Create Conversation

  • REST Method: POST
  • URL: https://api.helpscout.net/v1/conversations.json
  • Content-Type: application/json

Request

Name Type Required Default Notes
conversation Conversation Y   The body of the request (see example below).
imported boolean N false The 'imported' request parameter enables conversations 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.
autoReply boolean N false 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.
reload boolean N false Set this request parameter to true to return the created conversation in the response.
{
    "type": "email",
    "customer": {
        "id": 1234,
        "email": "customer@example.com"
    },
    "subject": "I need help",
    "mailbox": {
        "id": 4321
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "status": "active",
    "createdAt": "2012-07-23T12:34:12Z",
    "threads": [
        {
            "type": "customer",
            "createdBy": {
                "id": 1234,
                "email": "customer@example.com",
                "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"
                }
            ]
        }
    ],
    "customFields" : [
        {
            "fieldId": 10,
            "value": "Custom Support"
        },
        {
            "fieldId": 11,
            "value" : "10.5"
        },
        {
            "fieldId": 12,
            "value" : "2015-12-01 12:20:20"
        }
    ]
}

Accepted Conversation Fields

Name Type Required Default Notes
type string N email Options are 'email', 'chat' or 'phone'
customer Person Y   Must contain a valid customer id OR an email address.
  • If an id is specified, email is not required, but recommended.
  • 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).
  • Phone is recommended if the type of Conversation is 'phone'.
subject string Y    
mailbox MailboxRef Y    
tags Collection N   Collection of strings representing tags.
createdAt datetime N Current UTC date/time  
threads Collection Y   One or more Threads. See the next section for accepted thread fields.
customFields Collection N   One or more Custom Field responses

Accepted Thread Fields

Name Type Required Default Notes
type string Y   Options: note, message, customer, chat, phone.
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).
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 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.
state String N published Set to draft to create a draft.

Thread state:
  • draft
  • published

Response

Response Name Type Notes
Header Status Integer 201
Header Location String https://api.helpscout.net/v1/conversations/{id}.json
Status: 201 Created
Location: https://api.helpscout.net/v1/conversations/{id}.json