Senders API

The Twilio Senders API allows you to:

Create (or register) a WhatsApp Sender
Fetch a specific WhatsApp Sender
Verify a WhatsApp Sender
Update a WhatsApp Sender
Delete a WhatsApp Sender

(warning)

Public Beta

The Twilio Senders API is currently available as a Public Beta product. This means that some features (including Twilio SDK support) for configuring your WhatsApp Sender via the REST API are not yet implemented, and others may be changed without notice before the product is declared Generally Available. Managing your WhatsApp Senders through the Twilio Console is Generally Available.

Public Beta products are not covered by a Twilio SLA.

The resources for sending and receiving Messages with a WhatsApp Sender are Generally Available.

(information)

Just trying to register a WhatsApp Sender?

Check out our tutorial on how to register a number in the Twilio Console using WhatsApp Self Sign-up.

Or if you really want to use an API, then we have another tutorial for you Registering WhatsApp Senders via API.

WhatsApp Sender resource

A WhatsApp Sender resource represents a phone number enabled on the WhatsApp Business Platform (formerly called the WhatsApp Business API). In order to send and/or receive WhatsApp messages using Twilio's APIs, including the Programmable Messaging API, a WhatsApp Sender with a status of ONLINE is required.

Resource URI

All URLs in this documentation use the following base URL:


_10https://messaging.twilio.com/v2/Channels

Create or register a WhatsApp Sender


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

(warning)

Prerequisites

Unless you are onboarding your customers as an ISV within the WhatsApp Tech Provider Program, you may only create / register WhatsApp Senders using the Senders API after you have registered your first WhatsApp Sender using WhatsApp Self Sign-up.

curl


_26## Create Sender
_26curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders" \
_26  -H "Content-Type: application/json; charset=utf-8" \
_26  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
_26  -d $'{
_26  "sender_id": "whatsapp:+15017122661",
_26  "profile": {
_26    "address": "101 Spear Street, San Francisco, CA",
_26    "emails": [
_26      "support@twilio.com"
_26    ],
_26    "vertical": "Other",
_26    "logo_url": "https://www.twilio.com/logo.png",
_26    "description": "We\'re excited to see what you build!",
_26    "about": "Hello! We are Twilio.",
_26    "name": "Twilio",
_26    "websites": [
_26      "https://twilio.com",
_26      "https://help.twilio.com"
_26    ]
_26  },
_26  "webhook": {
_26    "callback_method": "POST",
_26    "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
_26  }
_26}'

Output


_38  {
_38    "status": "CREATING",
_38    "sender_id": "whatsapp:+15017122661",
_38    "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38    "configuration": {
_38      "waba_id": "12345678912345"
_38    },
_38    "profile": {
_38      "about": "Hello! This is Twilio's official account.",
_38      "name": "Twilio",
_38      "vertical": "Other",
_38      "websites": [
_38        {
_38          "website": "https://twilio.com",
_38          "label": "Website"
_38        },
_38        {
_38          "website": "https://help.twilio.com",
_38          "label": "Website"
_38        }
_38      ],
_38      "address": "101 Spear Street, San Francisco, CA",
_38      "logo_url": "https://www.twilio.com/logo.png",
_38      "emails": [
_38        {
_38          "email": "support@twilio.com",
_38          "label": "Email"
_38        }
_38      ],
_38      "description": "We're excited to see what you build!"
_38    },
_38    "webhook": {
_38      "callback_method": "POST",
_38      "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
_38    },
_38    "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38    "properties": null
_38  }

Fetch a WhatsApp Sender


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

curl


_10## Fetch Sender
_10curl -X "GET" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
_10     -H "Content-Type: application/json; charset=utf-8" \
_10     -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

Output


_41{
_41  "status": "ONLINE",
_41  "sender_id": "whatsapp:+15017122661",
_41  "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41  "configuration": {
_41    "waba_id": "12345678912345"
_41  },
_41  "profile": {
_41    "about": "Hello! This is Twilio's official account.",
_41    "name": "Twilio",
_41    "vertical": "Other",
_41    "websites": [
_41      {
_41        "website": "https://twilio.com",
_41        "label": "Website"
_41      },
_41      {
_41        "website": "https://help.twilio.com",
_41        "label": "Website"
_41      }
_41    ],
_41    "address": "101 Spear Street, San Francisco, CA",
_41    "logo_url": "https://www.twilio.com/logo.png",
_41    "emails": [
_41      {
_41        "email": "support@twilio.com",
_41        "label": "Email"
_41      }
_41    ],
_41    "description": "We're excited to see what you build!"
_41  },
_41  "webhook": {
_41    "callback_method": "POST",
_41    "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
_41  },
_41  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41  "properties": {
_41    "messaging_limit": "1K Customers/24hr",
_41    "quality_rating": "HIGH"
_41  }
_41}

Verify a WhatsApp Sender


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

If you are not using a Twilio SMS-capable phone number, you may need to verify your Sender before it will show as ONLINE. When the API call is made to create a WhatsApp Sender, Meta will send an OTP by either SMS (default) or a Voice call. A WhatsApp Sender will then be in PENDING_VERIFICATION until you update the Sender with the OTP you received.

curl


_10## Verify Sender
_10curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
_10  -H 'Content-Type: text/plain; charset=utf-8' \
_10  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
_10  -d '{
_10        "configuration": {
_10          "verification_code": "123456"
_10        }
_10      }'

Output


_45{
_45    "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45    "sender_id": "whatsapp:+15558675310",
_45    "status": "VERIFYING",
_45    "profile": {
_45      "about": "Hello! This is Twilio's official account.",
_45      "name": "Twilio",
_45      "vertical": "Other",
_45      "websites": [
_45        {
_45          "website": "https://twilio.com",
_45          "label": "Website"
_45        },
_45        {
_45          "website": "https://help.twilio.com",
_45          "label": "Website"
_45        }
_45      ],
_45      "address": "101 Spear Street, San Francisco, CA",
_45      "logo_url": "https://www.twilio.com/logo.png",
_45      "emails": [
_45        {
_45          "email": "support@twilio.com",
_45          "label": "Email"
_45        }
_45      ],
_45      "description": "We're excited to see what you build!"
_45    },
_45    "webhook": {
_45      "callback_method": "POST",
_45      "callback_url": "https://demo.twilio.com/welcome/sms/reply/",  
_45      "fallback_method": "POST",
_45      "fallback_url": "",
_45      "status_callback_url": "",
_45      "status_callback_method": "POST"
_45    },
_45    "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45    "configuration": {
_45      "waba_id": "123456789"
_45    },
_45    "properties": {
_45      "messaging_limit": "1K Customers/24hr",
_45      "quality_rating": "HIGH"
_45    }
_45  }

Update a WhatsApp Sender


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

Update a WhatsApp Sender's inbound messaging webhooks and / or the public profile fields displayed to end users. Any omitted values will not be updated.

curl


_13## Update Sender
_13curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
_13  -H "Content-Type: application/json; charset=utf-8" \
_13  -u "$TWILIO_ACCOUNT_SID":"$TWILIO_AUTH_TOKEN" \
_13  -d $'{
_13    "webhook": {
_13      "callback_method": "POST",
_13      "callback_url": "https://demo.twilio.com/new_webhook"
_13    },
_13    "profile": {
_13      "description": "Twilio powers your customer engagement innovation.",
_13    }
_13  }'

Output


_41{
_41  "status": "ONLINE:UPDATING",
_41  "sender_id": "whatsapp:+15017122661",
_41  "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41  "configuration": {
_41    "waba_id": "12345678912345"
_41  },
_41  "profile": {
_41    "about": "Hello! This is Twilio's official account.",
_41    "name": "Twilio",
_41    "vertical": "Other",
_41    "websites": [
_41      {
_41        "website": "https://twilio.com",
_41        "label": "Website"
_41      },
_41      {
_41        "website": "https://help.twilio.com",
_41        "label": "Website"
_41      }
_41    ],
_41    "address": "101 Spear Street, San Francisco, CA",
_41    "logo_url": "https://www.twilio.com/logo.png",
_41    "emails": [
_41      {
_41        "email": "support@twilio.com",
_41        "label": "Email"
_41      }
_41    ],
_41    "description": "Twilio powers your customer engagement innovation."
_41  },
_41  "webhook": {
_41    "callback_method": "POST",
_41    "callback_url": "https://demo.twilio.com/new_webhook"
_41  },
_41  "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41  "properties": {
_41    "messaging_limit": "1K Customers/24hr",
_41    "quality_rating": "HIGH"
_41  }
_41}

Delete a WhatsApp Sender


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

(error)

Danger

This is not reversible! Use extreme care as Twilio Support will not be able to help if you accidentally delete a WhatsApp Sender that is being used in Production.

curl


_10curl -X "DELETE" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
_10  -u "$TWILIO_ACCOUNT_SID":"$TWILIO_AUTH_TOKEN"