> For the complete documentation index, see [llms.txt](https://docs.epic-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.epic-ai.com/api-dokumentation/chatbot-variables.md).

# Chatbot Variables

## Lists all global variables for a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.variables.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/variables":{"get":{"operationId":"ChatbotVariableController_listGlobalVariables[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"filters","required":false,"in":"query","description":"Filters variables by categories. Separate multiple filters with commas.\n\n- `0`: CUSTOM\n- `1`: APP\n- `2`: Entity\n","schema":{"type":"string"}}],"responses":{"200":{"description":"List of all global variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGlobalVariablesResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all global variables for a chatbot","tags":["Chatbot variables"],"description":"\n\n**Required Permission:** `chatbots.variables.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListGlobalVariablesResponseDto":{"type":"object","properties":{"variables":{"description":"The list of global variables.","type":"array","items":{"$ref":"#/components/schemas/GlobalVariableDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["variables"]},"GlobalVariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the variable."},"name":{"type":"string","description":"The programmatic name of the variable."},"defaultValue":{"type":"string","description":"The default value of the variable."},"category":{"type":"string","description":"The category of the variable (e.g., custom, entity, app)."},"label":{"type":"string","description":"The readable label of the variable."},"type":{"type":"string","description":"The data type of the variable.","enum":["string","number","boolean","object"]},"readonly":{"type":"boolean","description":"Indicates whether the variable is read-only."},"created":{"type":"string","description":"Timestamp of when the variable was created."},"updated":{"type":"string","description":"Timestamp of when the variable was last updated."},"structureJson":{"type":"string","format":"json","description":"A JSON string defining the structure for object variables."}},"required":["id","name","category","label","type","readonly","created","updated"]}}}}
```

## Creates a new global variable

> \
> \
> \*\*Required Permission:\*\* \`chatbots.variables.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/variables":{"post":{"operationId":"ChatbotVariableController_createGlobalVariable[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGlobalVariableRequestDto"}}}},"responses":{"201":{"description":"Global variable created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalVariableResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new global variable","tags":["Chatbot variables"],"description":"\n\n**Required Permission:** `chatbots.variables.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateGlobalVariableRequestDto":{"type":"object","properties":{"category":{"type":"string","description":"The category of the variable.","enum":["custom"]},"defaultValue":{"type":"string","description":"An optional default value for the variable."},"label":{"type":"string","description":"The human-readable label of the variable."},"type":{"type":"string","description":"The data type of the variable (e.g., \"string\", \"number\", \"boolean\", \"object\")."},"name":{"type":"string","description":"The programmatic name of the variable."},"structureJson":{"type":"string","format":"json","description":"A JSON string defining the structure for object variables."},"subCategory":{"description":"Sets the subCategory of the variable.\n\n- `0`: GLOBAL_VARIABLE_SUB_CATEGORY_CONVERSATION\n- `1`: GLOBAL_VARIABLE_SUB_CATEGORY_CONTACT","allOf":[{"$ref":"#/components/schemas/GlobalVariableSubCategory"}]}},"required":["category","label","type","name","subCategory"]},"GlobalVariableSubCategory":{"type":"number","enum":[0,1,-1],"description":"Sets the subCategory of the variable.\n\n- `0`: GLOBAL_VARIABLE_SUB_CATEGORY_CONVERSATION\n- `1`: GLOBAL_VARIABLE_SUB_CATEGORY_CONTACT"},"GlobalVariableResponseDto":{"type":"object","properties":{"variable":{"description":"The global variable.","allOf":[{"$ref":"#/components/schemas/GlobalVariableDto"}]}}},"GlobalVariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the variable."},"name":{"type":"string","description":"The programmatic name of the variable."},"defaultValue":{"type":"string","description":"The default value of the variable."},"category":{"type":"string","description":"The category of the variable (e.g., custom, entity, app)."},"label":{"type":"string","description":"The readable label of the variable."},"type":{"type":"string","description":"The data type of the variable.","enum":["string","number","boolean","object"]},"readonly":{"type":"boolean","description":"Indicates whether the variable is read-only."},"created":{"type":"string","description":"Timestamp of when the variable was created."},"updated":{"type":"string","description":"Timestamp of when the variable was last updated."},"structureJson":{"type":"string","format":"json","description":"A JSON string defining the structure for object variables."}},"required":["id","name","category","label","type","readonly","created","updated"]}}}}
```

## Deletes a global variable

> \
> \
> \*\*Required Permission:\*\* \`chatbots.variables.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/variables/{variableId}":{"delete":{"operationId":"ChatbotVariableController_deleteGlobalVariable[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"variableId","required":true,"in":"path","description":"The ID of the variable to be deleted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Result of the deletion process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGlobalVariableResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a global variable","tags":["Chatbot variables"],"description":"\n\n**Required Permission:** `chatbots.variables.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteGlobalVariableResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Indicates whether the variable was successfully deleted."}}}}}}
```

## Updates an existing global variable

> \
> \
> \*\*Required Permission:\*\* \`chatbots.variables.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/variables/{variableId}":{"patch":{"operationId":"ChatbotVariableController_updateGlobalVariable[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"variableId","required":true,"in":"path","description":"The ID of the variable to be updated.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGlobalVariableRequestDto"}}}},"responses":{"200":{"description":"Global variable updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalVariableResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing global variable","tags":["Chatbot variables"],"description":"\n\n**Required Permission:** `chatbots.variables.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateGlobalVariableRequestDto":{"type":"object","properties":{"defaultValue":{"type":"string","description":"The new default value."},"label":{"type":"string","description":"The new label."},"name":{"type":"string","description":"The new programmatic name."}}},"GlobalVariableResponseDto":{"type":"object","properties":{"variable":{"description":"The global variable.","allOf":[{"$ref":"#/components/schemas/GlobalVariableDto"}]}}},"GlobalVariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the variable."},"name":{"type":"string","description":"The programmatic name of the variable."},"defaultValue":{"type":"string","description":"The default value of the variable."},"category":{"type":"string","description":"The category of the variable (e.g., custom, entity, app)."},"label":{"type":"string","description":"The readable label of the variable."},"type":{"type":"string","description":"The data type of the variable.","enum":["string","number","boolean","object"]},"readonly":{"type":"boolean","description":"Indicates whether the variable is read-only."},"created":{"type":"string","description":"Timestamp of when the variable was created."},"updated":{"type":"string","description":"Timestamp of when the variable was last updated."},"structureJson":{"type":"string","format":"json","description":"A JSON string defining the structure for object variables."}},"required":["id","name","category","label","type","readonly","created","updated"]}}}}
```