Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI
On this pageProducts used
Looking for more inspiration?Visit the

Senders API - WhatsApp

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.

(warning)

Warning

Senders API v1 will be deprecated on September 1, 2026. After that date, the service accepts only Senders API v2 requests. Update your integration to use v2 following the snippets in this guide before the deprecation occurs.

Base URL

base-url page anchor
https://messaging.twilio.com/v2/Channels/Senders

Senders properties

senders-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
sidSID<XE>

Optional

Not PII

The SID of the sender.

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

Optional

Not PII

The status of the sender.

Possible values:
CREATINGONLINEOFFLINEPENDING_VERIFICATIONVERIFYINGONLINE:UPDATINGTWILIO_REVIEWDRAFTSTUBBED
senderIdstring

Optional

Not PII

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

Example: whatsapp:+15017122661
friendlyNamestring

Optional

Not PII

Optional display label for the sender in the Twilio Console.

configurationobject

Optional

Not PII

The configuration settings for creating a sender.

webhookobject

Optional

Not PII

The configuration settings for webhooks.

profileobject

Optional

Not PII

The profile information for the sender.

pendingDisplayNamestring

Optional

Not PII

WhatsApp only. The display name the most recent change applies to — awaiting Meta review, approved by Meta and awaiting re-registration, or, once pending_display_name_status is COMPLETED, the name now in effect (identical to name). Absent when no display name change has been made, and once a completed change stops being reported.

pendingDisplayNameStatusenum<string>

Optional

Not PII

WhatsApp only. The status of the most recent display name change. PENDING_REVIEW, APPROVED and DECLINED are reported by Meta. PIN_MISMATCH and REGISTRATION_FAILED mean Meta approved the name but it could not be applied; EXPIRED means Meta's 14-day window to apply an approved name elapsed. In all three cases, re-submit the same profile.name to retry. COMPLETED means the name was approved and applied — name now returns it. A COMPLETED change is reported for 14 days after it completes and is absent afterwards, so treat its presence as "recently completed" rather than a permanent flag; use pending_display_name_status_date to tell how recent. Absent when no display name change has been made.

Possible values:
PENDING_REVIEWAPPROVEDDECLINEDPIN_MISMATCHREGISTRATION_FAILEDEXPIREDCOMPLETED
pendingDisplayNameStatusDatestring<date-time>

Optional

Not PII

WhatsApp only. The date and time in UTC when pending_display_name_status last changed, specified in ISO 8601 format. Absent whenever pending_display_name_status is absent, so the three pending_display_name* fields are always present or absent together.

propertiesobject

Optional

Not PII

The additional properties for the sender.

offlineReasonsarray[object]

Optional

Not PII

The reasons why the sender is offline.

complianceobject

Optional

Not PII

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

urlstring<uri>

Optional

Not PII

The URL of the resource.

(information)

Compliance not applicable

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

Create and register a Sender

create-and-register-a-sender page anchor

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

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
senderIdstring
required
Not PII

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

Example: whatsapp:+15017122661
friendlyNamestring

Optional

Not PII

Optional display label for the sender in the Twilio Console.

configurationobject

Optional

Not PII

The configuration settings for creating a sender.

webhookobject

Optional

Not PII

The configuration settings for webhooks.

profileobject

Optional

Not PII

The profile information for the sender.

WhatsApp:Create and register a SenderLink to code sample: WhatsApp:Create and register a Sender
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 at twilio.com/console

5
// Provision API Keys at twilio.com/console/runtime/api-keys

6
// and set the environment variables. See http://twil.io/secure

7
// For local testing, you can use your Account SID and Auth token

8
const accountSid = process.env.TWILIO_ACCOUNT_SID;

9
const apiKey = process.env.TWILIO_API_KEY;

10
const apiSecret = process.env.TWILIO_API_SECRET;

11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

12


13
async function createChannelsSender() {

14
  const channelsSender = await client.messaging.v2.channelsSenders.create({

15
    sender_id: "whatsapp:+15551234",

16
  });

17


18
  console.log(channelsSender.sid);

19
}

20


21
createChannelsSender();

Response

Note about this 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
    "account_type": null

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
    "name": "Example Profile Name",

22
    "about": "This is an example about text.",

23
    "address": "123 Example St, Example City, EX 12345",

24
    "description": "This is an example description.",

25
    "emails": [

26
      {

27
        "email": "example@example.com",

28
        "label": "Email"

29
      },

30
      {

31
        "email": "example2@example.com",

32
        "label": "Email"

33
      }

34
    ],

35
    "logo_url": "https://logo_url.example.com",

36
    "vertical": "Automotive",

37
    "websites": [

38
      {

39
        "website": "https://website1.example.com",

40
        "label": "Website1"

41
      },

42
      {

43
        "website": "http://website2.example.com",

44
        "label": "Website2"

45
      }

46
    ]

47
  }

48
}

Monitoring errors during Sender creation

monitoring-errors-during-sender-creation page anchor

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 (Console(link takes you to an external page) | Legacy Console(link takes you to an external page)).

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

alarms page anchor

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

event-streams page anchor

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

retrieve-a-sender page anchor

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

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidSID<XE>
required
Not PII

The SID of the sender.

Pattern: ^XE[0-9a-fA-F]{32}$Min length: 34Max length: 34
WhatsApp: Retrieve a SenderLink to code sample: WhatsApp: Retrieve a Sender
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 at twilio.com/console

5
// Provision API Keys at twilio.com/console/runtime/api-keys

6
// and set the environment variables. See http://twil.io/secure

7
// For local testing, you can use your Account SID and Auth token

8
const accountSid = process.env.TWILIO_ACCOUNT_SID;

9
const apiKey = process.env.TWILIO_API_KEY;

10
const apiSecret = process.env.TWILIO_API_SECRET;

11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

12


13
async function fetchChannelsSender() {

14
  const channelsSender = await client.messaging.v2

15
    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

16
    .fetch();

17


18
  console.log(channelsSender.sid);

19
}

20


21
fetchChannelsSender();

Response

Note about this 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
    "account_type": null

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
    "name": "Example Profile Name",

22
    "about": "This is an example about text.",

23
    "address": "123 Example St, Example City, EX 12345",

24
    "description": "This is an example description.",

25
    "emails": [

26
      {

27
        "email": "email@email.com",

28
        "label": "Email"

29
      }

30
    ],

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
    "use_case": null,

48
    "phone_numbers": null

49
  },

50
  "compliance": null,

51
  "properties": {

52
    "quality_rating": "HIGH",

53
    "messaging_limit": "10K Customers/24hr"

54
  },

55
  "offline_reasons": null,

56
  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

57
}

Retrieve a list of Senders

retrieve-a-list-of-senders page anchor

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
channelstring
required
Not PII
pageSizeinteger<int64>

Optional

Not PII

The number of items to return per page. For WhatsApp, the default is 20.

Default: 50Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. Use only for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token provided by the API.

WhatsApp: Retrieve a list of SendersLink to code sample: WhatsApp: Retrieve a list of Senders
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 at twilio.com/console

5
// Provision API Keys at twilio.com/console/runtime/api-keys

6
// and set the environment variables. See http://twil.io/secure

7
// For local testing, you can use your Account SID and Auth token

8
const accountSid = process.env.TWILIO_ACCOUNT_SID;

9
const apiKey = process.env.TWILIO_API_KEY;

10
const apiSecret = process.env.TWILIO_API_SECRET;

11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

12


13
async function listChannelsSender() {

14
  const channelsSenders = await client.messaging.v2.channelsSenders.list({

15
    channel: "whatsapp",

16
    limit: 20,

17
  });

18


19
  channelsSenders.forEach((c) => console.log(c.sid));

20
}

21


22
listChannelsSender();

Response

Note about this 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

update-a-sender page anchor

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

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
sidSID<XE>
required
Not PII

The SID of the sender.

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

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
friendlyNamestring

Optional

Not PII

Optional display label for the sender in the Twilio Console.

configurationobject

Optional

Not PII

The configuration settings for creating a sender.

webhookobject

Optional

Not PII

The configuration settings for webhooks.

profileobject

Optional

Not PII

The profile information for the sender.

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 SenderLink to code sample: WhatsApp: Update a Sender
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 at twilio.com/console

5
// Provision API Keys at twilio.com/console/runtime/api-keys

6
// and set the environment variables. See http://twil.io/secure

7
// For local testing, you can use your Account SID and Auth token

8
const accountSid = process.env.TWILIO_ACCOUNT_SID;

9
const apiKey = process.env.TWILIO_API_KEY;

10
const apiSecret = process.env.TWILIO_API_SECRET;

11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

12


13
async function updateChannelsSender() {

14
  const channelsSender = await client.messaging.v2

15
    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

16
    .update({

17
      friendly_name: "friendly_name",

18
    });

19


20
  console.log(channelsSender.sid);

21
}

22


23
updateChannelsSender();

Response

Note about this response
1
{

2
  "sid": "XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "status": "VERIFYING",

4
  "sender_id": "whatsapp:+999999999XX",

5
  "friendly_name": "friendly_name",

6
  "compliance": null,

7
  "configuration": {

8
    "waba_id": "1234567XXX",

9
    "verification_method": "sms",

10
    "verification_code": null,

11
    "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

12
    "account_type": null

13
  },

14
  "webhook": {

15
    "callback_url": "https://callback.example.com",

16
    "callback_method": "POST",

17
    "fallback_url": "https://fallback.example.com",

18
    "fallback_method": "POST",

19
    "status_callback_url": "https://statuscallback.example.com",

20
    "status_callback_method": "POST"

21
  },

22
  "profile": {

23
    "about": "Example about text",

24
    "address": "123 Example St, Example City, EX 12345",

25
    "description": "Example description",

26
    "emails": [

27
      {

28
        "email": "email@email.com",

29
        "label": "Email"

30
      }

31
    ],

32
    "name": "Example Business",

33
    "logo_url": "https://logo_url.example.com",

34
    "vertical": "Automotive",

35
    "websites": [

36
      {

37
        "website": "https://website1.example.com",

38
        "label": "Website"

39
      },

40
      {

41
        "website": "http://website2.example.com",

42
        "label": "Website"

43
      }

44
    ],

45
    "banner_url": null,

46
    "privacy_url": null,

47
    "terms_of_service_url": null,

48
    "accent_color": null,

49
    "phone_numbers": null

50
  },

51
  "display_name_status": "updating"

52
}

Delete a Sender

delete-a-sender page anchor

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

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
sidSID<XE>
required
Not PII

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(link takes you to an external page).

WhatsApp: Delete a SenderLink to code sample: WhatsApp: Delete a Sender
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 at twilio.com/console

5
// Provision API Keys at twilio.com/console/runtime/api-keys

6
// and set the environment variables. See http://twil.io/secure

7
// For local testing, you can use your Account SID and Auth token

8
const accountSid = process.env.TWILIO_ACCOUNT_SID;

9
const apiKey = process.env.TWILIO_API_KEY;

10
const apiSecret = process.env.TWILIO_API_SECRET;

11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

12


13
async function deleteChannelsSender() {

14
  await client.messaging.v2

15
    .channelsSenders("XEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

16
    .remove();

17
}

18


19
deleteChannelsSender();

Update a WhatsApp sender display name

update-a-whatsapp-sender-display-name page anchor

You can update the display name of an existing WhatsApp Cloud API sender by using the Senders API. Twilio submits the change to Meta for review and, after approval, automatically applies the new name.

Overview and constraints

overview-and-constraints page anchor
  • Scope: Supported for WhatsApp Cloud API senders only.
  • Length: Display names must be 1–255 characters.
  • Rate limits: Meta allows a limited number of display-name changes per 30-day period.
  • Meta Approval window: Meta display name approvals remain valid for 14 days. After Meta approves the new name, Twilio asynchronously re-registers it within this window. No action is required on your part.

Submit a display-name change

submit-a-display-name-change page anchor

Send a POST request to the Senders endpoint that includes the new name in the profile object. You can submit profile.name by itself or with other profile properties.

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

2


3
Content-Type: application/json

4


5
{

6
  "profile": {

7
    "name": "New Business Name"

8
  }

9
}

Response

response page anchor

A valid request returns HTTP 202 Accepted. The response includes the submission status in profile.display_name_status.

1
{

2
  "sid": "XE0123456789abcdef0123456789abcdef",

3
  "profile": {

4
    "display_name_status": "updating"

5
  }

6
}
Immediate response statuses
immediate-response-statuses page anchor
StatusDescription
updatingRequest accepted and submitted to Meta for review, or routed to automatic re-registration.
no_changeSubmitted name matches the sender's current, verified display name. No update sent to Meta.
pending_reviewSubmitted name matches a name already pending Meta review.
errorThe display-name update failed, but other profile fields (if any) succeeded.

Check display-name status

check-display-name-status page anchor

Because Meta must review display-name updates, the operation is asynchronous. To check the current status, fetch the sender.

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

Example response while an update is in progress:

1
{

2
  "sid": "XE0123456789abcdef0123456789abcdef",

3
  "status": "ONLINE",

4
  "profile": {

5
    "name": "Current Business Name",

6
    "pending_display_name": "New Business Name",

7
    "pending_display_name_status": "PENDING_REVIEW",

8
    "pending_display_name_status_date": "2026-08-03T10:15:00Z"

9
  }

10
}

After Meta approves and Twilio applies the name, profile.name returns the new name and pending_display_name_status becomes COMPLETED. The pending_display_name* fields are still reported for 14 days after completion, then removed together.

GET response fields

get-response-fields page anchor
ParameterTypeDescription
profile.pending_display_namestringThe requested display name that is awaiting review or application.
profile.pending_display_name_statusstringThe status of the pending display-name update. See the table below.
profile.pending_display_name_status_datestring (ISO 8601)Timestamp of the last pending-status update.
Pending-status values
pending-status-values page anchor
StatusDescription
PENDING_REVIEWDisplay name submitted and awaiting Meta review.
APPROVEDMeta approved the display name; Twilio is applying the change.
DECLINEDMeta rejected the display name.
PIN_MISMATCHAutomatic re-registration failed because the 2FA PIN is invalid.
REGISTRATION_FAILEDAutomatic re-registration failed because of a system error.
EXPIREDMeta approved the display name, but the 14-day re-registration window elapsed before application.
COMPLETEDMeta approved the display name and Twilio applied it; profile.name now returns it. Reported for 14 days after completion.

Retry a failed or unapplied name

retry-a-failed-or-unapplied-name page anchor

If a request ends with PIN_MISMATCH or REGISTRATION_FAILED:

  1. Resolve the underlying issue (for example, reset the 2FA PIN in Meta's WhatsApp Business Manager).
  2. Re-submit the same profile.name with POST /v2/Channels/Senders/{Sid}.

Twilio detects an existing approval and immediately attempts to re-register the sender without consuming additional Meta quota or initiating a new review. If you submit the sender's current name together with other profile fields, the API returns no_change for the name but updates the other fields.

Resubmitting the current name does not cancel a pending name change. The review continues, and the name is updated if Meta approves the change. The API does not provide a cancel operation.```

Error codes

error-codes page anchor
HTTP statusTwilio error codeDescriptionAction required
400 Bad Request63124Display name rejected by Meta.Modify the name to meet Meta Display-Name Guidelines and retry.
409 Conflict63121A display-name change is already in progress for this sender.Wait for the existing review process to finish before submitting a new request.
400 Bad Request63100Validation error, such as an empty name, a name over 255 characters, or an empty request body.Correct the request and resubmit.
404 Not Found20404The sender was not found, or is not a registered WhatsApp Cloud API sender.Verify the Sender SID and that the sender is a registered Cloud API sender.
503 Service Unavailable63117Twilio could not reach Meta to submit the change.Retry after a short delay.

What's next?

whats-next page anchor