Registering WhatsApp Senders via API

1. Note that Meta limits the number of WhatsApp Senders you may have in a single WhatsApp Business Account (WABA), and as a result, Twilio account or subaccount. (Twilio only supports a single WABA per unique ASID.) As a result, onboard numbers one by one, waiting until each one successfully returns an ONLINE status before moving to the next one.
2. If you are not using the WhatsApp Tech Provider Program to onboard customers as an ISV, you must first register a number using WhatsApp Self Sign-up in the Twilio Console.
3. Delete any numbers already registered on WhatsApp though either the business app or consumer app. Learn how to delete your WhatsApp account.
4. If using a Twilio Voice or non-Twilio phone number (BYON), make sure it is not associated with an IVR system (interactive voice response) or any computer-operated phone system that prohibits receiving an verification code via SMS or voice call.
5. Choose a display name carefully, as it must strictly follow Meta's display name guidelines.

You may purchase a Twilio number using our Phone Number APIs, or bring your own non-Twilio phone number (BYON). We recommend using a Twilio Phone Number that has SMS capabilities, as then Twilio will do the verification step automatically for you.

If using a Twilio Voice-only phone number, you will need to configure it to make sure you can receive the verification code, before moving on to the next step.

See our support article Which Twilio Phone Numbers are Compatible with WhatsApp? for more information.

Run the following cURL command, substituting the following required information:

• your phone number (in e.164 format) within the sender_id field
  • For AR (+54) and MX (+52) numbers, WhatsApp requires the format "+549" and "+521", respectively.
• your WhatsApp Sender's display name (profile.name)
• Twilio Account SID
• Twilio Auth Token

You may optionally include the following additional information:

• additional profile details that will be displayed publicly to end-users
• webhooks that Twilio will use to send inbound messages (webhooks.callbackUrl and webhooks.fallbackUrl) and outbound message status updates (webhooks.statusCallbackUrl)

This will create your WhatsApp sender in Twilio's system, add it to the WABA connected to your Twilio account, and trigger the verification code from Meta.

Make a note of the WhatsApp Sender's SID (starting with an XE), as you will need it in the next step.

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
}'

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
  }

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
  "configuration": {
8
    "verification_method": "voice"
9
  },
10
  "profile": {
11
    "address": "101 Spear Street, San Francisco, CA",
12
    "emails": [
13
      "support@twilio.com"
14
    ],
15
    "vertical": "Other",
16
    "logo_url": "https://www.twilio.com/logo.png",
17
    "description": "We\'re excited to see what you build!",
18
    "about": "Hello! We are Twilio.",
19
    "name": "Twilio",
20
    "websites": [
21
      "https://twilio.com",
22
      "https://help.twilio.com"
23
    ]
24
  },
25
  "webhook": {
26
    "callback_method": "POST",
27
    "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
28
  }
29
}'

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
  }

Once you receive the verification code, you must update your WhatsApp Sender with it by making the following cURL command substituing the code you received.

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
      }'

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
  }

In order to verify that the WhatsApp Sender was successfully registered, you will need to make the following request to fetch the WhatsApp Sender. In the response, check the status to make sure that it shows as ONLINE. If it still notes that it is PENDING_VERIFICATION then you will need to return to Step 2 in order to request another verification code.

Once the WhatsApp Sender shows as ONLINE you may begin sending and receiving messages on WhatsApp using the Twilio APIs. Congrats!

Last updated July 2024