Create Conversation

Creates a conversation in a mailbox with at least one thread.

Request

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

{
  "subject" : "Subject",
  "customer" : {
    "id" : 100
  },
  "mailboxId" : 85,
  "type" : "email",
  "status" : "active",
  "createdAt" : "2012-10-10T12:00:00Z",
  "threads" : [ {
    "type" : "customer",
    "customer" : {
      "id" : 100
    },
    "text" : "Hello, Help Scout. How are you?"
  } ],
  "tags" : [ "vip" ],
  "fields" : [ {
    "id" : 531,
    "value" : "trial"
  } ]
}

Request fields

Path Type Required Description
subject String Y Conversation’s subject
autoReply Boolean N The autoReply request parameter enables auto replies to be sent
when a conversation is created via the API. When autoReply is set to true, an auto reply will be sent
as long as there is at least one customer thread in the conversation.
imported Boolean N The imported field enables conversation 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.
type String Y Conversation type, one of:
chat
email
phone
assignTo Number N The Help Scout user assigned to the conversation.
mailboxId Number Y ID of a mailbox where the conversation is being created
status String Y Conversation status, one of
active
closed
pending
createdAt String N When this conversation was created - ISO 8061 date time
customer Object Y Customer associated with the conversation. 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.
threads Array Y Conversation threads. There has to be least one thread in a conversation
tags Array N List of tags to be be added to the conversation
fields Array N List of custom fields and values to be set for the conversation, see Update Custom Fields for details
user Number N ID of the user who is adding the conversation and threads. The resource owner is used when not set. The value can be also overridden for some thread types.

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

Threads

Every thread object has to have type field while the remaining fields are defined in the documentation for individual threads:

type Request fields documentation
note Create Note
chat Create Chat
phone Create Phone
reply Create Reply
customer Create Customer Thread

Response

HTTP/1.1 201 Created
Resource-ID: 123
Location: https://api.helpscout.net/v2/conversations/123

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.