Conversation Tags

A conversation tag is a named 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",
  "created_at": "2026-05-01T09:14:22+00:00"
}

string

required

Always "conversation_tag".

string

required

UUID. Reference this when assigning to a conversation.

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.

string

required

ISO 8601 timestamp.

Create a tag

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

await fetch("https://api.awardee.com/v1/conversation-tags", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AWARDEE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "billing" }),
})

requests.post(
    "https://api.awardee.com/v1/conversation-tags",
    headers={
        "Authorization": f"Bearer {os.environ['AWARDEE_KEY']}",
        "Content-Type": "application/json",
    },
    json={"name": "billing"},
)

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.com/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"
    ]
  }'

await fetch(
  "https://api.awardee.com/v1/conversations/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/tags",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.AWARDEE_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tag_ids: [
        "a3c5e7d9-1b2f-4a6c-9e8d-7c5b3a1e0f9d",
        "b4d6f8e0-2c3a-4b7d-9f8e-8d6c4b2a0e1f",
      ],
    }),
  }
)

requests.put(
    "https://api.awardee.com/v1/conversations/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/tags",
    headers={
        "Authorization": f"Bearer {os.environ['AWARDEE_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "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.

Fetch the palette

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

On each message.created

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

PUT the full set

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

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

Conversation Tags

Anatomy

Create a tag

Assigning tags to a conversation

Listing tags on a conversation

Deleting a tag

Tag the entire backlog by topic

​Anatomy

​Create a tag

​Assigning tags to a conversation

​Listing tags on a conversation

​Deleting a tag

​Tag the entire backlog by topic

Anatomy

Create a tag

Assigning tags to a conversation

Listing tags on a conversation

Deleting a tag

Tag the entire backlog by topic