Create Conversation

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

How to define a customer

There are two ways how to define a customer when creating a conversations - either via id:

{
  "customer" : {
    "id" : 100
  }
}

or via email:

{
  "customer" : {
    "email" : "bear@acme.com",
    "firstName" : "Vernon",
    "lastName" : "Bear",
    ...
  }
}

If a customer with this email doesn’t exist yet, the API will create a new customer — using all the optional fields.

Creating a draft conversation

To create a draft conversation, use the reply thread type with draft set to true.

Request

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

{
  "subject" : "Subject",
  "customer" : {
    "email" : "bear@acme.com",
    "firstName" : "Vernon",
    "lastName" : "Bear"
  },
  "mailboxId" : 85,
  "type" : "email",
  "status" : "active",
  "createdAt" : "2012-10-10T12:00:00Z",
  "threads" : [ {
    "type" : "customer",
    "customer" : {
      "email" : "bear@acme.com"
    },
    "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 8601 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.
closedAt String N When the conversation was closed, only applicable for imported conversations - ISO 8601 date time

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

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
Set-Cookie: JSESSIONID=F35AC8AA7BFCCF55D84C9DE37A08F6C7; Path=/; HttpOnly
Resource-ID: 123
Location: https://api.helpscout.net/v2/conversations/123
Web-Location: https://secure.helpscout.net/conversation/123/89

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.

↑Back to top
© Help Scout 2024