> For the complete documentation index, see [llms.txt](https://docs.chatcaptain.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chatcaptain.com/api/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"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.chatcaptain.com/api/api-dokumentation/chatbot-users.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.