Create a new conversation in your service

POST /v1/Services/{ChatServiceSid}/Conversations

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

Create a new conversation in your service

Headers

Path parameters

Body

  • Attributes string

    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.

  • DateCreated string(date-time)

    The date that this resource was created.

  • DateUpdated string(date-time)

    The date that this resource was last updated.

  • FriendlyName string

    The human-readable name of this conversation, limited to 256 characters. Optional.

  • MessagingServiceSid string

    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}$.

  • State string

    Current state of this conversation. Can be either active, inactive or closed and defaults to active

    Values are inactive, active, or closed.

  • Timers.Closed string

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

  • Timers.Inactive string

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

  • UniqueName string

    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.

Responses

  • 201

    Created

    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.
POST /v1/Services/{ChatServiceSid}/Conversations 
curl \
 -X POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "X-Twilio-Webhook-Enabled: true" \
 -d 'Attributes=string&DateCreated=2023-05-04T09%3A42%3A00%2B00%3A00&DateUpdated=2023-05-04T09%3A42%3A00%2B00%3A00&FriendlyName=string&MessagingServiceSid=string&State=inactive&Timers.Closed=string&Timers.Inactive=string&UniqueName=string'
Request example 
# Headers
X-Twilio-Webhook-Enabled: true

# Payload
{
  "Attributes": "string",
  "DateCreated": "2023-05-04T09:42:00+00:00",
  "DateUpdated": "2023-05-04T09:42:00+00:00",
  "FriendlyName": "string",
  "MessagingServiceSid": "string",
  "State": "inactive",
  "Timers.Closed": "string",
  "Timers.Inactive": "string",
  "UniqueName": "string"
}
Request examples 
# Headers
X-Twilio-Webhook-Enabled: true

# Payload
{
  "Attributes": "string",
  "DateCreated": "2025-05-04T09:42:00Z",
  "DateUpdated": "2025-05-04T09:42:00Z",
  "FriendlyName": "string",
  "MessagingServiceSid": "string",
  "State": "inactive",
  "Timers.Closed": "string",
  "Timers.Inactive": "string",
  "UniqueName": "string"
}
Response examples (201) 
{
  "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 (201) 
{
  "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"
}