Contact variables

Lists all custom variables of a contact

get

Required Permission: chatbots.contacts.variables.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

contactIdstringRequired

The Id of the contact.

Responses

200

The list of contact variables.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/contacts/variables/{contactId}

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts/variables/{contactId} 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 variables of a contact

delete

Required Permission: chatbots.contacts.variables.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

contactIdstringRequired

The Id of the contact.

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}/contacts/variables/{contactId}

HTTPcURLJavaScriptPython

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

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

Gets a specific custom variable of a contact

get

Required Permission: chatbots.contacts.variables.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

variableIdstringRequired

The Id of the variable.

contactIdstringRequired

The Id of the contact.

Responses

200

The requested variable.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

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

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts/variables/{contactId}/{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 variable of a contact

put

Required Permission: chatbots.contacts.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.

Body

application/json

valuestringRequired

The new value to be assigned to the variable.

Example: Custom Value

contactIdstringOptional

The id of the contact to assign the variable to.

Example: fdnklxaCACfw92b01v

Responses

200

The updated variable.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

put

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

HTTPcURLJavaScriptPython

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

{
  "value": "Custom Value",
  "contactId": "fdnklxaCACfw92b01v"
}

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