Twilio Conversations
Lets an agent run omnichannel message threads on Twilio Conversations: list and open conversations, add SMS, WhatsApp or chat participants, read the message history, send replies and close threads when done. Curated from Twilio's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with Twilio Conversations via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v1/Conversations |
listConversations | List conversations, optionally filtered by state or date |
| POST | /v1/Conversations |
createConversation | Start a new conversation |
| GET | /v1/Conversations/{Sid} |
getConversation | Get one conversation's details and state |
| POST | /v1/Conversations/{Sid} |
updateConversation | Rename a conversation or set it to inactive or closed |
| GET | /v1/Conversations/{ConversationSid}/Participants |
listParticipants | List the people and phone numbers in a conversation |
| POST | /v1/Conversations/{ConversationSid}/Participants |
addParticipant | Add an SMS, WhatsApp or chat participant to a conversation |
| GET | /v1/Conversations/{ConversationSid}/Participants/{Sid} |
getParticipant | Get one participant of a conversation |
| GET | /v1/Conversations/{ConversationSid}/Messages |
listMessages | List the messages in a conversation |
| POST | /v1/Conversations/{ConversationSid}/Messages |
sendMessage | Send a message into a conversation |
| GET | /v1/Conversations/{ConversationSid}/Messages/{Sid} |
getMessage | Get one message from a conversation |
| GET | /v1/Conversations/{ConversationSid}/Messages/{MessageSid}/Receipts |
listMessageReceipts | See delivery and read receipts for a message |
Authentication
accountSid_authToken
HTTP Basic
HTTP Basic auth: username = Account SID (AC...) or API key SID (SK...), password = Auth Token or API key secret.
How to get a credential
- Sign in to the Twilio Console.
- Copy the Account SID and Auth Token from the Account Info panel on the home page, or
- (Recommended) go to Account > API keys & tokens, click Create API key (type Standard), and copy the key SID (
SK...) and secret. The secret is shown once. - Conversations works on any account; WhatsApp participants need an approved WhatsApp sender, SMS participants need a Twilio phone number.
Permissions used
| Credential | Operations |
|---|---|
| Account SID + Auth Token, or Standard API key | all operations (listConversations, getConversation, createConversation, updateConversation, listParticipants, getParticipant, addParticipant, listMessages, getMessage, sendMessage, listMessageReceipts) |
Twilio has no per-endpoint scopes; a Standard API key can call everything except account/key management.
Common errors
- 401 (error 20003): wrong SID/secret pair, or an API key from another account. Re-copy both values.
- 403: the account is suspended, or the API key is Restricted without Conversations permissions.
- 400 (e.g. 50416 participant already exists, 50407 invalid address): fix the participant address or binding; phone numbers must be E.164.
- 404 (20404): wrong
ConversationSid(CH...) or the conversation was deleted. - 429 (20429): too many requests; back off and retry after a few seconds.
Store the SID and secret as a VX Agents Basic credential; they are never shown to the model.
Usage guide
Setup
- Credential: Basic auth with Account SID + Auth Token, or a Standard API key SID + secret (Twilio Console > Account > API keys & tokens).
- SMS participants need a Twilio phone number; WhatsApp needs an approved WhatsApp sender. Pin that number as a preset
MessagingBinding.ProxyAddress(e.g.+14155550100orwhatsapp:+14155550100). - All operations use your account's default Conversations service.
Handle a customer thread
- Find the thread:
listConversations(filterState=active, orStartDate/EndDateasYYYY-MM-DD), thengetConversationwith itsCH...sid. listParticipantsto see who is in it;listMessages(useOrder=desc,PageSize) to read the history.getMessageandlistMessageReceiptsshow one message and whether it was delivered/read.- New thread:
createConversationwith aFriendlyName(and optionalUniqueName), thenaddParticipant:- SMS/WhatsApp customer:
MessagingBinding.Address= their number (+1...orwhatsapp:+1...) andMessagingBinding.ProxyAddress= your Twilio number. - Chat user or agent:
Identity= their user id.
- SMS/WhatsApp customer:
sendMessagewithBody(andAuthor= the agent's name or identity). It is delivered to every SMS/WhatsApp participant.- When done,
updateConversationwithState=closed(orinactiveto pause). Closed conversations cannot be reopened.
Confirm before writing: sendMessage delivers a real, billed message to customers, addParticipant brings a phone number into the thread, and closing is final. Show the user the text and the recipients and get a yes before calling sendMessage, addParticipant or updateConversation with State=closed.
Good to know
- Requests are form-encoded; field names are PascalCase with dots (
MessagingBinding.Address). - Ids: conversations
CH..., participantsMB..., messagesIM.... - Phone numbers must be E.164. WhatsApp outside the 24-hour session window needs an approved template.
- A phone number can be in only one active conversation per proxy number (error 50416 if it is already in another).
- Lists page with
PageSize(max 100) and themeta.next_page_urltoken. - Dates are ISO 8601 UTC.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Twilio Conversations” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.