Skip to main content
A conversation tag is a named, colored label scoped to your organization. Tags live in a shared palette under /conversation-tags and attach to conversations many-to-many under /conversations/{id}/tags.

​
Anatomy

{
  "object": "conversation_tag",
  "id": "a3c5e7d9-1b2f-4a6c-9e8d-7c5b3a1e0f9d",
  "name": "billing",
  "color": "#FFB020",
  "created_at": "2026-05-01T09:14:22+00:00"
}
​
object
string
required
Always "conversation_tag".
​
id
string
required
UUID. Reference this when assigning to a conversation.
​
name
string
required
Display label, max 100 characters. Unique per org, case-insensitively — billing and Billing collide and cannot both exist. Creating a tag whose name matches an existing one (ignoring case) returns a conflict.
​
color
string | null
Hex color in #RRGGBB form (e.g. #FFB020) used in the dashboard. Send null (or omit it) to fall back to the default palette color. Any other string is rejected with 400 invalid_payload.
​
created_at
string
required
ISO 8601 timestamp.

​
Create a tag

curl -X POST https://api.awardee.dev/v1/conversation-tags \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "billing", "color": "#FFB020"}'

​
Assigning tags to a conversation

PUT /conversations/{id}/tags uses replace-set semantics — the array you send becomes the conversation’s full tag set. There’s no separate add/remove endpoint; send [] to clear all tags. 
curl -X PUT https://api.awardee.dev/v1/conversations/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/tags \
  -H "Authorization: Bearer aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      "a3c5e7d9-1b2f-4a6c-9e8d-7c5b3a1e0f9d",
      "b4d6f8e0-2c3a-4b7d-9f8e-8d6c4b2a0e1f"
    ]
  }'
Because assignment is a replace-set, you don’t need to diff against the current tags. Compute the full desired set in one place (a classifier, a rules engine) and PUT it. Idempotent by construction.

​
Listing tags on a conversation

GET /v1/conversations/{id}/tags
Returns the full assigned set with the same shape as /conversation-tags list items.

​
Deleting a tag

DELETE /conversation-tags/{id} removes the tag from the org-level palette and unassigns it from every conversation it was attached to. There’s no soft-delete — gone is gone.
Deleting a tag is irreversible and fans out to all conversations that referenced it. Rename via the dashboard if you just want a different label.

​
Tag the entire backlog by topic

A common workflow: route on message.created, run your own classifier, then snap the predicted tag set onto the conversation.
1

Fetch the palette

GET /conversation-tags once, cache by name → id locally.
2

On each message.created

Classify the visitor’s turn. Translate predicted labels to IDs from your cache.
3

PUT the full set

PUT /conversations/{id}/tags with the merged set (existing tags you want to keep, plus any new ones).