Create Chat Thread

Request

POST /v2/conversations/123/chats HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json; charset=UTF-8

{
  "customer" : {
    "id" : 456
  },
  "text" : "Buy more pens",
  "attachments" : [ {
    "fileName" : "file.txt",
    "mimeType" : "plain/text",
    "data" : "ZmlsZQ=="
  } ]
}

Request fields

Path Type Required Description
text String Y The chat text
customer Object Y Customer associated with the chat. Must contain a valid customer id or an email address. If the id field is defined,
the email will be ignored. If the id is not defined, email is used to look up a customer. If a customer with the email in question does not exist a new one will be created, using all the optional fields and email.

If a customer is matched either via id or email field, the rest of the optional fields is ignored.
imported Boolean N The imported field enables thread to be created for historical purposes
(i.e. if moving from a different platform, you can import your history).
When imported is set to true, no outgoing emails or notifications will be generated.
createdAt String N Optional creation date to be used when importing conversations and threads. It can only be used with imported field set to true
attachments Array N Optional list of attachments to be attached to this thread

Customer

Path Type Required Description
id Number N Customer ID
email String N Customer’s email
firstName String N First name of the customer. Must be shorter than 40 characters
lastName String N Last name of the customer. Must be shorter than 40 characters
photoUrl String N URL of the customer’s photo
jobTitle String N Job title
photoType String N Type of photo. Possible values include:
unknown
gravatar
twitter
facebook
googleprofile
googleplus
linkedin
background String N This is the Notes field from the user interface.
location String N Location of the customer
createdAt String N Time and date when the customer was created (UTC)
updatedAt String N Time and date when the customer was update (UTC)
organization String N Organization
gender String N Gender of this customer. Possible values include:
male
female
unknown
age String N Customer’s age

Attachments

Path Type Required Description
[].fileName String Y Attachment’s file name
[].mimeType String Y Attachment’s mime type
[].data String Y Base64-encoded stream of data.

Response

HTTP/1.1 201 Created

Moved or merged conversations

When a conversation is moved to a new mailbox or it is merged with another conversation, it is no longer accessible using the old ID. Get Conversation endpoint will return a HTTP 301 Moved Permanently status code and the response will contain a Location header with the URI of the new conversation.

This request will return a HTTP 404 Not Found in such case. If you suspect the conversation you are trying to change was moved or merged, call the Get Conversation endpoint to get a new conversation location.

Locked conversation - maximum number of threads

A single conversation can contain up to 100 threads. If you try to create conversation with more than 100 threads or add a thread to a conversation that has 99 threads or more, the API will return HTTP 412 Precondition failed error.