Overview of the WhatsApp Business Platform with Twilio

WhatsApp has 3 messaging products:

• WhatsApp Consumer app, with users around the globe;
• WhatsApp Business app, generally used by small businesses and micro businesses; and
• WhatsApp Business Platform, previously known as the WhatsApp Business API

Twilio offers access to the WhatsApp Business Platform. Developers can use WhatsApp with all of Twilio's products, including the Programmable Messaging API, Conversations API, Twilio Flex and Studio. For more information, please see WhatsApp Business Accounts with Twilio.

WhatsApp requires that your application implement explicit user opt-ins to deliver messages over WhatsApp. You may gather this opt-in information either via a web page or a mobile app, such as during your application's sign-up flow, in your application's account settings, via SMS, etc. WhatsApp also requires businesses to respect opt-out requests from end users to maintain high number quality.

Please note that sending messages to end users without an opt-in may result in users blocking your business and may ultimately lead to the suspension of your WhatsApp Business account.

On WhatsApp, users message each other using their phone numbers as identifiers. To send and receive WhatsApp messages using the Twilio Programmable Messaging API, you'll need a phone number as well. The Twilio API addresses WhatsApp users and your numbers, using the following prefixed address format:

whatsapp:<E.164 formatted phone number>

(E.164 is an international telephone number format; you will see it often in the strings that represent Twilio phone numbers.)

To use WhatsApp messaging in production apps, you must enable WhatsApp on your Twilio number. For a step-by-step walkthrough of the process, visit our Self-Signup Guide for WhatsApp. If you are registering for WhatsApp on behalf of a third party, such as one of your clients, then you may be an Independent Software Vendor (ISV) - please follow our Guided Signup process instead.

For information about using a non-Twilio number with WhatsApp, check out our Support guide Can I activate my own phone number for WhatsApp on Twilio?

WhatsApp uses your Meta Business Manager account to identify your business and associate your WhatsApp Business Account (WABA) with it. To scale with WhatsApp, you will also need to verify your Meta Business Manager account. You can create or connect your Meta Business Manager account through Twilio's Self-Signup process in the Console.

If you are an ISV, you will need to provide Twilio with your Meta Business Manager ID before you or your end clients begin onboarding. If you do not already have a Meta Business Manager account, follow Facebook's instructions to create one. Your Meta Business Manager ID can be found in the "Business Info" section under Business Settings.

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_14

// Download the helper library from https://www.twilio.com/docs/node/install

_14

// Find your Account SID and Auth Token at twilio.com/console

_14

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

_14

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_14

const authToken = process.env.TWILIO_AUTH_TOKEN;

_14

const client = require('twilio')(accountSid, authToken);

_14

_14

client.messages

_14

.create({

_14

from: 'whatsapp:+14155238886',

_14

body: 'Hello, there!',

_14

to: 'whatsapp:+15005550006'

_14

})

_14

.then(message => console.log(message.sid));

Output

_24

{

_24

"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"api_version": "2010-04-01",

_24

"body": "Hello, there!",

_24

"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"direction": "outbound-api",

_24

"error_code": null,

_24

"error_message": null,

_24

"from": "whatsapp:+14155238886",

_24

"num_media": "0",

_24

"num_segments": "1",

_24

"price": null,

_24

"price_unit": null,

_24

"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"status": "queued",

_24

"subresource_uris": {

_24

"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"

_24

},

_24

"to": "whatsapp:+15005550006",

_24

"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"

_24

}

Send a freeform WhatsApp message with media

Send a freeform media message within the 24-hour session

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_15

// Download the helper library from https://www.twilio.com/docs/node/install

_15

// Find your Account SID and Auth Token at twilio.com/console

_15

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

_15

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_15

const authToken = process.env.TWILIO_AUTH_TOKEN;

_15

const client = require('twilio')(accountSid, authToken);

_15

_15

client.messages

_15

.create({

_15

body: `Here's that picture of an owl you requested.`,

_15

mediaUrl: ['https://demo.twilio.com/owl.png'],

_15

from: 'whatsapp:+14155238886',

_15

to: 'whatsapp:+15017122661'

_15

})

_15

.then(message => console.log(message.sid));

Output

_24

{

_24

"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"api_version": "2010-04-01",

_24

"body": "Here's that picture of an owl you requested.",

_24

"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",

_24

"direction": "outbound-api",

_24

"error_code": null,

_24

"error_message": null,

_24

"from": "whatsapp:+14155238886",

_24

"num_media": "0",

_24

"num_segments": "1",

_24

"price": null,

_24

"price_unit": null,

_24

"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

_24

"status": "queued",

_24

"subresource_uris": {

_24

"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"

_24

},

_24

"to": "whatsapp:+15017122661",

_24

"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"

_24

}

To receive real-time status updates for outbound messages, you can choose to set a Status Callback URL. Twilio sends a request to this URL each time your message status changes to one of the transition values in the Message Status Callback Event Flow diagram.

You can set the Status Callback URL in the Console, or when you send an individual outbound message, by including the StatusCallback parameter. You can set the status callback URL in different parts of the Twilio Console depending on your messaging setup:

• For the WhatsApp Sandbox or an individual WhatsApp Sender -read WhatsApp and other messaging channels for additional properties that Twilio sends to your callback URL
• For a Messaging Service (under the Integration settings for a specific Messaging Service) - read the status callback with a Messaging service guide for configuration options

When you set the Status Callback URL, Twilio sends a POST request to that URL, including the message sid (the Message's Unique identifier) and other standard request parameters as well as a status and an associated error_code if any. Refer to the API Reference for the Message Resource for a list of parameters that Twilio sends to your callback URL.