Create message by customer ID
/v1/customers/{id}/messagesorg.permission.message.createorg.user.message.writeThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Creates a new message based on the unique customer ID.
Note
If a conversation is specified, the message will be linked to the existing conversation. Otherwise, a new conversation will be created and associated with the message.
Authorization
The org.admin role is required for setting createdAt, createdBy, modifiedAt, and modifiedBy. Otherwise, these attributes are automatically set by the token.
Rate Limit
Messages are subject to a rate limit. A single client can create up to 120 messages per minute per customer.
Messages with importedAt in their body will not be subject to the rate limit.
A 429 Too Many Requests response will be returned if the rate limit has been reached for a customer.
Messages
A message is one communication between your team and a customer, such as an email, a chat line, a text, a call or a social post, recorded inside a conversation. Creating one through the API records it on the timeline; it does not deliver anything.
Messages are the customer-visible part of a conversation. Each one belongs to a conversation and to that conversation's customer, and agents see them in order on the customer's timeline. Kustomer's native channels create messages automatically: an inbound email or chat line becomes an in message, and when an agent replies, the sent reply becomes an out message. You create messages through the API to bring in conversations from somewhere Kustomer doesn't connect to natively, to import history, or to record something your own system already sent.
Channel, app and direction
| Field | Meaning |
|---|---|
channel |
The kind of communication: email, sms, chat, facebook, twitter-dm, twitter-tweet, voice, instagram or whatsapp. Required. Responses can also contain channels you can't create, such as instagram-comment or form. |
app |
Which integration produced the message, such as your own acme-inbox. Required. Use one stable value per integration so you can recognize your own records. |
direction |
in from the customer, out to the customer. |
status |
received, sent or error, with details in error and errorAt when delivery failed. |
preview holds the text (up to 10,240 characters), subject the subject line for channels that have one, and meta any channel-specific details, such as from and to addresses. sentAt is when the message was sent in the source system, and it decides where the message sits on the timeline. auto: true marks automated messages, which are left out of reporting metrics. For email, reference links a reply, reply-all or forward to the message it answers. Files go in attachments; upload them first, as described in Upload attachments.
Recorded, not sent
An out message you create through the API is a record of something already delivered. Kustomer does not send it to the customer by email, SMS or chat. To have Kustomer deliver a reply through a connected channel, create a draft and send it. Kustomer then records the resulting out message for you.
Messages can't be deleted through the API. To remove sensitive content, such as a card number a customer pasted into chat, redact the message. You supply replacement preview text, a replacement meta object, or the IDs of up to 10 of the message's attachments to redact, and the replacements overwrite the original content. Redacted attachments are marked redacted: true and their files are no longer available.
Which endpoint to use
| To | Call |
|---|---|
| Add a message to a conversation you already track | POST /v1/conversations/{id}/messages, or POST /v1/messages with conversation in the body |
Add a message for a customer, creating a conversation unless you pass conversation |
POST /v1/customers/{id}/messages |
| Read or update a message | GET, PUT or PATCH /v1/messages/{id} |
| Check whether you've already imported a message | GET /v1/messages/externalId={externalId} |
| List a conversation's messages | GET /v1/conversations/{id}/messages, optionally filtered by channel |
| List a customer's messages across conversations | GET /v1/customers/{id}/messages |
| Page through all messages | GET /v1/messages |
| Remove sensitive content | POST /v1/messages/{id}/redactions |
| Import or update up to 100 messages per request | POST or PUT /v1/messages/bulk |
A client can create 120 messages per customer per minute; set importedAt on historical imports to skip that limit, and keep sentAt as the original send time. One message can be updated 100 times in 10 minutes. Only tokens with the org.admin role can set createdAt, createdBy, modifiedAt and modifiedBy. Set externalId to the source system's message ID so retries don't create duplicates. To import history, create customers and conversations before their messages, as in Bulk operations.
Path parameters
Customer ID.
"5f8efdd5d3de932f344ca367"Request body
application/jsonrequiredCreates a new message.
Any one of the following roles is required for this endpoint:
|Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.create|
### Note If a conversation is specified, the message will be linked to the existing conversation. Otherwise, a new conversation will be created and associated with the message.
### Authorization The org.admin role is required for setting createdAt, createdBy, modifiedAt, and modifiedBy. Otherwise, these attributes are automatically set by the token.
### Rate Limit Messages are subject to a rate limit. A single client can create up to 120 messages per minute per customer. Messages with importedAt in their body will not be subject to the rate limit.
A 429 Too Many Requests response will be returned if the rate limit has been reached for a customer.
"email""sms""chat""facebook""twitter-dm""twitter-tweet""voice""instagram""whatsapp""in""out""sent""received""error""bulk""satisfaction"Responses
Created