We're upgrading our API

On June 6th, 2019, Mailbox API 1.0 will be sunsetted, and at that time any apps using this legacy API will no longer work. Please use Mailbox API 2.0 instead.

Update Conversation

  • REST Method: PUT
  • URL: https://api.helpscout.net/v1/conversations/{id}.json
  • Content-Type: application/json

Request

Name Type Required Default Options Notes
conversation Conversation Y     The body of the request (see example below).
reload boolean N false   Set this request parameter to true to return the updated conversation in the response.

Response codes

Code Description
200 conversation was found
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
{
    "subject": "I need help",
    "status": "closed",
    "owner": {
        "id": 2222,
        "type": "user"
    },
    "mailbox": {
        "id": 4321
    },
    "tags": [
        "tag1",
        "tag2"
    ],
    "customFields" : [
        {
            "fieldId": 10,
            "value": "Custom Support"
        },
        {
            "fieldId": 11,
            "value" : "10.5"
        },
        {
            "fieldId": 12,
            "value" : "2015-12-01 12:20:20"
        }
    ]
}

Accepted Fields

Name Type Required Default Notes
subject string N    
status string N   Options: active, pending, closed, spam
owner Person N   The Help Scout user assigned to the conversation.
mailbox MailboxRef Y    
tags Collection N   Collection of strings representing tags.
customFields Collection N   One or more Custom Field responses

Response

Response Name Type Notes
Header Status Integer 200
Status: 200 OK

Examples

Updating Existing Tags

To update a conversation's existing tags, send a request that contains the new tags, along with any old ones. For example, if conversation 1 has tag a, send this request to add tag b:

{ "tags": [ "tag a", "tag b" ] }

Removing All Tags

To remove all tags from a conversation, send a request containing an empty array of tags. For example, if conversation 1 has tag a and tag b, send this request to remove both tags:

{ "tags": [] }

Removing Only One Tag

To remove only one tag from a conversation, send a request that omits the tag you want to delete, while including the other tags. For example, if conversation 1 has tag a and tag b, send this request to remove only tag b:

{ "tags": [ "tag a" ] }

Updating Without Changing Tags

To update a conversation without changing its tags, send a request that omits the tags completely, while updating the other field(s) you want. For example, if conversation 1 has a subject of "Help!" and a tag of tag a, send this request to update the subject only:

{ "subject": "Help! - updated" }

Assigning Conversations

To assign a conversation to an existing user, send a request that sets the desired owner. For example, if conversation 1 is unassigned, send this request to assign the conversation to user 123:

{ "owner": 123 }

Unassigning Conversations

To unassign a conversation, send a request that sets the owner to null. For example, if conversation 1 is assigned to user 123, send this request to unassign the conversation:

{ "owner": null }

Updating Custom Field Responses

Custom fields are updated the same way as tags - omit existing field and it will be removed, add a new one and it will be added, change a value and it will be updated. Our conversation has two custom field responses (123, 234) and we want to keep one (123) and remove the other:

{
    "fields": [ { "fieldId" : 123, "value" : "Free" } ]
}

Clearing Custom Field Responses

Send empty array to clear all custom field responses

{
    "fields": []
}