Add a new message to the conversation

POST /v1/Conversations/{ConversationSid}/Messages
Account sid auth token

A Message resource represents a message in a conversation.

Add a new message to the conversation

Headers

  • X-Twilio-Webhook-Enabled string

    The X-Twilio-Webhook-Enabled HTTP request header

    Values are true or false.

Path parameters

  • ConversationSid string Required

    The unique ID of the Conversation for this message.

application/x-www-form-urlencoded

Body

  • Author string

    The channel specific identifier of the message's author. Defaults to system.

  • Body string

    The content of the message, can be up to 1,600 characters long.

  • DateCreated string(date-time)

    The date that this resource was created.

  • DateUpdated string(date-time)

    The date that this resource was last updated. null if the message has not been edited.

  • Attributes string

    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.

  • MediaSid string

    The Media SID to be attached to the new Message.

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

  • ContentSid string

    The unique ID of the multi-channel Rich Content template, required for template-generated messages. Note that if this field is set, Body and MediaSid parameters are ignored.

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

  • ContentVariables string

    A structurally valid JSON string that contains values to resolve Rich Content template variables.

  • Subject string

    The subject of the message, can be up to 256 characters long.

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 message.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[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}$.

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

    • index integer

      The index of the message within the Conversation. Indices may skip numbers, but will always be in order of when the message was received.

      Default value is 0.

    • author string | null

      The channel specific identifier of the message's author. Defaults to system.

    • body string | null

      The content of the message, can be up to 1,600 characters long.

    • media array | null

      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.

    • attributes string | null

      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.

    • participant_sid string | null

      The unique ID of messages's author participant. Null in case of system sent message.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MB[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. null if the message has not been edited.

    • url string(uri) | null

      An absolute API resource API URL for this message.

    • delivery

      An object that contains the summary of delivery statuses for the message to non-chat participants.

    • links object(uri-map) | null

      Contains an absolute API resource URL to access the delivery & read receipts of this message.

    • content_sid string | null

      The unique ID of the multi-channel Rich Content template.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HX[0-9a-fA-F]{32}$.
POST /v1/Conversations/{ConversationSid}/Messages 
curl \
 --request POST 'https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Messages' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --header "X-Twilio-Webhook-Enabled: true" \
 --data 'Body=Hello&Author=message+author&Attributes=%7B+%22importance%22%3A+%22high%22+%7D&DateCreated=2015-12-16T22%3A18%3A37Z&DateUpdated=2015-12-16T22%3A18%3A38Z'
Request examples 
{"Body"=>"Hello", "Author"=>"message author", "Attributes"=>"{ \"importance\": \"high\" }", "DateCreated"=>"2015-12-16T22:18:37Z", "DateUpdated"=>"2015-12-16T22:18:38Z"}
{"Author"=>"message author", "MediaSid"=>"MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "Attributes"=>"{ \"importance\": \"high\" }", "DateCreated"=>"2015-12-16T22:18:37Z", "DateUpdated"=>"2015-12-16T22:18:38Z"}
{"Body"=>"Hello", "Author"=>"message author", "DateCreated"=>"2020-07-01T22:18:37Z", "DateUpdated"=>"2020-07-01T22:18:37Z"}
{"Author"=>"message author", "ContentSid"=>"HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "DateCreated"=>"2015-12-16T22:18:37Z", "DateUpdated"=>"2015-12-16T22:18:38Z", "ContentVariables"=>"{\"name\": \"John\"}"}
{"Body"=>"message body", "Author"=>"message author", "Subject"=>"message subject", "DateCreated"=>"2015-12-16T22:18:37Z", "DateUpdated"=>"2015-12-16T22:18:38Z"}
Response examples (201) 
{
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "body": "Hello",
  "index": 0,
  "links": {
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata",
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts"
  },
  "media": null,
  "author": "message author",
  "delivery": {
    "read": "some",
    "sent": "all",
    "total": 2,
    "failed": "none",
    "delivered": "some",
    "undelivered": "none"
  },
  "attributes": "{ \"importance\": \"high\" }",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_sid": null,
  "date_created": "2015-12-16T22:18:37Z",
  "date_updated": "2015-12-16T22:18:38Z",
  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
{
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "body": null,
  "index": 0,
  "links": {
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata",
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts"
  },
  "media": [
    {
      "sid": "MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "size": 42056,
      "filename": "car.jpg",
      "content_type": "image/jpeg"
    }
  ],
  "author": "message author",
  "delivery": {
    "read": "some",
    "sent": "all",
    "total": 2,
    "failed": "none",
    "delivered": "some",
    "undelivered": "none"
  },
  "attributes": "{ \"importance\": \"high\" }",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_sid": null,
  "date_created": "2015-12-16T22:18:37Z",
  "date_updated": "2015-12-16T22:18:38Z",
  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
{
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "body": "Hello",
  "index": 0,
  "links": {
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata",
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts"
  },
  "media": null,
  "author": "message author",
  "delivery": {
    "read": "some",
    "sent": "all",
    "total": 2,
    "failed": "none",
    "delivered": "some",
    "undelivered": "none"
  },
  "attributes": "{}",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_sid": null,
  "date_created": "2020-07-01T22:18:37Z",
  "date_updated": "2020-07-01T22:18:37Z",
  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
{
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "body": "Hello John",
  "index": 0,
  "links": {
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata",
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts"
  },
  "media": null,
  "author": "message author",
  "delivery": {
    "read": "some",
    "sent": "all",
    "total": 2,
    "failed": "none",
    "delivered": "some",
    "undelivered": "none"
  },
  "attributes": "{}",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-12-16T22:18:37Z",
  "date_updated": "2015-12-16T22:18:38Z",
  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
{
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "body": "message body",
  "index": 0,
  "links": {
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata",
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts"
  },
  "media": null,
  "author": "message author",
  "delivery": {
    "read": "some",
    "sent": "all",
    "total": 2,
    "failed": "none",
    "delivered": "some",
    "undelivered": "none"
  },
  "attributes": "{}",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-12-16T22:18:37Z",
  "date_updated": "2015-12-16T22:18:38Z",
  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}