Twilio Conversations is an omni-channel messaging platform that allows you to build engaging conversational messaging experiences across many channels. Find the documentation, sample code, and developer tools you need to build exactly what you want.
components:
schemas:
conversations.v1.configuration:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this configuration.
default_chat_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the default [Conversation
Service](https://www.twilio.com/docs/conversations/api/service-resource)
used when creating a conversation.
default_messaging_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MG[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the default [Messaging
Service](https://www.twilio.com/docs/messaging/api/service-resource)
used when creating a conversation.
default_inactive_timer:
type: string
nullable: true
description: >-
Default ISO8601 duration when conversation will be switched to
`inactive` state. Minimum value for this timer is 1 minute.
default_closed_timer:
type: string
nullable: true
description: >-
Default ISO8601 duration when conversation will be switched to
`closed` state. Minimum value for this timer is 10 minutes.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this global configuration.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains absolute API resource URLs to access the webhook and
default service configurations.
conversations.v1.configuration_address:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IG[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) the address
belongs to
type:
type: string
nullable: true
description: Type of Address, value can be `whatsapp` or `sms`.
address:
type: string
nullable: true
description: >-
The unique address to be configured. The address can be a whatsapp
address or phone number
x-twilio:
pii:
handling: standard
deleteSla: 30
friendly_name:
type: string
nullable: true
description: >-
The human-readable name of this configuration, limited to 256
characters. Optional.
auto_creation:
nullable: true
description: Auto Creation configuration for the address.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this address configuration.
address_country:
type: string
nullable: true
description: >-
An ISO 3166-1 alpha-2n country code which the address belongs to.
This is currently only applicable to short code addresses.
configuration_address_enum_type:
type: string
enum:
- sms
- whatsapp
- messenger
- gbm
- email
configuration_address_enum_auto_creation_type:
type: string
enum:
- webhook
- studio
- default
configuration_address_enum_method:
type: string
enum:
- GET
- POST
conversations.v1.configuration.configuration_webhook:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this conversation.
method:
type: string
$ref: '#/components/schemas/configuration_webhook_enum_method'
nullable: true
description: The HTTP method to be used when sending a webhook request.
filters:
type: array
items:
type: string
nullable: true
description: >-
The list of webhook event triggers that are enabled for this
Service: `onMessageAdded`, `onMessageUpdated`, `onMessageRemoved`,
`onConversationUpdated`, `onConversationRemoved`,
`onParticipantAdded`, `onParticipantUpdated`, `onParticipantRemoved`
pre_webhook_url:
type: string
nullable: true
description: The absolute url the pre-event webhook request should be sent to.
post_webhook_url:
type: string
nullable: true
description: The absolute url the post-event webhook request should be sent to.
target:
type: string
$ref: '#/components/schemas/configuration_webhook_enum_target'
nullable: true
description: >-
The routing target of the webhook. Can be ordinary or route
internally to Flex
url:
type: string
format: uri
nullable: true
description: An absolute API resource API resource URL for this webhook.
configuration_webhook_enum_target:
type: string
enum:
- webhook
- flex
configuration_webhook_enum_method:
type: string
enum:
- GET
- POST
conversations.v1.conversation:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this conversation.
chat_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the [Conversation
Service](https://www.twilio.com/docs/conversations/api/service-resource)
this conversation belongs to.
messaging_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MG[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the [Messaging
Service](https://www.twilio.com/docs/messaging/api/service-resource)
this conversation belongs to.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
friendly_name:
type: string
nullable: true
description: >-
The human-readable name of this conversation, limited to 256
characters. Optional.
x-twilio:
pii:
handling: standard
deleteSla: 30
unique_name:
type: string
nullable: true
description: >-
An application-defined string that uniquely identifies the resource.
It can be used to address the resource in place of the resource's
`sid` in the URL.
x-twilio:
pii:
handling: standard
deleteSla: 30
attributes:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: sensitive
deleteSla: 30
state:
type: string
$ref: '#/components/schemas/conversation_enum_state'
nullable: true
description: >-
Current state of this conversation. Can be either `active`,
`inactive` or `closed` and defaults to `active`
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated.
timers:
nullable: true
description: Timer date values representing state update for this conversation.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this conversation.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains absolute URLs to access the
[participants](https://www.twilio.com/docs/conversations/api/conversation-participant-resource),
[messages](https://www.twilio.com/docs/conversations/api/conversation-message-resource)
and
[webhooks](https://www.twilio.com/docs/conversations/api/conversation-scoped-webhook-resource)
of this conversation.
bindings:
nullable: true
conversation_enum_webhook_enabled_type:
type: string
enum:
- 'true'
- 'false'
conversation_enum_state:
type: string
enum:
- inactive
- active
- closed
conversations.v1.conversation.conversation_message:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this message.
conversation_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for this message.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IM[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
index:
type: integer
nullable: true
description: >-
The index of the message within the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource). Indices may skip numbers, but will always be in order of when the
message was received.
author:
type: string
nullable: true
description: >-
The channel specific identifier of the message's author. Defaults to
`system`.
x-twilio:
pii:
handling: standard
deleteSla: 30
body:
type: string
nullable: true
description: The content of the message, can be up to 1,600 characters long.
x-twilio:
pii:
handling: sensitive
deleteSla: 30
media:
type: array
items: {}
nullable: true
description: >-
An array of objects that describe the Message's media, if the
message contains media. Each object contains these fields:
`content_type` with the MIME type of the media, `filename` with the
name of the media, `sid` with the SID of the Media resource, and
`size` with the media object's file size in bytes. If the Message
has no media, this value is `null`.
x-twilio:
pii:
handling: standard
deleteSla: 30
attributes:
type: string
nullable: true
description: >-
A 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.
x-twilio:
pii:
handling: sensitive
deleteSla: 30
participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MB[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of messages's author participant. Null in case of
`system` sent message.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this resource was last updated. `null` if the message
has not been edited.
url:
type: string
format: uri
nullable: true
description: An absolute API resource API URL for this message.
delivery:
nullable: true
description: >-
An object that contains the summary of delivery statuses for the
message to non-chat participants.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains an absolute API resource URL to access the delivery & read
receipts of this message.
content_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^HX[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the multi-channel [Rich
Content](https://www.twilio.com/docs/content) template.
conversation_message_enum_order_type:
type: string
enum:
- asc
- desc
conversation_message_enum_webhook_enabled_type:
type: string
enum:
- 'true'
- 'false'
conversations.v1.conversation.conversation_message.conversation_message_receipt:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this participant.
conversation_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for this message.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^DY[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
message_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IM[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the message within a
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
the delivery receipt belongs to
channel_message_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: >-
A messaging channel-specific identifier for the message delivered to
participant e.g. `SMxx` for SMS, `WAxx` for Whatsapp etc.
participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MB[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the participant the delivery receipt belongs to.
status:
type: string
$ref: >-
#/components/schemas/conversation_message_receipt_enum_delivery_status
nullable: true
description: >-
The message delivery status, can be `read`, `failed`, `delivered`,
`undelivered`, `sent` or null.
error_code:
type: integer
nullable: true
description: >-
The message [delivery error
code](https://www.twilio.com/docs/sms/api/message-resource#delivery-related-errors)
for a `failed` status,
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this resource was last updated. `null` if the delivery
receipt has not been updated.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this delivery receipt.
conversation_message_receipt_enum_delivery_status:
type: string
enum:
- read
- failed
- delivered
- undelivered
- sent
conversations.v1.conversation.conversation_participant:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this participant.
conversation_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for this participant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MB[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
identity:
type: string
nullable: true
description: >-
A unique string identifier for the conversation participant as
[Conversation
User](https://www.twilio.com/docs/conversations/api/user-resource).
This parameter is non-null if (and only if) the participant is using
the Conversations SDK to communicate. Limited to 256 characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
attributes:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: sensitive
deleteSla: 30
messaging_binding:
nullable: true
description: >-
Information about how this participant exchanges messages with the
conversation. A JSON parameter consisting of type and address fields
of the participant.
x-twilio:
pii:
handling: standard
deleteSla: 30
role_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RL[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of a conversation-level
[Role](https://www.twilio.com/docs/conversations/api/role-resource)
to assign to the participant.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this participant.
last_read_message_index:
type: integer
nullable: true
description: >-
Index of last “read” message in the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for the Participant.
last_read_timestamp:
type: string
nullable: true
description: >-
Timestamp of last “read” message in the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for the Participant.
conversation_participant_enum_webhook_enabled_type:
type: string
enum:
- 'true'
- 'false'
conversations.v1.conversation.conversation_scoped_webhook:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^WH[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this conversation.
conversation_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
for this webhook.
target:
type: string
nullable: true
description: 'The target of this webhook: `webhook`, `studio`, `trigger`'
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this webhook.
configuration:
nullable: true
description: The configuration of this webhook. Is defined based on target.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated.
conversation_scoped_webhook_enum_target:
type: string
enum:
- webhook
- trigger
- studio
conversation_scoped_webhook_enum_method:
type: string
enum:
- GET
- POST
conversations.v1.credential:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this credential.
friendly_name:
type: string
nullable: true
description: >-
The human-readable name of this credential, limited to 64
characters. Optional.
x-twilio:
pii:
handling: standard
deleteSla: 30
type:
type: string
$ref: '#/components/schemas/credential_enum_push_type'
nullable: true
description: >-
The type of push-notification service the credential is for. Can be:
`fcm`, `gcm`, or `apn`.
sandbox:
type: string
nullable: true
description: >-
[APN only] Whether to send the credential to sandbox APNs. Can be
`true` to send to sandbox APNs or `false` to send to production.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created.
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated.
url:
type: string
format: uri
nullable: true
description: An absolute API resource URL for this credential.
credential_enum_push_type:
type: string
enum:
- apn
- gcm
- fcm
conversations.v1.participant_conversation:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Account](https://www.twilio.com/docs/iam/api/account) responsible
for this conversation.
chat_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the [Conversation
Service](https://www.twilio.com/docs/conversations/api/service-resource)
this conversation belongs to.
participant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MB[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Participant](https://www.twilio.com/docs/conversations/api/conversation-participant-resource).
participant_user_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^US[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that identifies the conversation participant as
[Conversation
User](https://www.twilio.com/docs/conversations/api/user-resource).
participant_identity:
type: string
nullable: true
description: >-
A unique string identifier for the conversation participant as
[Conversation
User](https://www.twilio.com/docs/conversations/api/user-resource).
This parameter is non-null if (and only if) the participant is using
the Conversations SDK to communicate. Limited to 256 characters.
x-twilio:
pii:
handling: standard
deleteSla: 30
participant_messaging_binding:
nullable: true
description: >-
Information about how this participant exchanges messages with the
conversation. A JSON parameter consisting of type and address fields
of the participant.
x-twilio:
pii:
handling: standard
deleteSla: 30
conversation_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CH[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID of the
[Conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
this Participant belongs to.
conversation_unique_name:
type: string
nullable: true
description: >-
An application-defined string that uniquely identifies the
Conversation resource.
x-twilio:
pii:
handling: standard
deleteSla: 30
conversation_friendly_name:
type: string
nullable: true
description: >-
The human-readable name of this conversation, limited to 256
characters. Optional.
x-twilio:
pii:
handling: standard
deleteSla: 30
conversation_attributes:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: sensitive
deleteSla: 30
conversation_date_created:
type: string
format: date-time
nullable: true
description: >-
The date that this conversation was created, given in ISO 8601
format.
conversation_date_updated:
type: string
format: date-time
nullable: true
description: >-
The date that this conversation was last updated, given in ISO 8601
format.
conversation_created_by:
type: string
nullable: true
description: Identity of the creator of this Conversation.
conversation_state:
type: string
$ref: '#/components/schemas/participant_conversation_enum_state'
nullable: true
description: >-
The current state of this User Conversation. One of `inactive`,
`active` or `closed`.
conversation_timers:
nullable: true
description: Timer date values representing state update for this conversation.
links:
type: object
format: uri-map
nullable: true
description: >-
Contains absolute URLs to access the
[participant](https://www.twilio.com/docs/conversations/api/conversation-participant-resource)
and
[conversation](https://www.twilio.com/docs/conversations/api/conversation-resource)
of this conversation.
participant_conversation_enum_state:
type: string
enum:
- inactive
- active
- closed
conversations.v1.role:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RL[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Role resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio
# --- truncated at 32 KB (317 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/conversations-openapi-original.yml