Intercom API (unofficial showcase)
POST/messages

Create a message

Creates a message initiated by an admin as an in-app message, email, or WhatsApp message. Choose a message_type and provide the fields required for that type, including a sender and recipient. Set from.type to admin; using a user or lead as the sender instead creates a contact-initiated conversation and causes to, cc, and bcc to be ignored.

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

1 parameter · 10 body fields
Intercom-Versionstringoptional
The API version to use. Defaults to 2.17 when omitted; supported values include 1.0 through 1.4 and 2.0 through 2.6.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Message details. Required fields depend on message_type: email requires subject, body, template, from, and to; in-app requires body, from, and to; WhatsApp requires template, components, from, and to.

message_typestringrequired
The kind of message being created. Values: `in_app`, `email` or `whatsapp`.
Allowed:in_appemailwhatsapp
subjectstringrequired
The title of the email.
bodystringrequired
The content of the message. HTML and plaintext are supported.
templatestringrequired
The style of the outgoing message. Possible values `plain` or `personal`.
fromobjectrequired
The sender of the message. If not provided, the default sender will be used.
toobjectrequired
One recipient object or an array of recipient objects; each recipient has a `type` and `id`.
ccobjectoptional
One CC recipient object or an array of recipient objects; each recipient has a `type` and `id`.
bccobjectoptional
One BCC recipient object or an array of recipient objects; each recipient has a `type` and `id`.
created_atintegeroptional
The time the message was created. If not provided, the current time will be used.
create_conversation_without_contact_replybooleanoptional
Whether a conversation should be opened in the inbox for the message without the contact replying. Defaults to false if not provided.
Default:false

5 status codes
200Returns the created message, including its identifier, creation time, body, message type, and conversation identifier when available.
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_idstringoptional
The associated conversation_id
400Returned when an email message has no body.

One documented failure

  • parameter_invalid

    Body is required

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
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 this operation.

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
422Returned when an email message has no subject.

One documented failure

  • parameter_not_found

    No subject supplied for email message

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

Error handling

A 400 is returned when an email message has no body. A 401 is returned when the request is unauthorized. A 403 is returned when the API plan restricts this operation. A 422 is returned when an email message has no subject. Set message_type to in_app, email, or whatsapp and supply the fields required for that type; from.type must be admin to create an admin-initiated message.