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": []
}