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-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

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-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

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-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}

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-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

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}

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"
}