> 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-users.md).

# Chatbot Users

## Lists all users of a chatbot

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot users","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/workspaces/{workspaceId}/chatbots/{chatbotId}/users":{"get":{"operationId":"ChatbotUserController_listChatbotUsers[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"The ID of the workspace.","schema":{}}],"responses":{"200":{"description":"List of users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListChatbotUsersResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all users of a chatbot","tags":["Chatbot users"],"description":"\n\n**Required Permission:** `chatbots.users.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListChatbotUsersResponseDto":{"type":"object","properties":{"users":{"description":"The list of users associated with the chatbot.","type":"array","items":{"$ref":"#/components/schemas/ChatbotUserDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["users"]},"ChatbotUserDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user."},"name":{"type":"string","description":"The display name of the user."},"email":{"type":"string","description":"The email address of the user."},"added":{"type":"string","description":"Timestamp of when the user was added to the chatbot."},"roles":{"description":"The list of roles assigned to the user.","type":"array","items":{"type":"string"}}},"required":["id","name","email","added","roles"]}}}}
```

## Adds a user to a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.users.add\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot users","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/workspaces/{workspaceId}/chatbots/{chatbotId}/users":{"post":{"operationId":"ChatbotUserController_addUser[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"The ID of the workspace.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddChatbotUserRequestDto"}}}},"responses":{"201":{"description":"User successfully added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddChatbotUserResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Adds a user to a chatbot","tags":["Chatbot users"],"description":"\n\n**Required Permission:** `chatbots.users.add`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"AddChatbotUserRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"The ID of the user to be added."}},"required":["userId"]},"AddChatbotUserResponseDto":{"type":"object","properties":{"added":{"type":"boolean","description":"Indicates whether the user was successfully added."},"error":{"type":"string","description":"Optional error message."}}}}}}
```

## Removes a user from a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.users.remove\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot users","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/workspaces/{workspaceId}/chatbots/{chatbotId}/users/{userId}":{"delete":{"operationId":"ChatbotUserController_removeUser[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","description":"The ID of the user to be removed.","schema":{"type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"The ID of the workspace.","schema":{}}],"responses":{"200":{"description":"User successfully removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveChatbotUserResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Removes a user from a chatbot","tags":["Chatbot users"],"description":"\n\n**Required Permission:** `chatbots.users.remove`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"RemoveChatbotUserResponseDto":{"type":"object","properties":{"removed":{"type":"boolean","description":"Indicates whether the user was successfully removed."},"error":{"type":"string","description":"Optional error message."}}}}}}
```

## Assigns a role to a user for the chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.users.roles.grant\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot users","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/workspaces/{workspaceId}/chatbots/{chatbotId}/users/{userId}/roles":{"post":{"operationId":"ChatbotUserController_grantRole[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","description":"The Id of the user.","schema":{"type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"The ID of the workspace.","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantChatbotRoleRequestDto"}}}},"responses":{"201":{"description":"Role successfully assigned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantChatbotRoleResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Assigns a role to a user for the chatbot","tags":["Chatbot users"],"description":"\n\n**Required Permission:** `chatbots.users.roles.grant`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"GrantChatbotRoleRequestDto":{"type":"object","properties":{"role":{"type":"string","description":"The role to be assigned.","enum":["ChatbotAdmin","ChatbotOwner","ChatbotEditor","ChatbotMember","InboxAdmin","InboxUser","ExternalInboxUser","StatisticsViewer"]},"params":{"type":"object","description":"Additional parameters for the role assignment.","additionalProperties":{"type":"string"}}},"required":["role","params"]},"GrantChatbotRoleResponseDto":{"type":"object","properties":{"permissions":{"description":"The resulting list of permissions after the role assignment.","type":"array","items":{"$ref":"#/components/schemas/PermissionDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["permissions"]},"PermissionDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the permission."},"resource":{"type":"string","description":"The resource ID the permission applies to, if scoped."}},"required":["name"]}}}}
```

## Revokes a role from a user for the chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.users.roles.revoke\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot users","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/workspaces/{workspaceId}/chatbots/{chatbotId}/users/{userId}/roles/{role}":{"delete":{"operationId":"ChatbotUserController_revokeRole[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","description":"The Id of the user.","schema":{"type":"string"}},{"name":"role","required":true,"in":"path","description":"The role to be revoked.","schema":{"type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"The ID of the workspace.","schema":{}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeChatbotRoleRequestDto"}}}},"responses":{"200":{"description":"Role successfully revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeChatbotRoleResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Revokes a role from a user for the chatbot","tags":["Chatbot users"],"description":"\n\n**Required Permission:** `chatbots.users.roles.revoke`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"RevokeChatbotRoleRequestDto":{"type":"object","properties":{"params":{"type":"object","description":"Additional parameters that must match those of the assignment.","additionalProperties":{"type":"string"}}},"required":["params"]},"RevokeChatbotRoleResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the role was successfully revoked."},"error":{"type":"string","description":"Optional error message."}},"required":["success"]}}}}
```