Create message from conversation

post/v1/conversations/{id}/messages

Requires any one of these rolesAbout roles

org.permission.message.create

Legacyorg.user.message.write

The 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 from a conversation.

NOTE

The new message created by the endpoint will be associated with the same customer as the conversation.

Authorization

org.admin role is required for setting createdAt, createdBy, modifiedAt, and modifiedBy. Otherwise, the token automatically sets these attributes.

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.

About this resource

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

idstringrequired

Conversation ID.

Example "5faaf4a6ea0cb48cd0801bbf"

Request body

application/jsonrequired

idstring<object-id>

externalIdstring

max length 256

customerstring<object-id>

conversationstring<object-id>

object

channelstringrequired

One of"email""sms""chat""facebook""twitter-dm""twitter-tweet""voice""instagram""whatsapp"

previewstring

max length 10240

subjectstring

max length 256

directionstring

One of"in""out"

appstringrequired

sizenumber

relatedstring

statusstring

One of"sent""received""error"

objecterror

errorAtstring<date-time>

autoboolean

sentAtstring<date-time>

sourcestring

One of"bulk""satisfaction"

shortcutsarray<string<object-id>>

kbArticlesarray<string<object-id>>

anyOf

object

metaobject

customobjectcustom_attrs

objectsentiment

createdAtstring<date-time>

modifiedAtstring<date-time>

createdBystring<object-id>

modifiedBystring<object-id>

importedAtstring<date-time>

langstringlangnullable

max length 100

object

Responses

Created

objectrequired

Open in the API console

curl --request POST \
  --url 'https://api.kustomerapp.com/v1/conversations/5faaf4a6ea0cb48cd0801bbf/messages' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "crm-10293",
  "channel": "email",
  "preview": "Example text",
  "subject": "Example title",
  "direction": "in",
  "app": "string"
}'

{
  "data": {
    "type": "message",
    "id": "57a6082ae92c9510005e35ea",
    "attributes": {
      "channel": "email",
      "app": "postmark",
      "size": 1,
      "direction": "in",
      "meta": {},
      "status": "received",
      "sentAt": "2016-11-13T15:44:35.625Z",
      "createdAt": "2016-05-22T22:42:44.723Z",
      "updatedAt": "2016-11-13T15:44:35.625Z",
      "modifiedAt": "2016-11-13T15:44:35.625Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/57bb5d2e32e83a130052e94e"
        },
        "data": {
          "type": "org",
          "id": "57bb5d2e32e83a130052e94e"
        }
      },
      "createdBy": {
        "links": {
          "self": "/v1/users/57bb5d2e32e83a130052e94f"
        },
        "data": {
          "type": "user",
          "id": "57bb5d2e32e83a130052e94f"
        }
      },
      "modifiedBy": {
        "links": {
          "self": "/v1/users/57bb5d2e32e83a130052e94f"
        },
        "data": {
          "type": "user",
          "id": "57bb5d2e32e83a130052e94f"
        }
      },
      "customer": {
        "links": {
          "self": "/v1/customers/57c08ccde595371400462df2"
        },
        "data": {
          "type": "customers",
          "id": "57c08ccde595371400462df2"
        }
      },
      "conversation": {
        "links": {
          "self": "/v1/conversations/58288a637c7f551a00b5b716"
        },
        "data": {
          "type": "conversation",
          "id": "58288a637c7f551a00b5b716"
        }
      }
    },
    "links": {
      "self": "/v1/messages/57a6082ae92c9510005e35ea"
    }
  }
}