Inbox tags

Lists all tags for a chatbot

get

Required Permission: chatbots.tags.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Responses

200

List of all tags.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/inbox/{chatbotId}/tags

HTTPcURLJavaScriptPython

GET /v1/inbox/{chatbotId}/tags HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "tags": [
    {
      "id": "kMA97ZQweaES0FGU25cl",
      "created": "2025-10-06T18:00:00Z",
      "updated": "2025-10-06T18:05:00Z",
      "name": "Important",
      "color": "#FF0000"
    }
  ],
  "error": "text"
}

Creates a new tag

post

Required Permission: chatbots.tags.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

namestringRequired

The name of the new tag.

Example: VIP Customer

colorstringRequired

The color of the tag.

Example: blue

Responses

201

Tag created successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/inbox/{chatbotId}/tags

HTTPcURLJavaScriptPython

POST /v1/inbox/{chatbotId}/tags HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "name": "VIP Customer",
  "color": "blue"
}

{
  "tag": {
    "id": "kMA97ZQweaES0FGU25cl",
    "created": "2025-10-06T18:00:00Z",
    "updated": "2025-10-06T18:05:00Z",
    "name": "Important",
    "color": "#FF0000"
  },
  "error": "text"
}

Retrieves a specific tag

get

Required Permission: chatbots.tags.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

tagIdstringRequired

The ID of the tag to retrieve.

Responses

200

Details of the tag.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

404

Tag not found.

get

/v1/inbox/{chatbotId}/tags/{tagId}

HTTPcURLJavaScriptPython

GET /v1/inbox/{chatbotId}/tags/{tagId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "tag": {
    "id": "kMA97ZQweaES0FGU25cl",
    "created": "2025-10-06T18:00:00Z",
    "updated": "2025-10-06T18:05:00Z",
    "name": "Important",
    "color": "#FF0000"
  },
  "error": "text"
}

Deletes a tag

delete

Required Permission: chatbots.tags.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

tagIdstringRequired

The ID of the tag to delete.

Responses

200

Tag deleted successfully.

No content

403

Insufficient permissions.

delete

/v1/inbox/{chatbotId}/tags/{tagId}

HTTPcURLJavaScriptPython

DELETE /v1/inbox/{chatbotId}/tags/{tagId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

No content

Updates an existing tag

patch

Required Permission: chatbots.tags.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

tagIdstringRequired

The ID of the tag to update.

Body

application/json

namestringRequired

The new name of the tag.

Example: High Priority

colorstringRequired

The new color of the tag.

Example: dark_green

Responses

200

Tag updated successfully.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

patch

/v1/inbox/{chatbotId}/tags/{tagId}

HTTPcURLJavaScriptPython

PATCH /v1/inbox/{chatbotId}/tags/{tagId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "name": "High Priority",
  "color": "dark_green"
}

{
  "tag": {
    "id": "kMA97ZQweaES0FGU25cl",
    "created": "2025-10-06T18:00:00Z",
    "updated": "2025-10-06T18:05:00Z",
    "name": "Important",
    "color": "#FF0000"
  },
  "error": "text"
}