Chatbot variables

Lists all global variables for a chatbot

get

Required Permission: chatbots.variables.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

filtersstringOptional

Filters variables by categories. Separate multiple filters with commas.

• 0: CUSTOM
• 1: APP
• 2: Entity

Example: 0,1

Responses

200

List of all global variables.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/variables

HTTPcURLJavaScriptPython

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

{
  "variables": [
    {
      "id": "gS9DWxRHUuRI9yDUjiWw",
      "name": "customer_name",
      "defaultValue": "Default value",
      "category": "custom",
      "label": "Customer Name",
      "type": "string",
      "readonly": false,
      "created": "2025-10-04T10:00:00Z",
      "updated": "2025-10-04T10:05:00Z",
      "structureJson": "{\"firstName\": \"string\", \"lastName\": \"string\"}"
    }
  ],
  "error": "text"
}

Creates a new global variable

post

Required Permission: chatbots.variables.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

categorystring · enumRequired

The category of the variable.

Example: customPossible values:

defaultValuestringOptional

An optional default value for the variable.

Example: Default Value

labelstringRequired

The human-readable label of the variable.

Example: Customer Email

typestringRequired

The data type of the variable (e.g., "string", "number", "boolean", "object").

Example: string

namestringRequired

The programmatic name of the variable.

Example: customer_email

structureJsonstring · jsonOptional

A JSON string defining the structure for object variables.

Example: {"firstName": "string", "lastName": "string"}

subCategorynumber · enumRequired

Sets the subCategory of the variable.

• 0: GLOBAL_VARIABLE_SUB_CATEGORY_CONVERSATION
• 1: GLOBAL_VARIABLE_SUB_CATEGORY_CONTACT

Possible values:

Responses

201

Global variable created successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/variables

HTTPcURLJavaScriptPython

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

{
  "category": "custom",
  "defaultValue": "Default Value",
  "label": "Customer Email",
  "type": "string",
  "name": "customer_email",
  "structureJson": "{\"firstName\": \"string\", \"lastName\": \"string\"}",
  "subCategory": 0
}

{
  "variable": {
    "id": "gS9DWxRHUuRI9yDUjiWw",
    "name": "customer_name",
    "defaultValue": "Default value",
    "category": "custom",
    "label": "Customer Name",
    "type": "string",
    "readonly": false,
    "created": "2025-10-04T10:00:00Z",
    "updated": "2025-10-04T10:05:00Z",
    "structureJson": "{\"firstName\": \"string\", \"lastName\": \"string\"}"
  }
}

Deletes a global variable

delete

Required Permission: chatbots.variables.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

variableIdstringRequired

The ID of the variable to be deleted.

Responses

200

Result of the deletion process.

application/json

deletedbooleanOptional

Indicates whether the variable was successfully deleted.

Example: true

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/variables/{variableId}

HTTPcURLJavaScriptPython

DELETE /v1/chatbots/{chatbotId}/variables/{variableId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true
}

Updates an existing global variable

patch

Required Permission: chatbots.variables.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

variableIdstringRequired

The ID of the variable to be updated.

Body

application/json

defaultValuestringOptional

The new default value.

Example: Updated Default

labelstringOptional

The new label.

Example: Updated Label

namestringOptional

The new programmatic name.

Example: updated_variable_name

Responses

200

Global variable updated successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/variables/{variableId}

HTTPcURLJavaScriptPython

PATCH /v1/chatbots/{chatbotId}/variables/{variableId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "defaultValue": "Updated Default",
  "label": "Updated Label",
  "name": "updated_variable_name"
}

{
  "variable": {
    "id": "gS9DWxRHUuRI9yDUjiWw",
    "name": "customer_name",
    "defaultValue": "Default value",
    "category": "custom",
    "label": "Customer Name",
    "type": "string",
    "readonly": false,
    "created": "2025-10-04T10:00:00Z",
    "updated": "2025-10-04T10:05:00Z",
    "structureJson": "{\"firstName\": \"string\", \"lastName\": \"string\"}"
  }
}