Create a new conversation in your account's default service

POST /v1/Conversations

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

Headers

X-Twilio-Webhook-Enabled string

The X-Twilio-Webhook-Enabled HTTP request header

Values are true or false.

application/x-www-form-urlencoded

Body

FriendlyName string

The human-readable name of this conversation, limited to 256 characters. Optional.
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.
DateCreated string(date-time)

The date that this resource was created.
DateUpdated string(date-time)

The date that this resource was last updated.
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}$.
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.
State string

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

Values are inactive, active, or closed.
Timers.Inactive string

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

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

The default email address that will be used when sending outbound emails in this conversation.
Bindings.Email.Name string

The default name that will be used when sending outbound emails in this conversation.

Responses

201 application/json

Created
Hide headers attributes Show headers attributes
- Access-Control-Allow-Origin string
  
  Specify the origin(s) allowed to access the resource
- Access-Control-Allow-Methods string
  
  Specify the HTTP methods allowed when accessing the resource
- Access-Control-Allow-Headers string
  
  Specify the headers allowed when accessing the resource
- Access-Control-Allow-Credentials boolean
  
  Indicates whether the browser should include credentials
- Access-Control-Expose-Headers string
  
  Headers exposed to the client
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}$.
- 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}$.
- 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}$.
- friendly_name string | null
  
  The human-readable name of this conversation, limited to 256 characters. Optional.
- unique_name string | null
  
  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.
- attributes string | null
  
  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 string
  
  Current state of this conversation. Can be either initializing, active, inactive or closed and defaults to active
  
  Values are inactive, active, or closed.
- 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.
- timers
  
  Timer date values representing state update for this conversation.
- url string(uri) | null
  
  An absolute API resource URL for this conversation.
- links object(uri-map) | null
  
  Contains absolute URLs to access the participants, messages and webhooks of this conversation.
- bindings

POST /v1/Conversations

curl \
 --request POST 'https://conversations.twilio.com/v1/Conversations' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --header "X-Twilio-Webhook-Enabled: true" \
 --data 'State=inactive&Attributes=%7B+%22topic%22%3A+%22feedback%22+%7D&UniqueName=unique_name&DateCreated=2015-12-16T22%3A18%3A37Z&DateUpdated=2015-12-16T22%3A18%3A38Z&FriendlyName=friendly_name&Timers.Closed=PT10M&Timers.Inactive=PT1M&MessagingServiceSid=MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'

Request examples

{"State"=>"inactive", "Attributes"=>"{ \"topic\": \"feedback\" }", "UniqueName"=>"unique_name", "DateCreated"=>"2015-12-16T22:18:37Z", "DateUpdated"=>"2015-12-16T22:18:38Z", "FriendlyName"=>"friendly_name", "Timers.Closed"=>"PT10M", "Timers.Inactive"=>"PT1M", "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

{"State"=>"active", "DateCreated"=>"2020-07-01T22:18:37Z", "DateUpdated"=>"2020-07-01T22:18:37Z", "FriendlyName"=>"friendly_name", "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

{"DateCreated"=>"2020-07-01T22:18:37Z", "DateUpdated"=>"2020-07-01T22:18:37Z", "FriendlyName"=>"friendly_name", "Bindings.Email.Name"=>"Example", "Bindings.Email.Address"=>"example@example.com"}

Response examples (201)

{
  "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "export": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Export",
    "messages": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
    "webhooks": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
    "participants": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants"
  },
  "state": "inactive",
  "timers": {
    "date_closed": "2015-12-16T22:28:38Z",
    "date_inactive": "2015-12-16T22:19:38Z"
  },
  "bindings": {},
  "attributes": "{ \"topic\": \"feedback\" }",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "unique_name": "unique_name",
  "date_created": "2015-12-16T22:18:37Z",
  "date_updated": "2015-12-16T22:18:38Z",
  "friendly_name": "friendly_name",
  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "export": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Export",
    "messages": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
    "webhooks": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
    "participants": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants"
  },
  "state": "active",
  "timers": {},
  "bindings": {},
  "attributes": "{}",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "unique_name": null,
  "date_created": "2020-07-01T22:18:37Z",
  "date_updated": "2020-07-01T22:18:37Z",
  "friendly_name": "friendly_name",
  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "export": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Export",
    "messages": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
    "webhooks": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
    "participants": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants"
  },
  "state": "active",
  "timers": {},
  "bindings": {
    "email": {
      "name": "example",
      "projected_address": "example+123@example.com"
    }
  },
  "attributes": "{}",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "unique_name": null,
  "date_created": "2020-07-01T22:18:37Z",
  "date_updated": "2020-07-01T22:18:37Z",
  "friendly_name": "friendly_name",
  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}