# 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"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chatcaptain.com/api/api-dokumentation/chatbot-variables.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.