Add Conversation Tag

Add a tag to a conversation. Supply its conversation_id in the path and the tag name in the JSON body. Obtain conversation_id from List Conversations or data.conversation.id in a message webhook.

Tags belong to the conversation's contact, so the tag also appears on the contact's other conversations. An existing tag with this name is reused; otherwise a new tag is created. Adding a tag the contact already has keeps it attached once and does not run tag-added automations or webhooks again, so it is safe to retry. Tags require a Pro plan; on other plans the request returns 403.

Returns 200 OK with the conversation, contact and tag name.

POST https://developers.chatway.app/api/v1/conversations/{conversation_id}/tags

Example request

curl -X POST "https://developers.chatway.app/api/v1/conversations/0f46c0a1-8938-40e3-b2b5-bb56f569fcab/tags" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vip"
}'

Parameters

Request body

application/json

• name (string, required) — Tag name, up to 100 characters.
• color (string|null) — Optional tag color, for example a hex code. If the tag already exists, its color is changed to this value.

Responses

200

application/json

• message (string, required)
• data (object, required)
  • conversation_id (string, required)
  • contact_id (string, required)
  • tag (string, required)

422

403

Tags require a Pro plan

application/json

• message (string, required)

404

Conversation not found

application/json

• message (string, required)

Examples

Request body example

{
    "name": "vip"
}

Response 200 example

{
    "message": "Tag added.",
    "data": {
        "conversation_id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
        "contact_id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
        "tag": "vip"
    }
}