Create Reply Thread

Draft reply

It is possible to create a draft reply (AKA draft) by setting draft field to true.

Update a conversation owner for a published reply

If you create a reply thread that should be immediately published (draft is not set, or it is set to false), you can additionally specify the assignTo field to update the conversation owner. The owner can be updated as described for the Create Conversation endpoint.

If a draft reply is created, the conversation owner will not be updated until the reply is sent (published).

Request

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

{
  "customer" : {
    "id" : 123
  },
  "text" : "How are you?",
  "attachments" : [ {
    "fileName" : "file.txt",
    "mimeType" : "plain/text",
    "data" : "ZmlsZQ=="
  } ]
}

Request fields

Path Type Required Description
text String Y The reply
draft boolean N If set to true, a draft reply is created
customer Object Y Customer being replied to
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.
status String N Use this field to change conversation status when adding a thread. If not explicitly set, a reply thread will reactivate the conversation. Valid statuses:
active
all
closed
open
pending
spam
user Number N ID of the user who is adding the thread. The resource owner is the default when not set.
assignTo Number N The Help Scout user assigned to the conversation after the created thread is published.
cc Array N Collection of strings representing email addresses.
bcc Array N Collection of strings representing email addresses.
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

Response

HTTP/1.1 201 Created
Resource-ID: 567

Response Headers

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

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.

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 2025