Skip to content
Home/
/Messages

Messages

Everything about your messages

Schemas
Operations

Create a message

Request

You can create a message that has been initiated by an admin. The conversation can be either an in-app message, an email, sms or whatsapp.

🚧 Sending for visitors

There can be a short delay between when a contact is created and when a contact becomes available to be messaged through the API. A 404 Not Found error will be returned in this case.

This will return the Message model that has been created.

🚧 Retrieving Associated Conversations

As this is a message, there will be no conversation present until the contact responds. Once they do, you will have to search for a contact's conversations with the id of the message.

Messages from contacts

from should be an admin. A request with a user or lead as from is not rejected: it creates a conversation initiated by that contact, as the Create a conversation endpoint (POST /conversations) does, and the to, cc and bcc fields are ignored. To create a conversation initiated by a contact, use POST /conversations.

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:Preview
Bodyapplication/json
Any of:

You can create a message

message_typestring

The kind of message being created. Values: in_app, email, sms or whatsapp. inapp is also accepted for in-app messages, and responses always show in-app messages as inapp.

Enum:"in_app""inapp""email""sms""whatsapp"
Example:"in_app"
subjectstring

The title of the email.

Example:"Thanks for everything"
bodystring

The content of the message. HTML and plaintext are supported.

Example:"Hello there"
templatestring

The style of the outgoing message. Possible values plain or personal.

Example:"plain"
fromobject

The sender of the message. If not provided, the default sender will be used.

toRecipient (object) or Array of objects or WhatsApp recipient (object)
One of:

A recipient of a message

ccRecipient (object) or Array of objects
One of:

A recipient of a message

bccRecipient (object) or Array of objects
One of:

A recipient of a message

created_atinteger

The time the message was created. If not provided, the current time will be used.

Example:1590000000
create_conversation_without_contact_replyboolean

Whether a conversation should be opened in the inbox for the message without the contact replying. Defaults to false if not provided.

Default:false
Example:true
componentsArray of objects

The components of the WhatsApp template, with the values for its variables. Required for whatsapp messages.

Example:
[
  {
    "type": "BODY",
    "parameters": [ … ]
  }
]
localestring

The locale of the WhatsApp template to send, such as en. If you leave it out, the contact's messenger locale is used, then the workspace locale. A template that isn't available in the locale returns a 400 error.

Example:"en"
brand_idstring

The id of the brand to send the message from. Not used for whatsapp messages. A brand that doesn't exist returns a 400 error.

Example:"1234"
curl -i -X POST \
  https://api.intercom.io/messages \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "from": {
      "type": "user",
      "id": "6762f2341bb69f9f2193bc17"
    },
    "body": "heyy",
    "referer": "https://twitter.com/bob"
  }'

Responses

admin message 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, sms or whatsapp.

Enum:"email""inapp""facebook""twitter""sms""whatsapp"
Example:"inapp"
conversation_idstring

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": "403918396",
  "created_at": 1734537780,
  "body": "heyy",
  "message_type": "inapp",
  "conversation_id": "613"
}