Register WhatsApp senders using the Senders API

(new)

Public Beta

The Senders API is currently available as a Public Beta product and the information contained in this document is subject to change. This means that some features aren't yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products aren't covered by the Twilio Support Terms or Twilio Service Level Agreement.

The Senders API isn't a HIPAA Eligible Service or PCI compliant and shouldn't be enabled in workflows that are subject to HIPAA or PCI.

Learn how direct customers can register WhatsApp senders using the Twilio Senders API.

Note: If you're an Independent Software Vendor (ISV), join the WhatsApp Tech Provider Program and follow the WhatsApp sender registration process for ISVs.

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

You must register your first WhatsApp sender using WhatsApp Self Sign-up in the Twilio Console. Learn how to register a WhatsApp sender using WhatsApp Self Sign-up.

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

WhatsApp Self Sign-up
Senders API

(information)

When to use Self Sign-up 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 WhatsApp Self Sign-up for a small number of senders.

Register WhatsApp senders 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 every phone number registered with WhatsApp before that number can send or receive messages. Meta verifies ownership through SMS or voice call OTPs.

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

Phone number type	Capabilities	OTP verification code delivery
Twilio	SMS	Twilio handles the verification automatically during the registration process
	Voice	Configure the phone number to receive the OTP verification code via email
Non-Twilio	SMS	Receive the OTP verification code via SMS
	Voice	Receive the OTP verification code via voice call

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 by 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 that 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 by 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  }

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}

Make sure your phone number meets all requirements and can 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 you resolve common issues when you register a WhatsApp sender.

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 in a browser (include the 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: Open 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, turn off Two-Factor Authentication (2FA) for the number on the WhatsApp Business Platform and register a WhatsApp sender with the number. Contact your Solution Partner if you can't turn off 2FA by yourself.

Learn more about migrating phone numbers and WhatsApp senders. 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've reached Meta's maximum number of OTP verification attempts.

To resolve this issue:

Wait a few minutes.
Check the Error logs for any errors and follow the recommended actions.
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 when registration is complete, which 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 using the Senders API

Public Beta

Phone number requirements

Display name requirements

Register the first WhatsApp sender

When to use Self Sign-up or Senders API

Register WhatsApp senders 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`