API Mechanics

API Versions

The Communications API is versioned.

The version is specified in the URL path, immediately after the hostname. Thus, all API endpoints are versioned together.

For example, in the URL https://comms.twilio.com/v1/Messages, the version is v1.

Mainline Versions (v1, v2, etc.)

Communications API versions are released periodically with monotonically increasing integers with ‘v’ prefix, e.g. v1.

For previous versions, see the API Changelog.

Operations & HTTP 202 Responses

The Communications API exposes several ‘factory’ API endpoints that create and start asynchronous jobs.

These API endpoints return an HTTP 202 (Accepted) success response which indicates that the workload has been accepted for processing.

• To track the progress of your workload, the API provides an HTTP response header operation-id.
• This header contains a unique identifier for the Operation that represents the async job.
• You can use the operation-id and operation-location headers to query the status of your job by fetching the corresponding Operation resource.
• Once the job is complete, the Operation will have status completed.

1
curl -X POST 'https://comms.twilio.com/preview/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "to": [{
5
        "address": "+12065551337",
6
        "channel": "phone"
7
    }],
8
    "content": {
9
        "text": "What day is it?"
10
    }
11
}'\
12
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \

1
GET https://comms.twilio.com/v1/Messages/Operations/comms_operation_01k4vge2fxe3ramtcdv1zx1s9s

1
GET https://comms.twilio.com/v1/Messages?operation_id=comms_operation_01k4vge2fxe3ramtcdv1zx1s9s

Related Resources

The Communications API provides a field on many API resources with the name related. This field contains an array of related resources, making it easier to navigate to associated data and understand relationships.

For example, when retrieving a Message resource, t he response contains a related field with the associated Session resource:

1
{
2
    "id": "comms_message_01k4vge32ce3ar18sy56svjjpb",
3
    "status": "delivered",
4
    "content": {
5
        "text": "Ahoy, world!"
6
    },
7
    ...
8
    "{{related}}": [
9
        {
10
            "id": "comms_session_96c975d029164690a4abcc47afcf4938",
11
            "name": "session"
12
        }
13
    ],
14
    "created_at": "2025-09-11T04:27:12Z",
15
    "updated_at": "2025-09-11T04:27:53Z"
16
}

Tags

Many resources in the Communications API have a tags field. This field contains up to 10 simple key-value pairs that the API user may write and read to associate custom metadata with their API resources.

For example, here is an Audience with tags:

Events & Webhooks

To handle asynchronous events, Twilio provides Event Streams API.

Event Streams API provides access to a unified stream of every interaction sent or received on Twilio.

Event Streams supports streaming events to multiple sinks (destinations) and different types of delivery mechanisms, including:

• Webhooks
• Amazon Kinesis
• Twilio Segment

To see a list of all events generated by the Communications API, visit Communications API Events.

Pagination

The Communications API uses cursor-based pagination for list endpoints.

When listing resources, the response includes a pagination field with the pagination information.

The pagination fields in a list Response are:

For example, when fetching a page of Messages, the response will contain:

1
{
2
    "messages": [
3
      ...
4
    ],
5
    "pagination": {
6
        "next": "1P_oxvlUFrvT0HSwOIjkxxW5hW9d9ynzrDWM5UHbTWkP7EBqWF2aYcu1CqHxjqC2IeSPdYD3cSjuo6qbrdM",
7
        "self": "/Messages?page_size=50&page_token=okCy7mKb-s4x3QOwnQPHmIQuEiinaoXy4OTUXF0msnPlH52cXmByhGnECL_ClHkCQiuVJ4oXDTuNiHllao4"
8
    }
9
}

The pagination query parameters are:

To retrieve the ‘next’ page of Messages get the value in the response body pagination.next field and issue:

1
GET https://comms.twilio.com/v1/Messages?page_token=1P_oxvlUFrvT0HSwOIjkxxW5hW9d9ynzrDWM5UHbTWkP7EBqWF2aYcu1CqHxjqC2IeSPdYD3cSjuo6qbrdM&page_size=50

The number of items to retrieve can be controlled with the page_size query parameter.

Errors

The Communications API uses standard HTTP status codes to indicate the success or failure of an API request.

Error HTTP Responses (400s and 500s)

When the Communications API returns an error (HTTP status code 4xx or 5xx), the response body contains the following field:

Each element of the errors array has the following fields:

For example when supplying an invalid value to the query parameter channel when listing Messages:

1
{
2
    "errors": [
3
        {
4
            "code": 400,
5
            "message": "The value 'phonee' is not recognized for the field 'channel'."
6
        }
7
    ],
8
    "status": 400
9
}

Console & Debugging

Support