Widget

Operations tagged Widget in the public API.

About Widget

The widget is the chat bubble a website embeds for a chatbot. Its look and behaviour live in the chatbot's settings; the sites it may load on are the chatbot's allowlist of hostnames (allowed_domains). An empty allowlist lets it load on any site; otherwise the page's host must match an entry exactly, or as a subdomain of a *.example.com entry. The widget serves only an active chatbot.

Installations. A website plugin (WordPress) registers its site with POST /plugins/install: the site's host joins the allowlist and stays there while the installation is active — a host an active installation owns cannot be removed, and a whole-list replace keeps it. The plugin reports its version with POST /plugins/heartbeat; DELETE /plugins/{id} disconnects it (the row stays, removed).

IDs you will meet.

chatbotId — the chatbot id, in every /chatbots/{chatbotId}/widget… path.
Installation id — an integer, from POST /plugins/install or GET /chatbots/{chatbotId}/widget/installations; the plugin sends it back as installation_id.

IDs on this page

Chatbot id<CHATBOT_ID>: Integer.
Get it from
GET /v1/chatbots returns it as data[].id
POST /v1/chatbots returns it as id
GET /v1/chatbots/by_handle/{handle} returns it as id
Webhook chatbot.created carries it as data.object.id
In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
Allowlisted host<HOST>: A hostname exactly as the allowlist stores it, without scheme or path (e.g. shop.example.com or *.example.com).
Get it from
GET /v1/chatbots/{chatbotId}/widget/domains returns it as allowed_domains[]
GET /v1/chatbots/{chatbotId}/widget returns it as allowed_domains[]
Plugin installation id<INSTALLATION_ID>: Integer.
Get it from
POST /v1/plugins/install returns it as id
GET /v1/chatbots/{chatbotId}/widget/installations returns it as data[].id
Webhook plugin.installed carries it as data.object.id

/v1/chatbots/{chatbotId}/widget

Retrieve widget settings

Returns what the embedded widget is built from: the chatbot's status (the widget serves only active chatbots), its allowlist, welcome message, language and the widget settings bag (position, colours, launcher and the other look-and-behaviour keys). The same settings is on the chatbot object.

Required scope: widget:read
Idempotency: Read-only
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Responses

200
Success.
objectstringRequired
Alwayswidget_settings
idintegerRequired
The chatbot id.
statusstringRequired
The chatbot's lifecycle status; the widget serves only an active chatbot.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
welcome_messagestringnullableRequired
The first message the widget shows; null for the default greeting.
primary_languagestringRequired
The chatbot's content language, e.g. English.
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot. A key never set is absent.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "widget_settings",
  "id": 1,
  "status": "active",
  "allowed_domains": [
    "shop.example.com"
  ],
  "welcome_message": null,
  "primary_language": "English",
  "settings": []
}

/v1/chatbots/{chatbotId}/widget

Update widget settings

Merges the keys you send into the chatbot's widget settings and returns the widget settings. Keys you omit keep their value; to reset a key, send it with null where the key allows it. Only the documented widget keys are accepted — any other key is 422 VALIDATION_FAILED. Embedded widgets pick the change up on their next load. Emits chatbot.updated, then widget.updated.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: chatbot.updated widget.updated
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

settingsobjectRequired
The widget keys to change, merged into the stored settings: keys you omit keep their value. Only the documented keys are accepted; any other key is 422 VALIDATION_FAILED.

Responses

200
Success.
objectstringRequired
Alwayswidget_settings
idintegerRequired
The chatbot id.
statusstringRequired
The chatbot's lifecycle status; the widget serves only an active chatbot.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
welcome_messagestringnullableRequired
The first message the widget shows; null for the default greeting.
primary_languagestringRequired
The chatbot's content language, e.g. English.
settingsobjectRequired
The widget look-and-behaviour keys set on the chatbot. A key never set is absent.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PUT 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "settings": "settings"
}'

Response

Example 200 response

json

{
  "object": "widget_settings",
  "id": 1,
  "status": "inactive",
  "allowed_domains": [],
  "welcome_message": "Hi! Ask me about orders, shipping or refunds.",
  "primary_language": "English",
  "settings": {
    "widget_position": "bottom-right"
  }
}

/v1/chatbots/{chatbotId}/widget/domains

List allowed widget domains

Returns the chatbot's widget allowlist: the hostnames whose pages may load the widget. An empty list lets the widget load on any site; otherwise the page's host must equal an entry, or be a subdomain of a *. entry.

Required scope: widget:read
Idempotency: Read-only
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Responses

200
Success.
objectstringRequired
Alwayswidget_domains
idintegerRequired
The chatbot id.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/domains' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "widget_domains",
  "id": 1,
  "allowed_domains": [
    "shop.example.com"
  ]
}

/v1/chatbots/{chatbotId}/widget/domains

Replace the widget allowlist

Sets the whole allowlist to the hosts you send (an empty list lets the widget load anywhere) and returns it. Each host is normalised (scheme, port, path and case removed) and must be a valid hostname or *. wildcard; a host an active plugin installation owns is kept even when you leave it out. More hosts than the cap is 422 WIDGET_DOMAIN_LIMIT_REACHED. It emits no webhook event. To change one host without rewriting the list, use POST or DELETE on the domains instead.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

allowed_domainsarray of stringRequired
The complete new allowlist: hostnames without scheme, or *.example.com wildcards, at most 50 by default. Each entry is normalised (scheme, port, path and case removed). [] lets the widget load on any site. A host an active plugin installation owns is kept even when left out.
Max items: 50

Responses

200
Success.
objectstringRequired
Alwayswidget_domains
idintegerRequired
The chatbot id.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PUT 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/domains' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "allowed_domains": []
}'

Response

Example 200 response

json

{
  "object": "widget_domains",
  "id": 1,
  "allowed_domains": [
    "example.com",
    "*.example.com"
  ]
}

/v1/chatbots/{chatbotId}/widget/domains

Allow a widget domain

Adds one host to the allowlist and returns the list. Adding a host already on it changes nothing and succeeds, so retries are safe. A full allowlist is 422 WIDGET_DOMAIN_LIMIT_REACHED; an invalid host is 422. It emits no webhook event. Adding the first host switches the widget from loading anywhere to loading only on the listed hosts.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Body for POST /v1/chatbots/{id}/widget/domains. This used to be validated inline, which put the field error at error.details.domain while every other 422 on the surface puts it at errors + error.details.fields. A FormRequest routes it through the one renderer, so VALIDATION_FAILED means the same shape everywhere.

domainstringRequired
The hostname to allow, e.g. shop.example.com, or *.example.com to allow every subdomain of example.com (a wildcard over a public suffix such as *.co.uk is refused). A scheme, port or path is stripped.
Max length: 255

Responses

200
Success.
objectstringRequired
Alwayswidget_domains
idintegerRequired
The chatbot id.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/domains' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "domain": "domain"
}'

Response

Example 200 response

json

{
  "object": "widget_domains",
  "id": 1,
  "allowed_domains": [
    "example.com",
    "*.example.com",
    "shop.example.org"
  ]
}

/v1/chatbots/{chatbotId}/widget/installations

List plugin installations

Returns the sites where a website plugin registered the chatbot's widget, cursor-paginated: each installation's site, platform, plugin version, when it last reported in, and whether it is active or removed.

Required scope: widget:read
Idempotency: Read-only
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Query parameters

limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of WidgetInstallationResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/installations' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "widget_installation",
      "id": 1,
      "status": "active",
      "domain": "shop.example.com",
      "site_url": "https://shop.example.com",
      "platform": "wordpress",
      "plugin_version": "1.0.0",
      "last_seen_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/chatbots/1/widget/installations"
}

/v1/chatbots/{chatbotId}/widget/usage

Retrieve widget usage

Returns the chatbot's widget request counter and its lifetime number of chat turns. The counter is a snapshot taken at most once a minute, and it is not reset at midnight: on a day the widget has not served a request yet, requests_today still shows the last active day's count.

Required scope: widget:read
Idempotency: Read-only
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Path parameters

chatbotIdintegerRequired
The chatbot id.

Responses

200
Success.
objectstringRequired
Alwayswidget_usage
idintegerRequired
The chatbot id.
requests_todayintegerRequired
Widget requests counted on the last day the widget served one, refreshed at most once a minute.
queries_countintegerRequired
Chat turns the chatbot has answered, on every surface (a stored counter).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/usage' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "widget_usage",
  "id": 1,
  "requests_today": 0,
  "queries_count": 0
}

/v1/chatbots/{chatbotId}/widget/domains/{host}

Remove a widget domain

Removes one host from the allowlist and returns the list. Removing a host that is not on it changes nothing and succeeds. A host an active plugin installation owns is 422 WIDGET_DOMAIN_PLUGIN_MANAGED (error.details.installation_id names it): disconnect the installation with DELETE /plugins/{id} instead. It emits no webhook event. Removing the last host lets the widget load on any site again.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

chatbotId(path)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
host(path)Allowlisted host
A hostname exactly as the allowlist stores it, without scheme or path (e.g. shop.example.com or *.example.com).
Placeholder in the samples: <HOST>
Get it from
- GET /v1/chatbots/{chatbotId}/widget/domains returns it as allowed_domains[]
- GET /v1/chatbots/{chatbotId}/widget returns it as allowed_domains[]

Path parameters

chatbotIdintegerRequired
The chatbot id.
hoststringRequired
The host to remove, as the allowlist lists it (e.g. shop.example.com).

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayswidget_domains
idintegerRequired
The chatbot id.
allowed_domainsarray of stringRequired
Hostnames allowed to embed the widget, without scheme.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/widget/domains/<HOST>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "widget_domains",
  "id": 1,
  "allowed_domains": [
    "example.com",
    "*.example.com"
  ]
}

/v1/plugins/install

What the website plugin calls on activation: registers the site as an installation of the chatbot's widget, adds the site's host to the allowlist, and returns the installation with 201. The site must be HTTPS. A site already registered for the chatbot is the same installation — a removed one is revived — and only an installation that becomes active emits plugin.installed and mails the account owner, so a retry is safe. 402 when the plan has no website embed; 422 when the site is not HTTPS, the chatbot's installation registry or allowlist is full, or the host cannot be stored.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: plugin.installed
Rate limits

Before you call

chatbot_id(body)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

chatbot_idintegerRequired
The chatbot whose widget the site embeds. A chatbot of another account is 422 VALIDATION_FAILED.
platformstringRequired
The plugin's platform.
Possible valueswordpress
Max length: 64
site_urlstringRequired
The site URL (HTTPS, at most 255 characters). Its normalized host is added to the widget allowlist.
Format: uriMax length: 255
plugin_versionstringnullableOptional
The plugin's version, e.g. 1.4.0: letters, digits, ., _, - and +, at most 32 characters.
Max length: 32Pattern: ^[A-Za-z0-9._\-+]+$

Responses

201
WidgetInstallationResource
objectstringRequired
Alwayswidget_installation
idintegerRequired
The installation id. The plugin sends it as installation_id on each heartbeat; DELETE /plugins/{id} disconnects it.
statusstringRequired
active (the site owns its allowlist entry) or removed (disconnected; POST /plugins/install revives it).
Possible valuesactiveremoved
domainstringRequired
The site's normalised host, the entry the installation keeps on the widget allowlist.
site_urlstringRequired
The site URL the plugin registered.
platformstringRequired
The plugin platform, e.g. wordpress.
plugin_versionstringnullableRequired
The plugin version the site last reported; null when it never sent one.
last_seen_atstringnullableRequired
When the site last registered or sent a heartbeat (ISO 8601, UTC); null before the first.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/plugins/install' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "chatbot_id": 1,
  "platform": "platform",
  "site_url": "site_url",
  "plugin_version": "plugin_version"
}'

Response

Example 201 response

json

{
  "object": "widget_installation",
  "id": 1,
  "status": "active",
  "domain": "blog.example.com",
  "site_url": "https://blog.example.com",
  "platform": "wordpress",
  "plugin_version": "1.4.0",
  "last_seen_at": "2026-01-01T00:00:00+00:00"
}

/v1/plugins/heartbeat

Report a plugin heartbeat

What an installed plugin calls periodically: records that the site is alive (last_seen_at) and, when sent, its plugin_version, and returns the installation. A heartbeat never revives a removed installation or re-adds its host to the allowlist — the response shows status: removed, and only POST /plugins/install reconnects the site. It emits no webhook event.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

installation_id(body)Plugin installation id
Integer.
Placeholder in the samples: <INSTALLATION_ID>
Get it from
- POST /v1/plugins/install returns it as id
- GET /v1/chatbots/{chatbotId}/widget/installations returns it as data[].id
- Webhook plugin.installed carries it as data.object.id

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

installation_idintegerRequired
The installation id POST /plugins/install returned. An installation of another account is 404 NOT_FOUND.
Minimum: 1
plugin_versionstringnullableOptional
The plugin version now running, at most 32 characters. Omit it to keep the stored version.
Max length: 32

Responses

200
WidgetInstallationResource
objectstringRequired
Alwayswidget_installation
idintegerRequired
The installation id. The plugin sends it as installation_id on each heartbeat; DELETE /plugins/{id} disconnects it.
statusstringRequired
active (the site owns its allowlist entry) or removed (disconnected; POST /plugins/install revives it).
Possible valuesactiveremoved
domainstringRequired
The site's normalised host, the entry the installation keeps on the widget allowlist.
site_urlstringRequired
The site URL the plugin registered.
platformstringRequired
The plugin platform, e.g. wordpress.
plugin_versionstringnullableRequired
The plugin version the site last reported; null when it never sent one.
last_seen_atstringnullableRequired
When the site last registered or sent a heartbeat (ISO 8601, UTC); null before the first.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/plugins/heartbeat' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "installation_id": 1,
  "plugin_version": "plugin_version"
}'

Response

Example 200 response

json

{
  "object": "widget_installation",
  "id": 1,
  "status": "active",
  "domain": "blog.example.com",
  "site_url": "https://blog.example.com",
  "platform": "wordpress",
  "plugin_version": "1.4.1",
  "last_seen_at": "2026-01-01T00:00:00+00:00"
}

/v1/plugins/{id}

Disconnect a plugin installation

Marks the installation removed and drops its host from the allowlist, unless another active installation of the chatbot still claims that host. The installation stays listed (status: removed) so a later POST /plugins/install revives it. Only the call that actually moves it from active to removed emits plugin.uninstalled.

Required scope: widget:write
Idempotency: Accepts Idempotency-Key
Webhook events: plugin.uninstalled
Rate limits

Before you call

id(path)Plugin installation id
Integer.
Placeholder in the samples: <INSTALLATION_ID>
Get it from
- POST /v1/plugins/install returns it as id
- GET /v1/chatbots/{chatbotId}/widget/installations returns it as data[].id
- Webhook plugin.installed carries it as data.object.id

Path parameters

idintegerRequired
The plugin installation id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayswidget_installation
idintegerRequired
deletedbooleanRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/plugins/<INSTALLATION_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "widget_installation",
  "id": 1,
  "deleted": true
}

About Widget

IDs on this page

/v1/chatbots/{chatbotId}/widget

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/domains

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/domains

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/domains

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/installations

Path parameters

Query parameters

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/usage

Path parameters

Responses

See also

Request

Response

/v1/chatbots/{chatbotId}/widget/domains/{host}

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/plugins/install

Header parameters

Request body

Responses

See also

Request

Response

/v1/plugins/heartbeat

Header parameters

Request body

Responses

See also

Request

Response

/v1/plugins/{id}

Path parameters

Header parameters

Responses

See also

Request

Response