Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this pageProducts used
Twilio WhatsApp Business Platform DocumentationWhatsApp

Senders API

The Twilio Senders API allows you to:

  • Create (or register) a WhatsApp Sender
  • Fetch a specific WhatsApp Sender
  • Verify a WhatsApp Sender
  • Update a WhatsApp Sender
  • Delete a WhatsApp Sender
(warning)

Public Beta

The Twilio Senders API is currently available as a Public Beta product. This means that some features (including Twilio SDK support) for configuring your WhatsApp Sender via the REST API are not yet implemented, and others may be changed without notice before the product is declared Generally Available. Managing your WhatsApp Senders through the Twilio Console(link takes you to an external page) is Generally Available.

Public Beta products are not covered by a Twilio SLA(link takes you to an external page).

The resources for sending and receiving Messages with a WhatsApp Sender are Generally Available.

(information)

Just trying to register a WhatsApp Sender?

Check out our tutorial on how to register a number in the Twilio Console using WhatsApp Self Sign-up.

Or if you really want to use an API, then we have the Registering WhatsApp Senders via API tutorial for you.

WhatsApp Sender resource

whatsapp-sender-resource page anchor

A WhatsApp Sender resource represents a phone number enabled on the WhatsApp Business Platform(link takes you to an external page) (formerly called the WhatsApp Business API). In order to send and/or receive WhatsApp messages using Twilio's APIs, including the Programmable Messaging API, a WhatsApp Sender with a status of ONLINE is required.

Resource URI

resource-uri page anchor

All URLs in this documentation use the following base URL:

https://messaging.twilio.com/v2/Channels

Create or register a WhatsApp Sender

create-or-register-a-whatsapp-sender page anchor
POST https://messaging.twilio.com/v2/Channels/Senders
(warning)

Prerequisites

Unless you are onboarding your customers as an ISV within the WhatsApp Tech Provider Program, you may only create / register WhatsApp Senders using the Senders API after you have registered your first WhatsApp Sender using WhatsApp Self Sign-up.

(information)

WhatsApp Profile Name

The profile name will be visible to your customers, and it must comply with certain regulations set by WhatsApp(link takes you to an external page). To make the creation of a WhatsApp Sender smoother, Twilio encourages you to limit the number of different display names for each brand.

1
## Create Sender

2
curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders" \

3
  -H "Content-Type: application/json; charset=utf-8" \

4
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \

5
  -d $'{

6
  "sender_id": "whatsapp:+15017122661",

7
  "profile": {

8
    "address": "101 Spear Street, San Francisco, CA",

9
    "emails": [

10
      "support@twilio.com"

11
    ],

12
    "vertical": "Other",

13
    "logo_url": "https://www.twilio.com/logo.png",

14
    "description": "We\'re excited to see what you build!",

15
    "about": "Hello! We are Twilio.",

16
    "name": "Twilio",

17
    "websites": [

18
      "https://twilio.com",

19
      "https://help.twilio.com"

20
    ]

21
  },

22
  "webhook": {

23
    "callback_method": "POST",

24
    "callback_url": "https://demo.twilio.com/welcome/sms/reply/"

25
  }

26
}'

Output

1
{

2
    "status": "CREATING",

3
    "sender_id": "whatsapp:+15017122661",

4
    "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
    "configuration": {

6
      "waba_id": "12345678912345"

7
    },

8
    "profile": {

9
      "about": "Hello! This is Twilio's official account.",

10
      "name": "Twilio",

11
      "vertical": "Other",

12
      "websites": [

13
        {

14
          "website": "https://twilio.com",

15
          "label": "Website"

16
        },

17
        {

18
          "website": "https://help.twilio.com",

19
          "label": "Website"

20
        }

21
      ],

22
      "address": "101 Spear Street, San Francisco, CA",

23
      "logo_url": "https://www.twilio.com/logo.png",

24
      "emails": [

25
        {

26
          "email": "support@twilio.com",

27
          "label": "Email"

28
        }

29
      ],

30
      "description": "We're excited to see what you build!"

31
    },

32
    "webhook": {

33
      "callback_method": "POST",

34
      "callback_url": "https://demo.twilio.com/welcome/sms/reply/"

35
    },

36
    "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

37
    "properties": null

38
  }

Fetch a WhatsApp Sender

fetch-a-whatsapp-sender page anchor
GET https://messaging.twilio.com/v2/Channels/Senders/{Sid}
1
## Fetch Sender

2
curl -X "GET" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \

3
     -H "Content-Type: application/json; charset=utf-8" \

4
     -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

Output

1
{

2
  "status": "ONLINE",

3
  "sender_id": "whatsapp:+15017122661",

4
  "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "configuration": {

6
    "waba_id": "12345678912345"

7
  },

8
  "profile": {

9
    "about": "Hello! This is Twilio's official account.",

10
    "name": "Twilio",

11
    "vertical": "Other",

12
    "websites": [

13
      {

14
        "website": "https://twilio.com",

15
        "label": "Website"

16
      },

17
      {

18
        "website": "https://help.twilio.com",

19
        "label": "Website"

20
      }

21
    ],

22
    "address": "101 Spear Street, San Francisco, CA",

23
    "logo_url": "https://www.twilio.com/logo.png",

24
    "emails": [

25
      {

26
        "email": "support@twilio.com",

27
        "label": "Email"

28
      }

29
    ],

30
    "description": "We're excited to see what you build!"

31
  },

32
  "webhook": {

33
    "callback_method": "POST",

34
    "callback_url": "https://demo.twilio.com/welcome/sms/reply/"

35
  },

36
  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

37
  "properties": {

38
    "messaging_limit": "1K Customers/24hr",

39
    "quality_rating": "HIGH"

40
  }

41
}

Verify a WhatsApp Sender

verify-a-whatsapp-sender page anchor
POST https://messaging.twilio.com/v2/Channels/Senders/{Sid}
1
## Verify Sender

2
curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \

3
  -H 'Content-Type: text/plain; charset=utf-8' \

4
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \

5
  -d '{

6
        "configuration": {

7
          "verification_code": "123456"

8
        }

9
      }'

Output

1
{

2
    "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
    "sender_id": "whatsapp:+15558675310",

4
    "status": "VERIFYING",

5
    "profile": {

6
      "about": "Hello! This is Twilio's official account.",

7
      "name": "Twilio",

8
      "vertical": "Other",

9
      "websites": [

10
        {

11
          "website": "https://twilio.com",

12
          "label": "Website"

13
        },

14
        {

15
          "website": "https://help.twilio.com",

16
          "label": "Website"

17
        }

18
      ],

19
      "address": "101 Spear Street, San Francisco, CA",

20
      "logo_url": "https://www.twilio.com/logo.png",

21
      "emails": [

22
        {

23
          "email": "support@twilio.com",

24
          "label": "Email"

25
        }

26
      ],

27
      "description": "We're excited to see what you build!"

28
    },

29
    "webhook": {

30
      "callback_method": "POST",

31
      "callback_url": "https://demo.twilio.com/welcome/sms/reply/",  

32
      "fallback_method": "POST",

33
      "fallback_url": "",

34
      "status_callback_url": "",

35
      "status_callback_method": "POST"

36
    },

37
    "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

38
    "configuration": {

39
      "waba_id": "123456789"

40
    },

41
    "properties": {

42
      "messaging_limit": "1K Customers/24hr",

43
      "quality_rating": "HIGH"

44
    }

45
  }

Update a WhatsApp Sender

update-a-whatsapp-sender page anchor
POST https://messaging.twilio.com/v2/Channels/Senders/{Sid}
1
## Update Sender

2
curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \

3
  -H "Content-Type: application/json; charset=utf-8" \

4
  -u "$TWILIO_ACCOUNT_SID":"$TWILIO_AUTH_TOKEN" \

5
  -d $'{

6
    "webhook": {

7
      "callback_method": "POST",

8
      "callback_url": "https://demo.twilio.com/new_webhook"

9
    },

10
    "profile": {

11
      "description": "Twilio powers your customer engagement innovation.",

12
    }

13
  }'

Output

1
{

2
  "status": "ONLINE:UPDATING",

3
  "sender_id": "whatsapp:+15017122661",

4
  "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "configuration": {

6
    "waba_id": "12345678912345"

7
  },

8
  "profile": {

9
    "about": "Hello! This is Twilio's official account.",

10
    "name": "Twilio",

11
    "vertical": "Other",

12
    "websites": [

13
      {

14
        "website": "https://twilio.com",

15
        "label": "Website"

16
      },

17
      {

18
        "website": "https://help.twilio.com",

19
        "label": "Website"

20
      }

21
    ],

22
    "address": "101 Spear Street, San Francisco, CA",

23
    "logo_url": "https://www.twilio.com/logo.png",

24
    "emails": [

25
      {

26
        "email": "support@twilio.com",

27
        "label": "Email"

28
      }

29
    ],

30
    "description": "Twilio powers your customer engagement innovation."

31
  },

32
  "webhook": {

33
    "callback_method": "POST",

34
    "callback_url": "https://demo.twilio.com/new_webhook"

35
  },

36
  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

37
  "properties": {

38
    "messaging_limit": "1K Customers/24hr",

39
    "quality_rating": "HIGH"

40
  }

41
}

Delete a WhatsApp Sender

delete-a-whatsapp-sender page anchor
DELETE https://messaging.twilio.com/v2/Channels/Senders/{Sid}
(error)

Danger

This is not reversible! Use extreme care as Twilio Support will not be able to help if you accidentally delete a WhatsApp Sender that is being used in Production.

1
curl -X "DELETE" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \

2
  -u "$TWILIO_ACCOUNT_SID":"$TWILIO_AUTH_TOKEN"

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.