Skip to content Skip to navigation Skip to topbar

Page tools

On this pageProducts used

Looking for more inspiration?Visit the

Senders API - WhatsApp

(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.

The Senders API allows you to create, retrieve, update, and delete WhatsApp senders programmatically. A WhatsApp sender represents a phone number registered with WhatsApp Business through Twilio.

Base URL

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

Senders properties

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<XE>

Optional

The SID of the sender.

Pattern: ^XE[0-9a-fA-F]{32}$Min length: 34Max length: 34

statusenum<string>

Optional

The status of the sender.

Possible values:

CREATINGONLINEOFFLINEPENDING_VERIFICATIONVERIFYINGONLINE:UPDATINGTWILIO_REVIEWDRAFTSTUBBED

senderIdstring

Optional

The ID of the sender in whatsapp:<E.164_PHONE_NUMBER> format.

Example: whatsapp:+15017122661

configurationobject

Optional

The configuration settings for creating a sender.

Show configuration properties

webhookobject

Optional

The configuration settings for webhooks.

Show webhook properties

profileobject

Optional

The profile information for the sender.

Show profile properties

propertiesobject

Optional

The additional properties for the sender.

Show properties properties

offlineReasonsarray[object]

Optional

The reasons why the sender is offline.

Show offlineReasons properties

complianceobject

Optional

The KYC compliance information. This section consists of response to the request launch.

Show compliance properties

urlstring<uri>

Optional

The URL of the resource.

(information)

Compliance not applicable

For WhatsApp senders, the Compliance property is set to null.

Create and register a Sender

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

Request body parameters

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

senderIdstring

required

The ID of the sender in whatsapp:<E.164_PHONE_NUMBER> format.

Example: whatsapp:+15017122661

configurationobject

Optional

The configuration settings for creating a sender.

Show configuration properties

webhookobject

Optional

The configuration settings for webhooks.

Show webhook properties

profileobject

Optional

The profile information for the sender.

Show profile properties

WhatsApp:Create and register a Sender

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 createChannelsSender() {
11  const channelsSender = await client.messaging.v2.channelsSenders.create({
12    sender_id: "whatsapp:+15551234",
13  });
14
15  console.log(channelsSender.sid);
16}
17
18createChannelsSender();

Response

1{
2  "sid": "XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "status": "CREATING",
4  "sender_id": "whatsapp:+15551234",
5  "configuration": {
6    "waba_id": "1234567XXX",
7    "verification_method": "sms",
8    "verification_code": null,
9    "voice_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
10  },
11  "webhook": {
12    "callback_url": "https://callback.example.com",
13    "callback_method": "POST",
14    "fallback_url": "https://fallback.example.com",
15    "fallback_method": "POST",
16    "status_callback_url": "https://statuscallback.example.com",
17    "status_callback_method": "POST"
18  },
19  "profile": {
20    "name": "Example Profile Name",
21    "about": "This is an example about text.",
22    "address": "123 Example St, Example City, EX 12345",
23    "description": "This is an example description.",
24    "emails": [
25      {
26        "email": "example@example.com",
27        "label": "Email"
28      },
29      {
30        "email": "example2@example.com",
31        "label": "Email"
32      }
33    ],
34    "logo_url": "https://logo_url.example.com",
35    "vertical": "Automotive",
36    "websites": [
37      {
38        "website": "https://website1.example.com",
39        "label": "Website1"
40      },
41      {
42        "website": "http://website2.example.com",
43        "label": "Website2"
44      }
45    ]
46  }
47}

Monitoring errors during Sender creation

The POST /v2/Channels/Senders request creates and registers a WhatsApp sender asynchronously. If the request successfully creates a sender but fails to complete the registration, you can find more information in the Error Log in the Twilio Console.

An error log includes the following details:

Error description
Recommended actions to resolve it
Resource SID, which matches the Sender SID in your initial request

To monitor error logs, use Alarms or Event Streams.

Alarms

Set up an alarm to receive instant notifications by email, Twilio Console, or webhook when error thresholds are met within a specific timeframe.

For example, you can set alarms for the following common errors:

63104: Maximum number of phone numbers reached for your WhatsApp Business Account (WABA)
63110: The phone number is already registered on WhatsApp
63111: Sender's phone number or WABA returned "not found"
63100: Validation Error
63113: Sender Cannot Be Verified
63114: Too Many Verification Codes
63116: WhatsApp Sender failed to be automatically registered as OTP was not received

Event Streams

Set up an Event Stream to subscribe to Error Log events to receive notifications for every logged error. Each event payload includes the error code and a correlation_sid, which matches the Sender SID in the response of your initial request. This helps you track and resolve errors.

Retrieve a Sender

GET https://messaging.twilio.com/v2/Channels/Senders/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<XE>

required

The SID of the sender.

Pattern: ^XE[0-9a-fA-F]{32}$Min length: 34Max length: 34

WhatsApp: Retrieve a Sender

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 fetchChannelsSender() {
11  const channelsSender = await client.messaging.v2
12    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(channelsSender.sid);
16}
17
18fetchChannelsSender();

Response

1{
2  "sid": "XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "status": "ONLINE",
4  "sender_id": "whatsapp:+999999999XX",
5  "configuration": {
6    "waba_id": "1234567XXX",
7    "verification_method": null,
8    "verification_code": null,
9    "voice_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
10  },
11  "webhook": {
12    "callback_url": "https://callback.example.com",
13    "callback_method": "POST",
14    "fallback_url": "https://fallback.example.com",
15    "fallback_method": "POST",
16    "status_callback_url": "https://statuscallback.example.com",
17    "status_callback_method": "POST"
18  },
19  "profile": {
20    "name": "Example Profile Name",
21    "about": "This is an example about text.",
22    "address": "123 Example St, Example City, EX 12345",
23    "description": "This is an example description.",
24    "emails": [
25      {
26        "email": "email@email.com",
27        "label": "Email"
28      }
29    ],
30    "logo_url": "https://logo_url.example.com",
31    "vertical": "Automotive",
32    "websites": [
33      {
34        "website": "https://website1.example.com",
35        "label": "Website"
36      },
37      {
38        "website": "http://website2.example.com",
39        "label": "Website"
40      }
41    ],
42    "banner_url": null,
43    "privacy_url": null,
44    "terms_of_service_url": null,
45    "accent_color": null,
46    "phone_numbers": null
47  },
48  "compliance": null,
49  "properties": {
50    "quality_rating": "HIGH",
51    "messaging_limit": "10K Customers/24hr"
52  },
53  "offline_reasons": null,
54  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
55}

Retrieve a list of Senders

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

Query parameters

Property nameTypeRequiredPIIDescription

channelstring

required

pageSizeinteger<int64>

Optional

The number of items to return per page.

Default: 50Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. Use only for client state.

Minimum: 0

pageTokenstring

Optional

The page token provided by the API.

WhatsApp: Retrieve a list of Senders

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 listChannelsSender() {
11  const channelsSenders = await client.messaging.v2.channelsSenders.list({
12    channel: "whatsapp",
13    pageSize: 50,
14    limit: 20,
15  });
16
17  channelsSenders.forEach((c) => console.log(c.sid));
18}
19
20listChannelsSender();

Response

1{
2  "senders": [],
3  "meta": {
4    "page": 0,
5    "page_size": 10,
6    "first_page_url": "https://messaging.twilio.com/v2/Channels/Senders?PageSize=10&Page=0&Channel=whatsapp",
7    "previous_page_url": null,
8    "url": "https://messaging.twilio.com/v2/Channels/Senders?PageSize=10&Page=0&Channel=whatsapp",
9    "next_page_url": null,
10    "key": "senders"
11  }
12}

Update a Sender

POST https://messaging.twilio.com/v2/Channels/Senders/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<XE>

required

The SID of the sender.

Pattern: ^XE[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

configurationobject

Optional

The configuration settings for creating a sender.

Show configuration properties

webhookobject

Optional

The configuration settings for webhooks.

Show webhook properties

profileobject

Optional

The profile information for the sender.

Show profile properties

To update a WhatsApp sender's information, make a POST request to the Sender resource. To verify a WhatsApp sender, include the verification_code parameter in your request.

WhatsApp: Update a Sender

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 updateChannelsSender() {
11  const channelsSender = await client.messaging.v2
12    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({
14      configuration: {
15        waba_id: "waba_id",
16        verification_method: "sms",
17        verification_code: "verification_code",
18        voice_application_sid: "voice_application_sid",
19      },
20    });
21
22  console.log(channelsSender.sid);
23}
24
25updateChannelsSender();

Response

1{
2  "sid": "XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "status": "VERIFYING",
4  "sender_id": "whatsapp:+999999999XX",
5  "compliance": null,
6  "configuration": {
7    "waba_id": "1234567XXX",
8    "verification_method": "sms",
9    "verification_code": null,
10    "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
11  },
12  "webhook": {
13    "callback_url": "https://callback.example.com",
14    "callback_method": "POST",
15    "fallback_url": "https://fallback.example.com",
16    "fallback_method": "POST",
17    "status_callback_url": "https://statuscallback.example.com",
18    "status_callback_method": "POST"
19  },
20  "profile": {
21    "about": "Example about text",
22    "address": "123 Example St, Example City, EX 12345",
23    "description": "Example description",
24    "emails": [
25      {
26        "email": "email@email.com",
27        "label": "Email"
28      }
29    ],
30    "name": "Example Business",
31    "logo_url": "https://logo_url.example.com",
32    "vertical": "Automotive",
33    "websites": [
34      {
35        "website": "https://website1.example.com",
36        "label": "Website"
37      },
38      {
39        "website": "http://website2.example.com",
40        "label": "Website"
41      }
42    ],
43    "banner_url": null,
44    "privacy_url": null,
45    "terms_of_service_url": null,
46    "accent_color": null,
47    "phone_numbers": null
48  }
49}

Delete a Sender

DELETE https://messaging.twilio.com/v2/Channels/Senders/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<XE>

required

The SID of the sender.

Pattern: ^XE[0-9a-fA-F]{32}$Min length: 34Max length: 34

(information)

Turn off 2FA before re-registering a number

If you want to re-register the same number after deleting a sender, you must turn off Two-Factor Authentication (2FA) for the number in the WhatsApp Manager.

WhatsApp: Delete a Sender

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 deleteChannelsSender() {
11  await client.messaging.v2
12    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .remove();
14}
15
16deleteChannelsSender();