Register WhatsApp senders

(new)

Public Beta

The Senders API is in Public Beta. Twilio SDKs and some Senders API features for managing WhatsApp senders aren't yet supported. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support.

Managing WhatsApp senders in the Twilio Console is Generally Available.

Learn how Independent Software Vendors (ISVs) can register WhatsApp senders for their customers using Meta's Embedded Signup or the Senders API.

Phone number requirements

You can use either a Twilio phone number or a non-Twilio phone number to register a WhatsApp sender.

The phone number must meet the WhatsApp compatibility requirements.
The phone number must not already be registered with WhatsApp. Learn how to check if a phone number is registered with WhatsApp and how to use an already registered phone number.
If the phone number is non-Twilio, it must be able to receive SMS or voice calls.
- If the phone number is registered with an Interactive Voice Response (IVR) system or a computer-operated phone system, you can't receive One-Time Passwords (OTPs).
- If the phone number is only available for outbound messages or calls, you can't use it to register a WhatsApp sender because Meta can't deliver OTPs.

Display name requirements

The WhatsApp sender display name (profile.name) must comply with Meta's display name guidelines. Meta reviews the name after registration. Before bulk registration, register a single sender first to confirm that the name is accepted. If Meta rejects the name, the phone number is limited to 250 business-initiated messages per 24-hour period, and Meta might disconnect the sender.

Register the first WhatsApp sender

Your customer must register their first WhatsApp sender using Meta's Embedded Signup. The process involves the following steps:

You integrate Meta's Embedded Signup into your application through the Tech Provider Program.
Your customer registers the first WhatsApp sender using the Embedded Signup.
As part of the registration process, your customer will create a WhatsApp Business Account (WABA).
You create a Twilio subaccount for your customer and connect their WABA to the subaccount.

Register additional WhatsApp senders

After registering the first WhatsApp sender, there are two ways to register additional WhatsApp senders:

Embedded Signup: Your customers register additional senders using the Embedded Signup in your application. If you have access to your customer's WABA, you can register WhatsApp senders on their behalf.
Senders API: You register additional WhatsApp senders on behalf of your customers using the Senders API.

(information)

When to use Embedded Signup or Senders API

Twilio recommends using the API only when you need to onboard a large number of senders across many accounts (bulk registration). Use the Embedded Signup for a small number of senders.

You or your customers can register additional WhatsApp senders using the Embedded Signup flow they used to register their first WhatsApp sender.

(warning)

Session timeout

The Embedded Signup flow times out after 60 minutes of inactivity. Progress isn't saved and you must restart the registration process.

Click the Login with Facebook button in your application's UI.
Log in to Meta Business Manager.
Review the permissions Meta requests for your WABA and business assets, then continue.
Choose your Meta Business Portfolio and WABA.
For each sender, you must select the same Meta Business Portfolio and WABA that you used for the first WhatsApp sender. Selecting a different Meta Business Portfolio or WABA will result in an error.
(information)
Info
You can't use multiple WABAs in one Twilio account.
Enter the phone number you want to register and complete the OTP verification via SMS or voice call.
Review and accept the access/permissions required by the embedded flow.
Complete the flow and close the window once Meta confirms successful sender registration.

Using the Senders API

The Senders API allows you to register additional WhatsApp senders on behalf of your customers. This is useful when you have many customers and each customer needs multiple senders created across many Twilio subaccounts.

Meta requires ownership verification for all phone numbers registered with WhatsApp before they can send or receive messages. Meta verifies ownership through SMS or voice call OTPs. For Twilio phone numbers with SMS capabilities, Twilio handles the verification automatically during the registration process.

The registration process depends on the phone number type (Twilio or non-Twilio) and capabilities (SMS or voice) to receive the OTP for verification.

SMS: Twilio phone numbersVoice: Twilio phone numbersSMS: Non-Twilio phone numberVoice: Non-Twilio phone number

Buy a Twilio phone number that has SMS capabilities.
Purchase a phone number
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createIncomingPhoneNumber() {
11
const incomingPhoneNumber = await client.incomingPhoneNumbers.create({
12
phoneNumber: "+14155552344",
13
});
14

15
console.log(incomingPhoneNumber.accountSid);
16
}
17

18
createIncomingPhoneNumber();
- You can find available Twilio phone numbers using the AvailablePhoneNumbers Local, AvailablePhoneNumbers Mobile, and AvailablePhoneNumbers TollFree resources.
- Alternatively, you can buy a Twilio phone number in the Twilio Console.
To register a WhatsApp sender, make a POST /v2/Channels/Senders request. The following properties are required in the request body:
- sender_id: The phone number to register as a WhatsApp sender in E.164 format
- profile.name: The WhatsApp sender display name
For additional properties, see the Senders API documentation.

(warning)
Too many requests
Allow several minutes between Senders API requests. Too many requests in a short period might result in errors.
Register a WhatsApp sender (SMS: Twilio phone numbers)
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
}
This request creates a WhatsApp sender in Twilio's system, adds it to the WABA connected to your Twilio account, and completes the phone number verification.

To confirm the WhatsApp sender is registered, make a GET v2/Channels/Senders/{Sid} request and check if status is ONLINE.
Note: Immediately after registration, the status value will be OFFLINE. Wait a few minutes, then make the request again.

Confirm WhatsApp sender registration

1## Fetch Sender
2curl -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}

Buy a Twilio phone number that has voice capabilities.

Purchase a phone number

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createIncomingPhoneNumber() {
11  const incomingPhoneNumber = await client.incomingPhoneNumbers.create({
12    phoneNumber: "+14155552344",
13  });
14
15  console.log(incomingPhoneNumber.accountSid);
16}
17
18createIncomingPhoneNumber();

You can find available Twilio phone numbers using the AvailablePhoneNumbers Local, AvailablePhoneNumbers Mobile, and AvailablePhoneNumbers TollFree resources.
Alternatively, you can buy a Twilio phone number in the Twilio Console.

Configure the phone number so it can receive OTP verification codes via voice call.
1. Open the Active Numbers page.
2. Click your Twilio phone number.
3. In the Voice Configuration section, in the Configure with row, select Webhook, TwiML Bin, Function, Studio Flow, Proxy Service.
4. In the A call comes in row, select Webhook and set the URL to https://twimlets.com/voicemail?Email=<YOUR_EMAIL_ADDRESS>. For example, https://twimlets.com/voicemail?Email=support@example.com.
  Note: The Voicemail Twimlet transcribes incoming calls and sends the transcription to your email address. This allows you to receive OTPs via email.

To register a WhatsApp sender, make a POST /v2/Channels/Senders request. The following properties are required in the request body:

sender_id: The phone number to register as a WhatsApp sender in E.164 format
profile.name: The WhatsApp sender display name

For additional properties, see the Senders API documentation.

(warning)

Too many requests

Allow several minutes between Senders API requests. Too many requests in a short period might result in errors.

1## Create Sender
2curl -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}'

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  }

This request creates a WhatsApp sender in Twilio's system, adds it to the WABA connected to your Twilio account, and triggers the OTP from Meta.

To verify the phone number, make a POST /v2/Channels/Senders/{Sid} request with the OTP received via email.

Verify the phone number

1## Verify Sender
2curl -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        "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  }

Confirm WhatsApp sender registration

1## Fetch Sender
2curl -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}

Make sure your phone number meets all requirements and is able to receive SMS messages.

To register a WhatsApp sender, make a POST /v2/Channels/Senders request. The following properties are required in the request body:

sender_id: The phone number to register as a WhatsApp sender in E.164 format
profile.name: The WhatsApp sender display name

For additional properties, see the Senders API documentation.

(warning)

Too many requests

Allow several minutes between Senders API requests. Too many requests in a short period might result in errors.

1## Create Sender
2curl -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  }

This request creates a WhatsApp sender in Twilio's system, adds it to the WABA connected to your Twilio account, and triggers the OTP from Meta.

To verify the phone number, make a POST /v2/Channels/Senders/{Sid} request with the OTP received via SMS.

Verify the phone number

1## Verify Sender
2curl -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        "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  }

Confirm WhatsApp sender registration

1## Fetch Sender
2curl -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}

Make sure your phone number meets all requirements and is able to receive voice calls.

To register a WhatsApp sender, make a POST /v2/Channels/Senders request. The following properties are required in the request body:

sender_id: The phone number to register as a WhatsApp sender in E.164 format
profile.name: The WhatsApp sender display name

For additional properties, see the Senders API documentation.

(warning)

Too many requests

Allow several minutes between Senders API requests. Too many requests in a short period might result in errors.

1## Create Sender
2curl -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}'

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  }

This request creates a WhatsApp sender in Twilio's system, adds it to the WABA connected to your Twilio account, and triggers the OTP from Meta.

To verify the phone number, make a POST /v2/Channels/Senders/{Sid} request with the OTP received via a voice call.

Verify the phone number

1## Verify Sender
2curl -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        "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  }

Confirm WhatsApp sender registration

1## Fetch Sender
2curl -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}

Troubleshooting

The following troubleshooting steps can help resolve common issues with WhatsApp sender registration.

I want to check if a phone number is registered with WhatsApp

To check if a phone number is registered with WhatsApp, use one of the following methods:

Send a test message: Open https://wa.me/<PHONE_NUMBER>?text=hi (include country code without +, for example, 15551234). If the number is registered, you'll receive "hi" in WhatsApp.
Search contacts: In WhatsApp, tap New Chat > New Contact and enter the phone number. If the number is registered, you'll see "This phone number is on WhatsApp".
Check error logs: Check the Error Logs page in the Twilio Console. If the number is registered, you'll see Error 63110.

I want to use an already registered phone number

To use a phone number that's already registered with WhatsApp:

If registered with WhatsApp or WhatsApp Business app: Delete the WhatsApp account to make the phone number available for the WhatsApp Business Platform with Twilio.
If registered with another WhatsApp Business Platform: In the WhatsApp Manager, disable Two-Factor Authentication (2FA) for the number on the WhatsApp Business Platform. Contact the WhatsApp Business Platform owner if you can't disable 2FA by yourself.

If you need further assistance, contact Twilio Support.

I can't use Argentina or Mexico phone numbers

For Argentina phone numbers (+54): Add a 9 after the country code and remove the prefix 15 (For example, +549 XXX XXX XXXX).
For Mexico phone numbers (+52): Add a 1 after the country code (For example, +521 XX XXXX XXXX).

Learn more about WhatsApp's international phone number format.

I'm not receiving an OTP via SMS

You might not receive an OTP via SMS for the following reasons:

The OTP delivery is delayed.
You reached Meta's maximum number of OTP verification attempts.

To resolve this issue:

Wait a few minutes.
Resend an OTP by making another POST /v2/Channels/Senders request.
If you don't receive the OTP after several attempts, contact Twilio Support.

Alternatively, you can try the voice method for verification.

The `status` field remains `OFFLINE`

The status field briefly shows as OFFLINE after registration. The status field changes to ONLINE once registration is complete. This typically takes a few minutes. If the status field remains OFFLINE after that, follow these steps:

Confirm the phone number meets all requirements.
Confirm the display name follows Meta's display name guidelines.
Check the Error logs for any errors and follow the recommended actions.
Check your WABA status on WhatsApp Manager.
If you still see OFFLINE, contact Twilio Support.

Register WhatsApp senders

Public Beta

Phone number requirements

Display name requirements

Register the first WhatsApp sender

Register additional WhatsApp senders

When to use Embedded Signup or Senders API

Using the Embedded Signup in your application

Session timeout

Info

Using the Senders API

Too many requests

Output

Output

Too many requests

Output

Output

Output

Too many requests

Output

Output

Output

Too many requests

Output

Output

Output

Troubleshooting

I want to check if a phone number is registered with WhatsApp

I want to use an already registered phone number

I can't use Argentina or Mexico phone numbers

I'm not receiving an OTP via SMS

The status field remains OFFLINE

The `status` field remains `OFFLINE`