Conversation Resource
A Conversation is a unique message thread that contains Participants and the Messages they have sent.
Do not use Personally Identifiable Information (PII) for the friendlyName field.
Avoid using a person's name, home address, email, phone number, or other PII in the friendlyName field. Use some form of pseudonymized identifier, instead.
You can learn more about how we process your data in our privacy policy.
API Base URL
All URLs in the reference documentation use the following base URL:
https://conversations.twilio.com/v1Using the shortened base URL
Using the REST API, you can interact with Conversation resources in the default Conversation Service instance via a "shortened" URL that does not include the Conversation Service instance SID ("ISXXX..."). If you are only using one Conversation Service (the default), you do not need to include the Conversation Service SID in your URL, e.g.
GET /v1/Conversations
For Conversations applications that build on more than one Conversation Service instance, you will need to specify the Conversation Service SID in the REST API call:
GET /v1/Services/ISxx/ConversationsConversation properties
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The unique ID of the Account responsible for this conversation. |
chat_service_sid
|
The unique ID of the Conversation Service this conversation belongs to. |
messaging_service_sid
|
The unique ID of the Messaging Service this conversation belongs to. |
sid
|
A 34 character string that uniquely identifies this resource. |
friendly_name
|
The human-readable name of this conversation, limited to 256 characters. Optional. |
unique_name
|
An application-defined string that uniquely identifies the resource. It can be used to address the resource in place of the resource's |
attributes
|
An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned. |
state
|
Current state of this conversation. Can be either |
date_created
|
The date that this resource was created. |
date_updated
|
The date that this resource was last updated. |
timers
|
Timer date values representing state update for this conversation. |
url
|
An absolute API resource URL for this conversation. |
links
|
Contains absolute URLs to access the participants, messages and webhooks of this conversation. |
bindings
|
|
Create a Conversation resource
https://conversations.twilio.com/v1/Conversations
Parameters
| Parameters in REST API format | |
|---|---|
friendly_name
Optional
|
The human-readable name of this conversation, limited to 256 characters. Optional. |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. It can be used to address the resource in place of the resource's |
date_created
Optional
|
The date that this resource was created. |
date_updated
Optional
|
The date that this resource was last updated. |
messaging_service_sid
Optional
|
The unique ID of the Messaging Service this conversation belongs to. |
attributes
Optional
|
An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned. |
state
Optional
|
Current state of this conversation. Can be either |
timers.inactive
Optional
|
ISO8601 duration when conversation will be switched to |
timers.closed
Optional
|
ISO8601 duration when conversation will be switched to |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
Fetch a Conversation resource
https://conversations.twilio.com/v1/Conversations/{Sid}
You can fetch a Conversation by providing your account credentials and the conversation SID (provided when the Conversation is created).
The most valuable part of the Conversation resource itself is the attributes key, which includes metadata attached to the conversation from the moment of its creation.
The other relevant parts of a Conversation include its Participants (the entities who are currently conversing) and the Messages they've sent. Both of these are linked directly from the top-level url key.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this resource. Can also be the |
Example 1
Read multiple Conversation resources
https://conversations.twilio.com/v1/Conversations
Returns a list of conversations sorted by recent message activity.
Parameters
| Parameters in REST API format | |
|---|---|
start_date
Optional
|
Start date or time in ISO8601 format for filtering list of Conversations. If a date is provided, the start time of the date is used (YYYY-MM-DDT00:00:00Z). Can be combined with other filters. |
end_date
Optional
|
End date or time in ISO8601 format for filtering list of Conversations. If a date is provided, the end time of the date is used (YYYY-MM-DDT23:59:59Z). Can be combined with other filters. |
state
Optional
|
State for sorting and filtering list of Conversations. Can be |
Example 1
Update Conversation
https://conversations.twilio.com/v1/Conversations/{Sid}
The core definition of any Conversation can be modified on the fly. Update a Conversation to attach metadata that you extract on the fly (e.g. "customer-loyalty-status": "gold", or "aml-risk-level": "heightened"), or to correct mistakes manually.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this resource. Can also be the |
friendly_name
Optional
|
The human-readable name of this conversation, limited to 256 characters. Optional. |
date_created
Optional
|
The date that this resource was created. |
date_updated
Optional
|
The date that this resource was last updated. |
attributes
Optional
|
An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned. |
messaging_service_sid
Optional
|
The unique ID of the Messaging Service this conversation belongs to. |
state
Optional
|
Current state of this conversation. Can be either |
timers.inactive
Optional
|
ISO8601 duration when conversation will be switched to |
timers.closed
Optional
|
ISO8601 duration when conversation will be switched to |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. It can be used to address the resource in place of the resource's |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
Delete a Conversation resource
https://conversations.twilio.com/v1/Conversations/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
A 34 character string that uniquely identifies this resource. Can also be the |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
