# Inbox widgets

## Lists all widgets

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets":{"get":{"operationId":"InboxWidgetController_listInboxWidgets[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The Id of the chatbot.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListInboxWidgetsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all widgets","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListInboxWidgetsResponseDto":{"type":"object","properties":{"inboxWidgets":{"description":"The list of widgets.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetDto"}}},"required":["inboxWidgets"]},"InboxWidgetDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the widget."},"title":{"type":"string","description":"The title of the widget."},"fields":{"description":"The fields contained in the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}},"created":{"type":"string","description":"Timestamp when the widget was created."},"updated":{"type":"string","description":"Timestamp when the widget was last updated."}},"required":["id","title","fields","created","updated"]},"InboxWidgetFieldDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the field."},"variable":{"type":"string","description":"The variable id used to bind field data."},"type":{"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE","allOf":[{"$ref":"#/components/schemas/InboxWidgetFieldType"}]},"readonly":{"type":"boolean","description":"Whether the field is read-only."},"options":{"description":"The selectable options for DROPDOWN type fields.","type":"array","items":{"type":"string"}},"position":{"type":"number","description":"The display position of the field in which they will be ordered by in the widget."}},"required":["label","variable","type","options","position"]},"InboxWidgetFieldType":{"type":"number","enum":[0,1,2,3,4,-1],"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE"}}}}
```

## Creates a widget

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.widgets.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets":{"post":{"operationId":"InboxWidgetController_createInboxWidget[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/CreateInboxWidgetRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxWidgetResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Creates a widget","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateInboxWidgetRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the widget."},"fields":{"description":"The fields for the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}}},"required":["title","fields"]},"InboxWidgetFieldDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the field."},"variable":{"type":"string","description":"The variable id used to bind field data."},"type":{"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE","allOf":[{"$ref":"#/components/schemas/InboxWidgetFieldType"}]},"readonly":{"type":"boolean","description":"Whether the field is read-only."},"options":{"description":"The selectable options for DROPDOWN type fields.","type":"array","items":{"type":"string"}},"position":{"type":"number","description":"The display position of the field in which they will be ordered by in the widget."}},"required":["label","variable","type","options","position"]},"InboxWidgetFieldType":{"type":"number","enum":[0,1,2,3,4,-1],"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE"},"InboxWidgetResponseDto":{"type":"object","properties":{"inboxWidget":{"description":"The widget.","nullable":true,"allOf":[{"$ref":"#/components/schemas/InboxWidgetDto"}]}}},"InboxWidgetDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the widget."},"title":{"type":"string","description":"The title of the widget."},"fields":{"description":"The fields contained in the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}},"created":{"type":"string","description":"Timestamp when the widget was created."},"updated":{"type":"string","description":"Timestamp when the widget was last updated."}},"required":["id","title","fields","created","updated"]}}}}
```

## Gets a widget

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets/{widgetId}":{"get":{"operationId":"InboxWidgetController_getInboxWidget[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The Id of the chatbot.","schema":{"type":"string"}},{"name":"widgetId","required":true,"in":"path","description":"The Id of the widget.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxWidgetResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Gets a widget","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"InboxWidgetResponseDto":{"type":"object","properties":{"inboxWidget":{"description":"The widget.","nullable":true,"allOf":[{"$ref":"#/components/schemas/InboxWidgetDto"}]}}},"InboxWidgetDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the widget."},"title":{"type":"string","description":"The title of the widget."},"fields":{"description":"The fields contained in the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}},"created":{"type":"string","description":"Timestamp when the widget was created."},"updated":{"type":"string","description":"Timestamp when the widget was last updated."}},"required":["id","title","fields","created","updated"]},"InboxWidgetFieldDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the field."},"variable":{"type":"string","description":"The variable id used to bind field data."},"type":{"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE","allOf":[{"$ref":"#/components/schemas/InboxWidgetFieldType"}]},"readonly":{"type":"boolean","description":"Whether the field is read-only."},"options":{"description":"The selectable options for DROPDOWN type fields.","type":"array","items":{"type":"string"}},"position":{"type":"number","description":"The display position of the field in which they will be ordered by in the widget."}},"required":["label","variable","type","options","position"]},"InboxWidgetFieldType":{"type":"number","enum":[0,1,2,3,4,-1],"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE"}}}}
```

## Deletes a widget

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.widgets.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets/{widgetId}":{"delete":{"operationId":"InboxWidgetController_deleteInboxWidget[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The Id of the chatbot.","schema":{"type":"string"}},{"name":"widgetId","required":true,"in":"path","description":"The Id of the widget.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteInboxWidgetResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a widget","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteInboxWidgetResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Whether the widget was successfully deleted."}}}}}}
```

## Updates a widget

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets/{widgetId}":{"patch":{"operationId":"InboxWidgetController_updateInboxWidget[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The Id of the chatbot.","schema":{"type":"string"}},{"name":"widgetId","required":true,"in":"path","description":"The Id of the widget.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInboxWidgetRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxWidgetResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Updates a widget","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateInboxWidgetRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"The updated title of the widget."},"fields":{"description":"The updated fields for the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}}},"required":["fields"]},"InboxWidgetFieldDto":{"type":"object","properties":{"label":{"type":"string","description":"The display label of the field."},"variable":{"type":"string","description":"The variable id used to bind field data."},"type":{"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE","allOf":[{"$ref":"#/components/schemas/InboxWidgetFieldType"}]},"readonly":{"type":"boolean","description":"Whether the field is read-only."},"options":{"description":"The selectable options for DROPDOWN type fields.","type":"array","items":{"type":"string"}},"position":{"type":"number","description":"The display position of the field in which they will be ordered by in the widget."}},"required":["label","variable","type","options","position"]},"InboxWidgetFieldType":{"type":"number","enum":[0,1,2,3,4,-1],"description":"The type of the field.\n\n- `0`: TEXT\n- `1`: NUMBER\n- `2`: CHECKBOX\n- `3`: DROPDOWN\n- `4`: DATE"},"InboxWidgetResponseDto":{"type":"object","properties":{"inboxWidget":{"description":"The widget.","nullable":true,"allOf":[{"$ref":"#/components/schemas/InboxWidgetDto"}]}}},"InboxWidgetDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the widget."},"title":{"type":"string","description":"The title of the widget."},"fields":{"description":"The fields contained in the widget.","type":"array","items":{"$ref":"#/components/schemas/InboxWidgetFieldDto"}},"created":{"type":"string","description":"Timestamp when the widget was created."},"updated":{"type":"string","description":"Timestamp when the widget was last updated."}},"required":["id","title","fields","created","updated"]}}}}
```

## Gets a widget's values

> \
> \
> \*\*Required Permission:\*\* \`chatbots.inbox.widgets.content.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Inbox widgets","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{}],"paths":{"/v1/inbox/{chatbotId}/widgets/{widgetId}/values":{"get":{"operationId":"InboxWidgetController_getInboxWidgetValuesBatch[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The Id of the chatbot.","schema":{"type":"string"}},{"name":"widgetId","required":true,"in":"path","description":"The Id of the widget.","schema":{"type":"string"}},{"name":"conversationId","required":true,"in":"query","description":"The Id of the conversation.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"query","description":"The Id of the contact.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxWidgetValuesResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Gets a widget's values","tags":["Inbox widgets"],"description":"\n\n**Required Permission:** `chatbots.inbox.widgets.content.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"InboxWidgetValuesResponseDto":{"type":"object","properties":{"fieldValues":{"description":"The widget values.","type":"array","items":{"type":"object"}}},"required":["fieldValues"]}}}}
```


---

# 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-widgets.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.