# Inbox agents

## Lists all agent's online status from a chatbot

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox agents","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/inbox/{chatbotId}/agents/online":{"get":{"operationId":"InboxAgentsController_getOnlineAgents[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of agent's online status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAgentOnlineStateResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all agent's online status from a chatbot","tags":["Inbox agents"],"description":"\n\n**Required Permission:** `chatbots.inbox.agents.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListAgentOnlineStateResponseDto":{"type":"object","properties":{"agents":{"description":"The list of agent online states.","type":"array","items":{"$ref":"#/components/schemas/AgentOnlineStateDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["agents"]},"AgentOnlineStateDto":{"type":"object","properties":{"agentId":{"type":"string","description":"The unique identifier of the agent."},"online":{"type":"boolean","description":"Whether the agent is currently online."},"lastSeen":{"type":"string","description":"Timestamp of the last activity."}},"required":["agentId","online","lastSeen"]}}}}
```

## Sets the agent's own online status

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.agents.online.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox agents","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/inbox/{chatbotId}/agents/me/online":{"post":{"operationId":"InboxAgentsController_setOwnAgentState[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/SetAgentOnlineStateRequestDto"}}}},"responses":{"200":{"description":"The updated online status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAgentOnlineStateResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Sets the agent's own online status","tags":["Inbox agents"],"description":"\n\n**Required Permission:** `chatbots.inbox.agents.online.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"SetAgentOnlineStateRequestDto":{"type":"object","properties":{"online":{"type":"boolean","description":"Sets the online status of the agent."},"clientTimestamp":{"type":"string","description":"The client timestamp when the request is made. This is used to resolve conflicts when multiple requests are made in a short period of time."}},"required":["online","clientTimestamp"]},"SetAgentOnlineStateResponseDto":{"type":"object","properties":{"agent":{"description":"The updated agent online state.","nullable":true,"allOf":[{"$ref":"#/components/schemas/AgentOnlineStateDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["agent"]},"AgentOnlineStateDto":{"type":"object","properties":{"agentId":{"type":"string","description":"The unique identifier of the agent."},"online":{"type":"boolean","description":"Whether the agent is currently online."},"lastSeen":{"type":"string","description":"Timestamp of the last activity."}},"required":["agentId","online","lastSeen"]}}}}
```

## Retrieves the agent's own notification settings

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.agents.notifications.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox agents","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/inbox/{chatbotId}/agents/me/notifications":{"get":{"operationId":"InboxAgentsController_getOwnAgentNotificationSettings[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"responses":{"200":{"description":"The current settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentNotificationSettingsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves the agent's own notification settings","tags":["Inbox agents"],"description":"\n\n**Required Permission:** `chatbots.inbox.agents.notifications.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"AgentNotificationSettingsResponseDto":{"type":"object","properties":{"settings":{"description":"The agent notification settings.","nullable":true,"allOf":[{"$ref":"#/components/schemas/AgentNotificationSettingsDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["settings"]},"AgentNotificationSettingsDto":{"type":"object","properties":{"agentId":{"type":"string","description":"The unique identifier of the agent."},"botHandoverToUnassigned":{"description":"Notification settings for bot handover to unassigned.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"botAssignsYou":{"description":"Notification settings for when bot assigns you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"conversationsAssignedToYou":{"description":"Notification settings for conversations assigned to you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"pushToken":{"type":"string","description":"The push token for browser notifications."}},"required":["agentId","botHandoverToUnassigned","botAssignsYou","conversationsAssignedToYou"]},"AgentNotificationSettings_SettingDto":{"type":"object","properties":{"email":{"type":"boolean","description":"Enable/disable email notifications."},"browser":{"type":"boolean","description":"Enable/disable in-browser (push) notifications."}},"required":["email","browser"]}}}}
```

## Updates the agent's own notification settings

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.agents.notifications.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox agents","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/inbox/{chatbotId}/agents/me/notifications":{"post":{"operationId":"InboxAgentsController_setOwnAgentNotificationSettings[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/UpdateAgentNotificationSettingsRequestDto"}}}},"responses":{"200":{"description":"The updated settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentNotificationSettingsResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Updates the agent's own notification settings","tags":["Inbox agents"],"description":"\n\n**Required Permission:** `chatbots.inbox.agents.notifications.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateAgentNotificationSettingsRequestDto":{"type":"object","properties":{"botHandoverToUnassigned":{"description":"Notification settings for bot handover to unassigned.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"botAssignsYou":{"description":"Notification settings for when bot assigns you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"conversationsAssignedToYou":{"description":"Notification settings for conversations assigned to you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"pushToken":{"type":"string","description":"The push token for browser notifications."}},"required":["botHandoverToUnassigned","botAssignsYou","conversationsAssignedToYou"]},"AgentNotificationSettings_SettingDto":{"type":"object","properties":{"email":{"type":"boolean","description":"Enable/disable email notifications."},"browser":{"type":"boolean","description":"Enable/disable in-browser (push) notifications."}},"required":["email","browser"]},"AgentNotificationSettingsResponseDto":{"type":"object","properties":{"settings":{"description":"The agent notification settings.","nullable":true,"allOf":[{"$ref":"#/components/schemas/AgentNotificationSettingsDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["settings"]},"AgentNotificationSettingsDto":{"type":"object","properties":{"agentId":{"type":"string","description":"The unique identifier of the agent."},"botHandoverToUnassigned":{"description":"Notification settings for bot handover to unassigned.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"botAssignsYou":{"description":"Notification settings for when bot assigns you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"conversationsAssignedToYou":{"description":"Notification settings for conversations assigned to you.","allOf":[{"$ref":"#/components/schemas/AgentNotificationSettings_SettingDto"}]},"pushToken":{"type":"string","description":"The push token for browser notifications."}},"required":["agentId","botHandoverToUnassigned","botAssignsYou","conversationsAssignedToYou"]}}}}
```


---

# 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/inbox-agents.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.