Widget

A persona on your website.

GET/v1/personas/{id}/widget

Get a persona's website widget

getPersonaWidgetwidgets:readread: 600/min per keySince 2026-10-01

How it shows, where it may appear, where requests go, whether it is on and live, what it still needs (steps) and the code to paste. Before the first PUT it answers with exists: false. Only the organisation's own personas have a widget (not a portal's persona).

Path parameters

idstringrequired
Persona id (pa_…); the id without its prefix is accepted too.

Returns

200 The widget. data is Widget.

Fields of data

personaIdstringrequired
Persona id (pa_…).
pattern `^pa_.*`
existsbooleanrequired
The widget has been set up (the first PUT makes it).
onbooleanrequired
Switched on.
livebooleanrequired
Switched on and showing: its public door is open and it has websites to show on.
lookWidgetLookrequired
How the widget shows on your pages.
labelstringrequired
The button's words as visitors see them.
allowedOriginsstring[]required
The websites that may show it (every other website gets nothing).
requestEmailstring | nullrequired
Where visitors' messages and requests go.
templatestring | nullrequired
What its conversations are set up as: support-agent or receptionist.
stepsWidgetStep[]required
What it needs before it goes live, in order.
documentsintegerrequired
Documents it answers from (the persona's knowledge).
answersintegerrequired
Approved answers of its own.
publicIdstring | nullrequired
The widget's public id (<organisation>/w-…): all the snippet names.
snippetstring | nullrequired
The code to paste into your pages, as the layout needs it.
configUrlstring | nullrequired
Where a website reads the widget's public settings (for your own button).
portalIdstring | nullrequired
Its hidden website-assistant portal (never listed by GET /portals).
subjectIdstring | nullrequired
Its subject: edit its answers through /subjects/{id}/content.
outOfDatebooleanrequired
The persona's first line or languages changed since the widget was saved; any PUT brings them over.

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/personas/pa_123/widget" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getPersonaWidget("pa_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_persona_widget("pa_123")

Example answer

Response

{
  "data": {
    "personaId": "pa_cmfq2b7x10000abcd1234",
    "exists": true,
    "on": true,
    "live": true,
    "look": {
      "layout": "floating",
      "initialState": "minimized",
      "position": "bottom-right",
      "label": "…",
      "accent": "#0f766e",
      "start": "voice"
    },
    "label": "…"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

PUT/v1/personas/{id}/widget

Set up a persona's website widget, switch it on or off

updatePersonaWidgetwidgets:writewrite: 120/min per keySince 2026-10-01

The first call makes the widget (a hidden website-assistant portal for the persona, never listed by GET /portals), off. Change how it shows (floating or inline, minimized or expanded, one of four corners, the button), the websites that may show it and where visitors' requests go. on: true needs the portals:publish scope, the plan's website assistants and website embedding (403 upgrade_required), and everything steps lists: otherwise 422 go_live_refused names what is missing in details.problems, with the widget unchanged in details.widget. While it is on, changing requestEmail or allowedOrigins needs portals:publish too (403). Switching on also lets outside visitors talk to the organisation's avatars (its public-website switch). on: false closes its door at once.

Path parameters

idstringrequired
Persona id (pa_…); the id without its prefix is accepted too.

Body

purpose"support" | "reception"
What its conversations are set up as when it is first made: support (a support agent) or reception (a receptionist).
layout"floating" | "inline"
floating (a button in a corner) or inline (inside your page).
initialState"minimized" | "expanded"
minimized or expanded ("minimised" is read too).
position"bottom-right" | "top-right" | "bottom-left" | "top-left"
A floating widget's corner ("right" and "left" read as the bottom ones).
labelstring | null
The button's words (null or "" for "Talk to <name>").
at most 40 characters
accentstring
The button's colour, #rrggbb.
start"voice" | "chat"
The panel opens ready to talk (voice) or to type (chat).
allowedOriginsstring[]
Replaces the websites that may show it, such as https://www.example.com (20 at most).
at most 20 items
requestEmailstring | null
Where visitors' messages and requests go; null clears it.
onboolean
Switch it on (needs the portals:publish scope and what steps lists) or off (its door closes at once).

Returns

200 The widget as saved, and what happened. data is WidgetSaved.

Fields of data

personaIdstringrequired
Persona id (pa_…).
pattern `^pa_.*`
existsbooleanrequired
The widget has been set up (the first PUT makes it).
onbooleanrequired
Switched on.
livebooleanrequired
Switched on and showing: its public door is open and it has websites to show on.
lookWidgetLookrequired
How the widget shows on your pages.
labelstringrequired
The button's words as visitors see them.
allowedOriginsstring[]required
The websites that may show it (every other website gets nothing).
requestEmailstring | nullrequired
Where visitors' messages and requests go.
templatestring | nullrequired
What its conversations are set up as: support-agent or receptionist.
stepsWidgetStep[]required
What it needs before it goes live, in order.
documentsintegerrequired
Documents it answers from (the persona's knowledge).
answersintegerrequired
Approved answers of its own.
publicIdstring | nullrequired
The widget's public id (<organisation>/w-…): all the snippet names.
snippetstring | nullrequired
The code to paste into your pages, as the layout needs it.
configUrlstring | nullrequired
Where a website reads the widget's public settings (for your own button).
portalIdstring | nullrequired
Its hidden website-assistant portal (never listed by GET /portals).
subjectIdstring | nullrequired
Its subject: edit its answers through /subjects/{id}/content.
outOfDatebooleanrequired
The persona's first line or languages changed since the widget was saved; any PUT brings them over.
saidstringrequired
What happened, in one sentence.

Errors

invalid_request unauthorized forbidden upgrade_required not_found go_live_refused rate_limited server_error

Events

portal.updated portal.created workspace.published

Request

curl -X PUT "https://app.zentiqai.com/v1/personas/pa_123/widget" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.updatePersonaWidget("pa_123", {});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.update_persona_widget("pa_123", {})

Example answer

Response

{
  "data": {
    "personaId": "pa_cmfq2b7x10000abcd1234",
    "exists": true,
    "on": true,
    "live": true,
    "look": {
      "layout": "floating",
      "initialState": "minimized",
      "position": "bottom-right",
      "label": "…",
      "accent": "#0f766e",
      "start": "voice"
    },
    "label": "…"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}