Conversation variables

Lists all custom, entity and app variables of a conversation

get

Required Permission: chatbots.conversations.variables.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The ID of the conversation.

Responses

200

The list of conversation variables.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables

HTTPcURLJavaScriptPython

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

{
  "variables": [
    {
      "id": "oxFRSIOBMF3gaiD3XRGK",
      "name": "customer_name",
      "type": "string",
      "value": "Max Mustermann",
      "updated": "2025-10-06T10:00:00Z"
    }
  ],
  "error": "text"
}

Deletes all custom, entity and app variables of a conversation

delete

Required Permission: chatbots.conversations.variables.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The ID of the conversation.

Responses

200

The deletion result.

application/json

deletedbooleanOptional

Indicates whether the deletion operation was successful.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables

HTTPcURLJavaScriptPython

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

{
  "deleted": true,
  "error": "text"
}

Retrieves a specific custom, entity or app variable of a conversation

get

Required Permission: chatbots.conversations.variables.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

conversationIdstringRequired

The ID of the conversation.

variableIdstringRequired

The Id of the variable.

Responses

200

The requested variable.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

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

HTTPcURLJavaScriptPython

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

{
  "variable": {
    "id": "oxFRSIOBMF3gaiD3XRGK",
    "name": "customer_name",
    "type": "string",
    "value": "Max Mustermann",
    "updated": "2025-10-06T10:00:00Z"
  },
  "error": "text"
}

Sets or updates the value of a custom, entity or app variable in a conversation

put

Required Permission: chatbots.conversations.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 whose value is to be set.

conversationIdstringRequired

The ID of the conversation.

Body

application/json

valuestringRequired

The new value to be assigned to the variable.

Example: Custom Value

Responses

200

The updated variable.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

put

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

HTTPcURLJavaScriptPython

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

{
  "value": "Custom Value"
}

{
  "variable": {
    "id": "oxFRSIOBMF3gaiD3XRGK",
    "name": "customer_name",
    "type": "string",
    "value": "Max Mustermann",
    "updated": "2025-10-06T10:00:00Z"
  },
  "error": "text"
}