Intercom API (unofficial showcase)
POST/conversations

Create a conversation

Creates a conversation initiated by a contact and returns the created message. The conversation can be an in-app message only; include the contact in from and the message text in body. When you identify a visitor in from, the visitor is converted to a contact with a lead role.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 6 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to `2.17` when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Conversation message details. Include the contact in from and the message content in body.

fromobjectrequired
The contact initiating the conversation. Include both `type` and `id`.
bodystringrequired
The content of the message. HTML is not supported.
subjectstringoptional
The title of the email. Only applicable if the message type is email.
attachment_urlsarray<string>optional
A list of image URLs that will be added as attachments. You can include up to 10 URLs.
created_atintegeroptional
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.
brand_idstringoptional
The unique identifier of the brand to associate with this conversation.

4 status codes
200Returns the created message, including its identifier, creation time, body, message type, and conversation identifier.
typestringrequired
The type of the message
idstringrequired
The id representing the message.
created_atintegerrequired
The time the conversation was created.
subjectstringoptional
The subject of the message. Only present if message_type: email.
bodystringrequired
The message body, which may contain HTML.
message_typestringrequired
The type of message that was sent. Can be email, inapp, facebook or twitter.
Allowed:emailinappfacebooktwitter
conversation_idstringrequired
The associated conversation_id
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
403Returned when the API plan restricts access.

One documented failure

  • api_plan_restricted

    Active subscription needed.

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
404Returned when the contact is not found.

One documented failure

  • not_found

    User Not Found

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized, a 403 when the API plan restricts access, and a 404 when the contact is not found. If you send a request body, include from and body; from.type must be lead, user, or contact, and from.id must be a 24-character UUID.