Inbox widgets

Lists all widgets

get

Required Permission: chatbots.inbox.widgets.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

Responses

200Success

application/json

403

Insufficient permissions.

get

/v1/inbox/{chatbotId}/widgets

HTTPcURLJavaScriptPython

GET /v1/inbox/{chatbotId}/widgets HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "inboxWidgets": [
    {
      "id": "U0LXi1GyLR2Nj11Nt43J",
      "title": "Customer Info",
      "fields": [
        {
          "label": "Customer Name",
          "variable": "dcq55wcucbiwa212v",
          "type": 0,
          "readonly": false,
          "options": [
            "Option A",
            "Option B"
          ],
          "position": 0
        }
      ],
      "created": "2025-10-07T14:00:00Z",
      "updated": "2025-10-07T14:05:00Z"
    }
  ]
}

Creates a widget

post

Required Permission: chatbots.inbox.widgets.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

Body

application/json

titlestringRequired

The title of the widget.

Example: Customer Info

Responses

201Success

application/json

403

Insufficient permissions.

post

/v1/inbox/{chatbotId}/widgets

HTTPcURLJavaScriptPython

POST /v1/inbox/{chatbotId}/widgets HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "title": "Customer Info",
  "fields": [
    {
      "label": "Customer Name",
      "variable": "dcq55wcucbiwa212v",
      "type": 0,
      "readonly": false,
      "options": [
        "Option A",
        "Option B"
      ],
      "position": 0
    }
  ]
}

{
  "inboxWidget": {
    "id": "U0LXi1GyLR2Nj11Nt43J",
    "title": "Customer Info",
    "fields": [
      {
        "label": "Customer Name",
        "variable": "dcq55wcucbiwa212v",
        "type": 0,
        "readonly": false,
        "options": [
          "Option A",
          "Option B"
        ],
        "position": 0
      }
    ],
    "created": "2025-10-07T14:00:00Z",
    "updated": "2025-10-07T14:05:00Z"
  }
}

Gets a widget

get

Required Permission: chatbots.inbox.widgets.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

widgetIdstringRequired

The Id of the widget.

Responses

200Success

application/json

403

Insufficient permissions.

get

/v1/inbox/{chatbotId}/widgets/{widgetId}

HTTPcURLJavaScriptPython

GET /v1/inbox/{chatbotId}/widgets/{widgetId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "inboxWidget": {
    "id": "U0LXi1GyLR2Nj11Nt43J",
    "title": "Customer Info",
    "fields": [
      {
        "label": "Customer Name",
        "variable": "dcq55wcucbiwa212v",
        "type": 0,
        "readonly": false,
        "options": [
          "Option A",
          "Option B"
        ],
        "position": 0
      }
    ],
    "created": "2025-10-07T14:00:00Z",
    "updated": "2025-10-07T14:05:00Z"
  }
}

Deletes a widget

delete

Required Permission: chatbots.inbox.widgets.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

widgetIdstringRequired

The Id of the widget.

Responses

200Success

application/json

deletedbooleanOptional

Whether the widget was successfully deleted.

Example: true

403

Insufficient permissions.

delete

/v1/inbox/{chatbotId}/widgets/{widgetId}

HTTPcURLJavaScriptPython

DELETE /v1/inbox/{chatbotId}/widgets/{widgetId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true
}

Updates a widget

patch

Required Permission: chatbots.inbox.widgets.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

widgetIdstringRequired

The Id of the widget.

Body

application/json

titlestringOptional

The updated title of the widget.

Example: Updated Customer Info

Responses

200Success

application/json

403

Insufficient permissions.

patch

/v1/inbox/{chatbotId}/widgets/{widgetId}

HTTPcURLJavaScriptPython

PATCH /v1/inbox/{chatbotId}/widgets/{widgetId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "title": "Updated Customer Info",
  "fields": [
    {
      "label": "Customer Name",
      "variable": "dcq55wcucbiwa212v",
      "type": 0,
      "readonly": false,
      "options": [
        "Option A",
        "Option B"
      ],
      "position": 0
    }
  ]
}

{
  "inboxWidget": {
    "id": "U0LXi1GyLR2Nj11Nt43J",
    "title": "Customer Info",
    "fields": [
      {
        "label": "Customer Name",
        "variable": "dcq55wcucbiwa212v",
        "type": 0,
        "readonly": false,
        "options": [
          "Option A",
          "Option B"
        ],
        "position": 0
      }
    ],
    "created": "2025-10-07T14:00:00Z",
    "updated": "2025-10-07T14:05:00Z"
  }
}

Gets a widget's values

get

Required Permission: chatbots.inbox.widgets.content.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The Id of the chatbot.

widgetIdstringRequired

The Id of the widget.

Query parameters

conversationIdstringRequired

The Id of the conversation.

contactIdstringRequired

The Id of the contact.

Responses

200Success

application/json

fieldValuesobject[]Required

The widget values.

403

Insufficient permissions.

get

/v1/inbox/{chatbotId}/widgets/{widgetId}/values

HTTPcURLJavaScriptPython

GET /v1/inbox/{chatbotId}/widgets/{widgetId}/values?conversationId=text&contactId=text HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "fieldValues": [
    {}
  ]
}