GuidesMessagingEssentials

Getting started with the Twilio Communications API

Prerequisites

Before you begin, ensure you have the following:

  1. A Twilio account: Sign up for a free account.
  2. An approved and compliant phone number or sender for SMS, MMS, WhatsApp, or RCS in your target region(s).
  3. Opt-out configuration as per your regional requirements: To configure advanced opt-out see the Customizing User’s Opt-in and Opt-out Experience with Advanced Opt-Out. This functionality is not currently supported natively in this API.

Authenticate your requests

The API uses basic authentication, just like our existing APIs. To authenticate, include the Basic Authentication header whose username:password pair is one of the following:

  • Your Account SID and Auth Token
  • Your API Key SID and API Key Secret

Send your first message

For this Private Beta release, the base URI for this API is https://comms.twilio.com/preview/. The API accepts JSON requests and returns JSON responses.

Now that you’re authenticated, let’s send your first message.

$curl -X POST 'https://comms.twilio.com/preview/Messages' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "<Your Purchased Twilio Phone Number>",
>        "channel": "SMS"
>    },
>    "to": [{
>        "address": "+12065551337",
>        "channel": "PHONE"
>    }],
>    "content": {
>        "text": "What day is it?"
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

You can deliver the same message to up to 10,000 recipients in a single API request by adding more entries to the to array.

$curl -X POST 'https://comms.twilio.com/preview/Messages' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "<Your Purchased Twilio Phone Number>",
>        "channel": "SMS"
>    },
>    "to": [
>        {
>            "address": "+19143188062",
>            "channel": "PHONE"
>        },
>        {
>            "address": "+19143188063",
>            "channel": "PHONE"
>        }
>    ],
>    "content": {
>        "text": "Ahoy!"
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Possible values for channel

When describing who you are sending to, the possible values are:

  • WHATSAPP
  • PHONE: The phone represents the text messaging app on a user’s device. This is the same identifier for both RCS and SMS/MMS messages.

When describing what numbers and addresses you are sending from, we split RCS and SMS, so that it is possible to specify when you want to use RCS, text message, or both. The possible values in those scenarios are:

  • SMS
  • RCS
  • WHATSAPP

See the Messages API reference for more details.

Check message request status with the Operation resource

After sending a message, especially to many recipients, retrieving the operation lets you monitor and manage the outcome, providing transparency and control over message delivery.

When you send a message with the Create Message endpoint, the response headers include an operationId. Use this value to track the delivery status of the message by sending a GET request to the Operations endpoint.

Request sample:

$curl -X GET "https://comms.twilio.com/preview/Messages/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8" \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Sample response:

1  {
2  "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
3  "status": "COMPLETED",
4  "stats": {
5    "total": 1,
6    "recipients": 1,
7    "attempts": 1,
8    "unaddressable": 0,
9    "queued": 0,
10    "sent": 0,
11    "scheduled": 0,
12    "delivered": 1,
13    "read": 0,
14    "undelivered": 0,
15    "failed": 0,
16    "canceled": 0
17  },
18  "createdAt": "2024-04-05T06:20:00Z",
19  "updatedAt": "2024-04-05T06:20:00Z"
20}

For more details, see the Fetch a Message Operation API reference.

Next steps