> 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/conversation-variables.md).

# Conversation Variables

## Lists all custom, entity and app variables of a conversation

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables":{"get":{"operationId":"ConversationVariableController_listVariables[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The ID of the conversation.","schema":{"type":"string"}}],"responses":{"200":{"description":"The list of conversation variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListVariablesResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all custom, entity and app variables of a conversation","tags":["Conversation variables"],"description":"\n\n**Required Permission:** `chatbots.conversations.variables.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListVariablesResponseDto":{"type":"object","properties":{"variables":{"description":"The list of conversation variables.","type":"array","items":{"$ref":"#/components/schemas/VariableDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["variables"]},"VariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the variable (corresponds to the global variable ID)."},"name":{"type":"string","description":"The programmatic name of the variable."},"type":{"type":"string","description":"The data type of the variable."},"value":{"type":"string","description":"The value assigned in this conversation."},"updated":{"type":"string","description":"The timestamp of the last update."}},"required":["id","name","type","value","updated"]}}}}
```

## Deletes all custom, entity and app variables of a conversation

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables":{"delete":{"operationId":"ConversationVariableController_deleteVariables[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The ID of the conversation.","schema":{"type":"string"}}],"responses":{"200":{"description":"The deletion result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteVariablesResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes all custom, entity and app variables of a conversation","tags":["Conversation variables"],"description":"\n\n**Required Permission:** `chatbots.conversations.variables.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteVariablesResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Indicates whether the deletion operation was successful."},"error":{"type":"string","description":"Optional error message."}}}}}}
```

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

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables/{variableId}":{"get":{"operationId":"ConversationVariableController_getVariable[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The ID of the conversation.","schema":{"type":"string"}},{"name":"variableId","required":true,"in":"path","description":"The Id of the variable.","schema":{"type":"string"}}],"responses":{"200":{"description":"The requested variable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariableResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific custom, entity or app variable of a conversation","tags":["Conversation variables"],"description":"\n\n**Required Permission:** `chatbots.conversations.variables.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"VariableResponseDto":{"type":"object","properties":{"variable":{"description":"The variable.","allOf":[{"$ref":"#/components/schemas/VariableDto"}]},"error":{"type":"string","description":"Optional error message."}}},"VariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the variable (corresponds to the global variable ID)."},"name":{"type":"string","description":"The programmatic name of the variable."},"type":{"type":"string","description":"The data type of the variable."},"value":{"type":"string","description":"The value assigned in this conversation."},"updated":{"type":"string","description":"The timestamp of the last update."}},"required":["id","name","type","value","updated"]}}}}
```

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

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation variables","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/conversations/{conversationId}/variables/{variableId}":{"put":{"operationId":"ConversationVariableController_assignValueToVariable[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 whose value is to be set.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"path","description":"The ID of the conversation.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignValueToConversationVariableRequestDto"}}}},"responses":{"200":{"description":"The updated variable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariableResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Sets or updates the value of a custom, entity or app variable in a conversation","tags":["Conversation variables"],"description":"\n\n**Required Permission:** `chatbots.conversations.variables.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"AssignValueToConversationVariableRequestDto":{"type":"object","properties":{"value":{"type":"string","description":"The new value to be assigned to the variable."}},"required":["value"]},"VariableResponseDto":{"type":"object","properties":{"variable":{"description":"The variable.","allOf":[{"$ref":"#/components/schemas/VariableDto"}]},"error":{"type":"string","description":"Optional error message."}}},"VariableDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the variable (corresponds to the global variable ID)."},"name":{"type":"string","description":"The programmatic name of the variable."},"type":{"type":"string","description":"The data type of the variable."},"value":{"type":"string","description":"The value assigned in this conversation."},"updated":{"type":"string","description":"The timestamp of the last update."}},"required":["id","name","type","value","updated"]}}}}
```