Create Chat Thread

Request

POST /v2/conversations/123/chats HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json

{
  "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

Request fields

Path Type Required Description
id Number N Customer ID
email String N Customer’s email
firstName String N First name of the customer. When defined it must be between 1 and 40 characters.
lastName String N Last name of the customer. When defined it must be between 1 and 40 characters.
phone String N Optional phone number that will be used when creating a new customer
photoUrl String N URL of the customer’s photo. Max length 200 characters.
jobTitle String N Job title. Max length 60 characters.
photoType String N Type of photo. Accepted values are:
unknown
gravatar
twitter
facebook
googleprofile
googleplus
linkedin
instagram
background String N This is the Notes field from the user interface. Max length 200 characters.
location String N Location of the customer. Max length 60 characters.
organization String N Organization. Max length 60 characters.
gender String N Gender of this customer. Accepted values are:
male
female
unknown
age String N Customer’s age

Request fields

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
Set-Cookie: JSESSIONID=7F7613CD0D2FD0FD4ED55C0BB4B5F4A4; Path=/; HttpOnly
Resource-ID: 567

Response Headers

Name Description
Resource-Id Internal ID of the newly created thread

Moved or merged conversations

When a conversation 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 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.

Locked conversation - too old

Company policy can prevent old conversations to be updated. If you try to add a new thread to a conversation when when this policy is active, the API will return HTTP 412 Precondition failed error.

Conversation status change

When a thread of this type is added to a conversation, the conversation will be reopened unless the thread is imported (signalled by imported: true field value).

↑Back to top
© Help Scout 2024