Skip to content
Home/
REST API Reference
/
/
Creates a conversation

Creates a conversation

Request

You can create a conversation that has been initiated by a contact (ie. user or lead). The conversation can be an in-app message only.

Sending for visitors

You can also send a message from a visitor by specifying their id value in the from field, along with a type field value of lead. This visitor will be automatically converted to a contact with a lead role once the conversation is created.

This will return the Message model that has been created.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
Bodyapplication/json
fromobjectrequired
bodystringrequired

The content of the message. HTML is not supported.

Example:"Hello"
subjectstring

The title of the email. Only applicable if the message type is email.

Example:"Thanks for everything"
attachment_urlsArray of strings, (uri), <= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

created_atinteger, (date-time)

The time the conversation was created as a UTC Unix timestamp. If not provided, the current time will be used. This field is only recommneded for migrating past conversations from another source into Intercom.

Example:1671028894
brand_idstring

The unique identifier of the brand to associate with this conversation.

Example:"123"
curl -i -X POST \
  https://api.intercom.io/conversations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "from": {
      "type": "user",
      "id": "6762f11b1bb69f9f2193bba3"
    },
    "body": "Hello there"
  }'

Responses

conversation created

Bodyapplication/json
typestringrequired

The type of the message

Example:"user_message"
idstringrequired

The id representing the message.

Example:"1488971108"
created_atinteger, (date-time)required

The time the conversation was created.

Example:1667560812
subjectstring

The subject of the message. Only present if message_type: email.

Example:"Greetings"
bodystringrequired

The message body, which may contain HTML.

Example:"Hello"
message_typestringrequired

The type of message that was sent. Can be email, inapp, facebook, twitter or whatsapp.

Enum:"email""inapp""facebook""twitter""whatsapp"
Example:"inapp"
conversation_idstringrequired

The associated conversation_id

Example:"64619700005570"
ownerobject or null(Admin)

The admin who sent the message. Only present when the message has an owner.

templatestring

The style of the email, such as plain or personal. Only present when message_type is email.

Example:"plain"
external_idstring

The external identifier of the message, if one was set when the message was created. Only returned for messages started by a contact.

Example:"api:order-1234"
whatsapp_message_idstring

The id WhatsApp gave the message. Only present for whatsapp messages that WhatsApp accepted.

Example:"wamid.EXAMPLE123"
Response
{
  "type": "user_message",
  "id": "403918330",
  "created_at": 1734537501,
  "body": "Hello there",
  "message_type": "inapp",
  "conversation_id": "499"
}