# 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"]}}}}
```


---

# 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-users.md?ask=<question>
```

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.