Programmable Messaging for WhatsApp curl Quickstart

Before you can send a WhatsApp message from your web language, you'll need to sign up for a Twilio account or sign into your existing account and activate the Twilio Sandbox for WhatsApp. It allows you to prototype with WhatsApp immediately using a shared phone number, without waiting for a dedicated number to be approved by WhatsApp.

To get started, select a number from the available sandbox numbers to activate your sandbox.

Expand image

Be sure to take note of the phone number you choose in the Sandbox. You will need this later when we're ready to send some messages.

Before you can send any messages, you'll need to gather your Twilio account credentials. You can find these in the Twilio Console.

• Account SID - Used to authenticate REST API requests
• Auth Token - Used to authenticate REST API requests

Expand image

For all of our code snippets and curl examples, you will need to authenticate with the Account SID and Auth Token.

curl should work by default in a recent Linux or macOS terminal. If you are using Windows, you can find curl packages already compiled here.

Send "join <your sandbox keyword>" to your Sandbox number in WhatsApp to join your Sandbox, and we'll reply with a confirmation that you've joined. Your sandbox keyword can be found in the console.

Once you join, you will only receive messages from your specific Sandbox. To disconnect from the sandbox, you can reply to the message from WhatsApp with sandbox stop, or switch to a different sandbox by messaging join <other sandbox keyword>.

Expand image

To invite someone else to your sandbox, create a link with the following format containing the opt-in message and send it to them: whatsapp://send?phone=<Your Sandbox Number>&text=<your URL-encoded sandbox keyword>

You can also create a QR code with the link format above that users can scan on their phone to opt-in to your sandbox.

Expand image

To send a message, use the following code and replace the To parameter with the phone number for your personal WhatsApp account in the E.164 format. (If you haven't already, install WhatsApp on your device and register for an account.) For the From parameter, be sure to include the whatsapp: channel identifier before the Sandbox number in E.164 format.

For the From parameter, you need your Sender ID which should be shown on the installed channel in the Twilio Console, as shown previously.

1
EXCLAMATION_MARK='!'
2
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
3
--data-urlencode "To=whatsapp:+15005550006" \
4
--data-urlencode "From=whatsapp:+14155238886" \
5
--data-urlencode "Body=Hello there$EXCLAMATION_MARK" \
6
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "api_version": "2010-04-01",
4
  "body": "Hello there!",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "whatsapp:+14155238886",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "whatsapp:+15005550006",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

When someone replies to one of your messages, you will receive a webhook request from Twilio.

You can configure webhooks by connecting your Sandbox to an app you've already built for handling incoming messages, or build a new one for WhatsApp messages.

Expand image

This webhook request also supports TwiML (the Twilio Markup Language) just like a regular Twilio SMS request.

Although we're sure it's possible to run a server from your command line, we prefer you use a language with more of a web focus at this point. To handle this request, you need to set up a web application and expose it to the internet. Check out the SMS Quickstarts to see how to respond to a message and generate TwiML in your language of (second?) choice.

If you're a Node developer, you can also host this web application with Twilio Functions.

Because the Twilio WhatsApp API is essentially the same as the Twilio Programmable Messaging API, all of the documentation for that API applies to your apps sending and receiving messages with WhatsApp. To dive deeper with a WhatsApp integration, see the WhatsApp documentation overview as well as the API Reference.

Here are some areas you might like to explore next.

• Send appointment reminders
• Create SMS conversations
• The Programmable Messaging API overview

We can't wait to see what kind of WhatsApp integration you build!