Retrieve a list of all conversation users in your account's default service

Update the global configuration of conversations on your account

POST /v1/Configuration

The Configuration resource manages a set of account-level settings applicable to the Conversations API.

Update the global configuration of conversations on your account

Body

DefaultChatServiceSid string

The SID of the default Conversation Service to use when creating a conversation.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
DefaultClosedTimer string

Default ISO8601 duration when conversation will be switched to closed state. Minimum value for this timer is 10 minutes.
DefaultInactiveTimer string

Default ISO8601 duration when conversation will be switched to inactive state. Minimum value for this timer is 1 minute.
DefaultMessagingServiceSid string

The SID of the default Messaging Service to use when creating a conversation.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.

Responses

200

OK
Hide response attributes Show response attributes object
- account_sid string | null
  
  The SID of the Account responsible for this configuration.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- default_chat_service_sid string | null
  
  The SID of the default Conversation Service that every new conversation is associated with.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
- default_closed_timer string | null
  
  Default ISO8601 duration when conversation will be switched to closed state.
- default_inactive_timer string | null
  
  Default ISO8601 duration when conversation will be switched to inactive state.
- default_messaging_service_sid string | null
  
  The SID of the default Messaging Service that every new conversation is associated with.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.
- links object(uri-map) | null
  
  Absolute URLs to access the webhook and default service configurations.
- url string(uri) | null
  
  An absolute URL for this global configuration.

POST /v1/Configuration

curl \
 -X POST https://conversations.twilio.com/v1/Configuration \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'DefaultChatServiceSid=string&DefaultClosedTimer=string&DefaultInactiveTimer=string&DefaultMessagingServiceSid=string'

Request example

{
  "DefaultChatServiceSid": "string",
  "DefaultClosedTimer": "string",
  "DefaultInactiveTimer": "string",
  "DefaultMessagingServiceSid": "string"
}

Request examples

{
  "DefaultChatServiceSid": "string",
  "DefaultClosedTimer": "string",
  "DefaultInactiveTimer": "string",
  "DefaultMessagingServiceSid": "string"
}

Response examples (200)

{
  "account_sid": "string",
  "default_chat_service_sid": "string",
  "default_closed_timer": "string",
  "default_inactive_timer": "string",
  "default_messaging_service_sid": "string",
  "links": {},
  "url": "https://example.com"
}

Response examples (200)

{
  "account_sid": "string",
  "default_chat_service_sid": "string",
  "default_closed_timer": "string",
  "default_inactive_timer": "string",
  "default_messaging_service_sid": "string",
  "links": {},
  "url": "https://example.com"
}

Retrieve a list of all messages in the conversation

GET /v1/Conversations/{ConversationSid}/Messages

A Message resource represents a message in a conversation.

Retrieve a list of all messages in the conversation

Path parameters

ConversationSid string Required

The unique ID of the Conversation for messages.

Query parameters

Order string

The sort order of the returned messages. Can be: asc (ascending) or desc (descending), with asc as the default.

Values are asc or desc.
PageSize integer

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum value is 1, maximum value is 1000.

Responses

200

OK
Hide response attributes Show response attributes object
- messages array[object]
  
  Hide messages attributes Show messages attributes array[object]
  
  account_sid string | null
  
  The unique ID of the Account responsible for this message.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
  
  attributes string | null
  
  A string metadata field you can use to store any data you wish.
  
  author string | null
  
  The channel specific identifier of the message's author.
  
  body string | null
  
  The content of the message.
  
  conversation_sid string | null
  
  The unique ID of the Conversation for this message.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CH[0-9a-fA-F]{32}$.
  
  date_created string(date-time) | null
  
  The date that this resource was created.
  
  date_updated string(date-time) | null
  
  The date that this resource was last updated.
  
  delivery
  
  An object that contains the summary of delivery statuses for the message to non-chat participants.
  
  index integer | null
  
  The index of the message within the Conversation.
  
  links object(uri-map) | null
  
  Absolute URL to access the receipts of this message.
  
  media array | null
  
  An array of objects that describe the Message's media if attached, otherwise, null.
  
  participant_sid string | null
  
  The unique ID of messages's author participant.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MB[0-9a-fA-F]{32}$.
  
  sid string | null
  
  A 34 character string that uniquely identifies this resource.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IM[0-9a-fA-F]{32}$.
  
  url string(uri) | null
  
  An absolute API URL for this message.
- meta object
  
  Hide meta attributes Show meta attributes object
  
  first_page_url string(uri)
  
  key string
  
  next_page_url string(uri)
  
  page integer
  
  page_size integer
  
  previous_page_url string(uri)
  
  url string(uri)

GET /v1/Conversations/{ConversationSid}/Messages

curl \
 -X GET https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Messages \
 --user "username:password"

Response examples (200)

{
  "messages": [
    {
      "account_sid": "string",
      "attributes": "string",
      "author": "string",
      "body": "string",
      "conversation_sid": "string",
      "date_created": "2023-05-04T09:42:00+00:00",
      "date_updated": "2023-05-04T09:42:00+00:00",
      "index": 42,
      "links": {},
      "media": [],
      "participant_sid": "string",
      "sid": "string",
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Response examples (200)

{
  "messages": [
    {
      "account_sid": "string",
      "attributes": "string",
      "author": "string",
      "body": "string",
      "conversation_sid": "string",
      "date_created": "2025-05-04T09:42:00Z",
      "date_updated": "2025-05-04T09:42:00Z",
      "index": 42,
      "links": {},
      "media": [],
      "participant_sid": "string",
      "sid": "string",
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Fetch a conversation from your account's default service

GET /v1/Conversations/{Sid}

A Conversation resource represents an omnichannel group conversation with an ordered list of messages and a participant roster.

Fetch a conversation from your account's default service

Path parameters

Sid string Required

A 34 character string that uniquely identifies this resource. Can also be the unique_name of the Conversation.

Responses

200

OK
Hide response attributes Show response attributes object
- account_sid string | null
  
  The unique ID of the Account responsible for this conversation.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- attributes string | null
  
  An optional string metadata field you can use to store any data you wish.
- bindings
- chat_service_sid string | null
  
  The unique ID of the Conversation Service this conversation belongs to.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
- date_created string(date-time) | null
  
  The date that this resource was created.
- date_updated string(date-time) | null
  
  The date that this resource was last updated.
- friendly_name string | null
  
  The human-readable name of this conversation.
- links object(uri-map) | null
  
  Absolute URLs to access the participants, messages and webhooks of this conversation.
- messaging_service_sid string | null
  
  The unique ID of the Messaging Service this conversation belongs to.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.
- sid string | null
  
  A 34 character string that uniquely identifies this resource.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CH[0-9a-fA-F]{32}$.
- state string | null
  
  Current state of this conversation.
  
  Values are inactive, active, or closed.
- timers
  
  Timer date values for this conversation.
- unique_name string | null
  
  An application-defined string that uniquely identifies the resource
- url string(uri) | null
  
  An absolute URL for this conversation.

GET /v1/Conversations/{Sid}

curl \
 -X GET https://conversations.twilio.com/v1/Conversations/{Sid} \
 --user "username:password"

Response examples (200)

{
  "account_sid": "string",
  "attributes": "string",
  "chat_service_sid": "string",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "friendly_name": "string",
  "links": {},
  "messaging_service_sid": "string",
  "sid": "string",
  "state": "inactive",
  "unique_name": "string",
  "url": "https://example.com"
}

Response examples (200)

{
  "account_sid": "string",
  "attributes": "string",
  "chat_service_sid": "string",
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "friendly_name": "string",
  "links": {},
  "messaging_service_sid": "string",
  "sid": "string",
  "state": "inactive",
  "unique_name": "string",
  "url": "https://example.com"
}

Retrieve a list of all user roles in your account's default service

GET /v1/Roles

A Role resource represents a set of permissions granted to a user within a service or a conversation.

Retrieve a list of all user roles in your account's default service

Query parameters

PageSize integer

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum value is 1, maximum value is 1000.

Responses

200

OK
Hide response attributes Show response attributes object
- meta object
  
  Hide meta attributes Show meta attributes object
  
  first_page_url string(uri)
  
  key string
  
  next_page_url string(uri)
  
  page integer
  
  page_size integer
  
  previous_page_url string(uri)
  
  url string(uri)
- roles array[object]
  
  Hide roles attributes Show roles attributes array[object]
  
  account_sid string | null
  
  The SID of the Account that created the resource
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
  
  chat_service_sid string | null
  
  The SID of the Conversation Service that the resource is associated with
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
  
  date_created string(date-time) | null
  
  The ISO 8601 date and time in GMT when the resource was created
  
  date_updated string(date-time) | null
  
  The ISO 8601 date and time in GMT when the resource was last updated
  
  friendly_name string | null
  
  The string that you assigned to describe the resource
  
  permissions array[string] | null
  
  An array of the permissions the role has been granted
  
  sid string | null
  
  The unique string that identifies the resource
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RL[0-9a-fA-F]{32}$.
  
  type string | null
  
  The type of role
  
  Values are conversation or service.
  
  url string(uri) | null
  
  An absolute URL for this user role.

GET /v1/Roles

curl \
 -X GET https://conversations.twilio.com/v1/Roles \
 --user "username:password"

Response examples (200)

{
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  },
  "roles": [
    {
      "account_sid": "string",
      "chat_service_sid": "string",
      "date_created": "2023-05-04T09:42:00+00:00",
      "date_updated": "2023-05-04T09:42:00+00:00",
      "friendly_name": "string",
      "permissions": [
        "string"
      ],
      "sid": "string",
      "type": "conversation",
      "url": "https://example.com"
    }
  ]
}

Response examples (200)

{
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  },
  "roles": [
    {
      "account_sid": "string",
      "chat_service_sid": "string",
      "date_created": "2025-05-04T09:42:00Z",
      "date_updated": "2025-05-04T09:42:00Z",
      "friendly_name": "string",
      "permissions": [
        "string"
      ],
      "sid": "string",
      "type": "conversation",
      "url": "https://example.com"
    }
  ]
}

Fetch a user role from your account's default service

GET /v1/Roles/{Sid}

A Role resource represents a set of permissions granted to a user within a service or a conversation.

Fetch a user role from your account's default service

Path parameters

Sid string Required

The SID of the Role resource to fetch.

Responses

200

OK
Hide response attributes Show response attributes object
- account_sid string | null
  
  The SID of the Account that created the resource
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- chat_service_sid string | null
  
  The SID of the Conversation Service that the resource is associated with
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
- date_created string(date-time) | null
  
  The ISO 8601 date and time in GMT when the resource was created
- date_updated string(date-time) | null
  
  The ISO 8601 date and time in GMT when the resource was last updated
- friendly_name string | null
  
  The string that you assigned to describe the resource
- permissions array[string] | null
  
  An array of the permissions the role has been granted
- sid string | null
  
  The unique string that identifies the resource
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RL[0-9a-fA-F]{32}$.
- type string | null
  
  The type of role
  
  Values are conversation or service.
- url string(uri) | null
  
  An absolute URL for this user role.

GET /v1/Roles/{Sid}

curl \
 -X GET https://conversations.twilio.com/v1/Roles/{Sid} \
 --user "username:password"

Response examples (200)

{
  "account_sid": "string",
  "chat_service_sid": "string",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "friendly_name": "string",
  "permissions": [
    "string"
  ],
  "sid": "string",
  "type": "conversation",
  "url": "https://example.com"
}

Response examples (200)

{
  "account_sid": "string",
  "chat_service_sid": "string",
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "friendly_name": "string",
  "permissions": [
    "string"
  ],
  "sid": "string",
  "type": "conversation",
  "url": "https://example.com"
}

Retrieve a list of all messages in the conversation

GET /v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Messages

A Service Message resource represents a message in a conversation within a specific service.

Retrieve a list of all messages in the conversation

Path parameters

ChatServiceSid string Required

The SID of the Conversation Service the Participant resource is associated with.
ConversationSid string Required

The unique ID of the Conversation for messages.

Query parameters

Order string

The sort order of the returned messages. Can be: asc (ascending) or desc (descending), with asc as the default.

Values are asc or desc.
PageSize integer

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum value is 1, maximum value is 1000.

Responses

200

OK
Hide response attributes Show response attributes object
- messages array[object]
  
  Hide messages attributes Show messages attributes array[object]
  
  account_sid string | null
  
  The unique ID of the Account responsible for this message.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
  
  attributes string | null
  
  A string metadata field you can use to store any data you wish.
  
  author string | null
  
  The channel specific identifier of the message's author.
  
  body string | null
  
  The content of the message.
  
  chat_service_sid string | null
  
  The SID of the Conversation Service that the resource is associated with.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IS[0-9a-fA-F]{32}$.
  
  conversation_sid string | null
  
  The unique ID of the Conversation for this message.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^CH[0-9a-fA-F]{32}$.
  
  date_created string(date-time) | null
  
  The date that this resource was created.
  
  date_updated string(date-time) | null
  
  The date that this resource was last updated.
  
  delivery
  
  An object that contains the summary of delivery statuses for the message to non-chat participants.
  
  index integer | null
  
  The index of the message within the Conversation.
  
  links object(uri-map) | null
  
  Absolute URL to access the receipts of this message.
  
  media array | null
  
  An array of objects that describe the Message's media if attached, otherwise, null.
  
  participant_sid string | null
  
  The unique ID of messages's author participant.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MB[0-9a-fA-F]{32}$.
  
  sid string | null
  
  A 34 character string that uniquely identifies this resource.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^IM[0-9a-fA-F]{32}$.
  
  url string(uri) | null
  
  An absolute URL for this message.
- meta object
  
  Hide meta attributes Show meta attributes object
  
  first_page_url string(uri)
  
  key string
  
  next_page_url string(uri)
  
  page integer
  
  page_size integer
  
  previous_page_url string(uri)
  
  url string(uri)

GET /v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Messages

curl \
 -X GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Messages \
 --user "username:password"

Response examples (200)

{
  "messages": [
    {
      "account_sid": "string",
      "attributes": "string",
      "author": "string",
      "body": "string",
      "chat_service_sid": "string",
      "conversation_sid": "string",
      "date_created": "2023-05-04T09:42:00+00:00",
      "date_updated": "2023-05-04T09:42:00+00:00",
      "index": 42,
      "links": {},
      "media": [],
      "participant_sid": "string",
      "sid": "string",
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Response examples (200)

{
  "messages": [
    {
      "account_sid": "string",
      "attributes": "string",
      "author": "string",
      "body": "string",
      "chat_service_sid": "string",
      "conversation_sid": "string",
      "date_created": "2025-05-04T09:42:00Z",
      "date_updated": "2025-05-04T09:42:00Z",
      "index": 42,
      "links": {},
      "media": [],
      "participant_sid": "string",
      "sid": "string",
      "url": "https://example.com"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "string",
    "next_page_url": "https://example.com",
    "page": 42,
    "page_size": 42,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Remove an existing webhook scoped to the conversation

DELETE /v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

A Conversation-scoped Webhook resource manages a set of callback URLs and their configuration for receiving events specific to one conversation.

Remove an existing webhook scoped to the conversation

Path parameters

ChatServiceSid string Required

The SID of the Conversation Service the Participant resource is associated with.
ConversationSid string Required

The unique ID of the Conversation for this webhook.
Sid string Required

A 34 character string that uniquely identifies this resource.

Responses

204

The resource was deleted successfully.

DELETE /v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid}

curl \
 -X DELETE https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Webhooks/{Sid} \
 --user "username:password"

Remove a user role from your service

DELETE /v1/Services/{ChatServiceSid}/Roles/{Sid}

A Service Role resource represents a set of permissions granted to a user within a service or a conversation.

Remove a user role from your service

Path parameters

ChatServiceSid string Required

The SID of the Conversation Service to delete the Role resource from.
Sid string Required

The SID of the Role resource to delete.

Responses

204

The resource was deleted successfully.

DELETE /v1/Services/{ChatServiceSid}/Roles/{Sid}

curl \
 -X DELETE https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Roles/{Sid} \
 --user "username:password"