Skip to contentSkip to navigationSkip to topbar
On this page

v1 Reference


(error)

Danger

Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here(link takes you to an external page).

If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.

(error)

Danger

This is reference documentation for the v1 REST API, which has been deprecated. You should use the current v2 REST API.

The Programmable Chat REST API allows you to control your Chat applications from the server in much the same way you can from the client, except from a service perspective rather than a 1st person one. You can create channels, send messages, and query the state of your messaging applications using the resources in this REST API.


API Base URL

api-base-url page anchor

All URLs in the reference documentation use the following base URL:

https://chat.twilio.com/v1

All requests to the Programmable Chat REST API are served over HTTPS. Unencrypted HTTP is not supported.


HTTP requests to the REST API are protected with HTTP Basic authentication like
other REST APIs provided by Twilio. To learn more about how Twilio handles
authentication, please refer to our security documentation.
In short, you will use your Twilio account SID as the username and your
auth token as the password for HTTP Basic authentication.

1
curl -G https://chat.twilio.com/v1/Services \
2
-u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'

You can find your account SID and auth token in the admin console. Alternately, you can also use API keys and secrets to authenticate REST API requests - you can manage API key pairs in the console also.


You can use the Twilio Helper Libraries to interact with the Programmable Chat REST endpoints.

Programmable Chat is available in the Next Gen Release builds of the Twilio Helper Libraries.


Here are the resources you will be interacting with via the REST API:

ResourceDescription
ChannelsA "chat room" - a scope in which messages can be sent or received
CredentialsCredentials used by Twilio to integrate with Google Cloud Messaging(link takes you to an external page) or Apple Push Notifications Service(link takes you to an external page)
InvitesRepresents all pending invitations to Users within the Service instance to become a Member of the Channel.
MembersMembers of a Channel
MessagesMessages sent to a Channel
RolesDefine actions users are allowed to take in a Channel or Service scope
ServicesA service roughly maps to a Chat app. Channels, Users, Credentials, and all the REST (see what I did there?) are scoped to a Service. Can define webhook URLs for events in a service
UsersA user with a unique identity within the scope of your Service