Create Conversation Thread

  • REST Method: POST
  • URL: https://api.helpscout.net/v1/conversations/{id}.json
  • Content-Type: application/json
Please note that threads cannot be added to conversations with 100 threads (or more), if attempted the API will respond with HTTP 412.

Response codes

Code Description
200 when exists and it is not deleted, moved, merged, etc
301 The conversation exists under a different ID because it has either been moved or merged. The location header contains the location of the moved entity
404 when conversation does not exists or it is deleted

Request

Name Type Required Default Notes
thread ConversationThread Y   The body of the request (see example below).
imported boolean N false When the 'imported' request parameter is set to true, no outgoing emails or notifications will be generated.
reload boolean N false Set this request parameter to true to return the entire conversation in the response.
{
    "createdBy": {
        "id": 1234,
        "email": "customer@example.com",
        "type": "customer"
    },
    "type": "customer",
    "body": "I need your help with an issue I'm having.",
    "assignedTo": {
        "id": 2222
    },
    "status": "active",
    "createdAt": "2012-07-23T12:34:12Z",
    "cc": [
        "user1@example.com",
        "user2@example.com"
    ],
    "bcc": [
        "user3@example.com",
        "user4@example.com"
    ],
    "attachments": [
        {
            "hash": "7gjj3dg7fs3cvi956jjgfsw"
        },
        {
            "hash": "hfsf63fjgle8jglglksd285"
        }
    ]
}

Accepted Fields

Name Type Required Default Notes
createdBy Person Y   Set the 'type' property on the Person to specify 'user' or 'customer'. The 'type' property is required for this field.
  • If the type of thread is 'message' or 'note' this must be a user.
  • If the type of thread is 'customer' this must be a customer.
  • If the type of thread is 'chat' or 'phone' this can be either 'user' or 'customer'.
Depending on the type of Person, some fields are required:
  • If the type is 'user', id is required.
  • If the type is 'customer', id OR email is required. If an id is not specified, the customer will be looked up by email. If no customer exists with the email, it will be created (specifying first and last name is recommended).
type string Y   Options: note, message, customer, chat
body string Y    
assignedTo Person N anyone The Help Scout user assigned to the conversation.
status string N active Options: active, pending, closed, spam
createdAt datetime N now Defaults to current UTC date/time
cc Collection N empty Collection of strings representing email addresses.
bcc Collection N empty Collection of strings representing email addresses.
attachments Collection N empty Collection of Attachment objects. An Attachment must be sent to the API prior to including it with a new conversation or thread. The Attachment 'hash' property is required. See the Create Attachment documentation for more information.

Response

Response Name Type Notes
Header Status Integer 201
Status: 201 Created