Update Tags

Replaces the tags on a chat. The entire tag list must be sent in the payload: any tag on the chat that is not in the payload is removed, and an empty list removes them all.

Tags are how a chat reaches the reporting you already run on conversations and email. When the chat ends, Help Scout builds a transcript and creates a conversation from it, and the tags travel with it — chat tags are not a separate system.

Request

PUT /v2/chats/5a0da3c3-4882-3352-8db9-8fc47e14111f/tags HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json

{
  "tags": ["order-status", "vip-customer"]
}

Path Parameters

/v2/chats/{chatId}/tags

Request Body

Names only — a colour belongs to the tag itself rather than to applying one, so it is not part of this request. Names are lowercased, the same way they are when an agent adds a tag in the app.

Adding a tag

Send the tags the chat already has along with the new one. If the chat has order-status:

{
  "tags": ["order-status", "escalated"]
}

Removing one tag

List the tags to keep and leave out the one to remove:

{
  "tags": ["order-status"]
}

Removing all tags

{
  "tags": []
}

Sending the same list twice

Re-sending a list the chat already holds changes nothing and records nothing, so an integration can send its whole set on every pass without filling the chat’s history.

The chat must be open

Tagging a chat that has ended returns 404.

This is deliberate. The transcript that carries tags onto the conversation is built at the moment the chat ends, so a tag applied afterwards would land nowhere — it would not reach the conversation and it would not reach reporting. The endpoint refuses rather than silently doing nothing.

An integration listening for beacon.chat.ended is already too late. Tag while the chat is live — after classifying it, or before handing it to a person.

Concurrent changes

The last write wins. Because the payload is the whole list, a caller that reads the tags, adds one, and sends the list back will erase anything applied in between — including a tag an agent added in the app while the chat was live. This matches Update Tags for conversations.

On a live chat with both an integration and a person working it, that window is real. Read the chat immediately before writing, and use the response below to confirm what the chat now holds.

Response

200, with the chat, in the same shape Get Chat returns — so a caller sees the result of what it just did without a follow-up read. This is deliberately unlike the conversations endpoint, which answers 204: whole-list replace is read-modify-write, and returning the chat is what removes the second request.

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "id": "5a0da3c3-4882-3352-8db9-8fc47e14111f",
  "beaconId": "ed8e9fe0-acf4-4b44-b1fc-a5bff956e7a8",
  "mailboxId": 2599,
  "createdAt": "2020-07-03T07:03:29.982028Z",
  "customer": { "id": 498746, "type": "customer", "first": "Vernon", "last": "Bear" },
  "tags": [
    { "id": null, "slug": "order-status", "color": "none" },
    { "id": null, "slug": "vip-customer", "color": "none" }
  ],
  "_embedded": {
    "events": [ "..." ]
  },
  "_links": {
    "self": { "href": "..." }
  }
}

The full field reference is on Get Chat.

A tag applied through this endpoint carries id: null — the id belongs to the Help Scout tag, and a chat holds the name. Identify a chat tag by its slug, which is also what you send back.

The account’s tag is resolved when the conversation is created: a name that matches an existing tag’s slug uses that tag, and a name that matches nothing creates one.

What the chat’s history records

One line item per change, not per request. A request that adds two tags and removes one records three entries, which is what an agent making the same changes by hand would produce. They appear in _embedded.events with the actions tag-added and tag-removed.

Errors