Create Conversation

Creates a conversation in an inbox 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.

How to define a conversation owner

The conversation owner can be defined in multiple ways. If you want the conversation to be assigned to the specific user, it is as easy as providing that user’s ID in the payload:

{
  "assignTo": 234
}

If the conversation should be created with an assignee set according to the Inbox settings (for conversations with replies), the request payload should not contain the assignTo field at all.

However, if you want to ensure the conversation remains unassigned regardless of the Inbox settings, then the request payload should contain the assignTo field explicitly set to null:

{
  "assignTo": null
}

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

Request fields

Threads

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

Thread attachments

Note: The uploaded attachments will be scanned. In case of detecting malicious content, the affected attachments won’t be accessible.

Response

HTTP/1.1 201 Created
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.