@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/webChat.md

@@ -0,0 +1,2048 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.webChat`: Web Chat
+
+46 operations (15 read, 22 write, 9 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.webChat.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [webChat.d.ts](webChat.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addWebchatHandoffPoolTeams`](#op-addwebchathandoffpoolteams) | `POST /api/v1/webchat/handoff-pool/teams` | write | `inbox:write` | Add Webchat Handoff Pool Teams |
+| [`addWebchatHandoffPoolUsers`](#op-addwebchathandoffpoolusers) | `POST /api/v1/webchat/handoff-pool/users` | write | `inbox:write` | Add Webchat Handoff Pool Users |
+| [`createAssessment`](#op-createassessment) | `POST /api/v1/webchat/assessments` | write | `inbox:write` | Create Assessment |
+| [`createChatBot`](#op-createchatbot) | `POST /api/v1/webchat/chat-bots` | write | `inbox:write` | Create Chat Bot |
+| [`createWebchatAgent`](#op-createwebchatagent) | `POST /api/v1/webchat/agents` | write | `inbox:write` | Create Webchat Agent |
+| [`createWebchatBlog`](#op-createwebchatblog) | `POST /api/v1/webchat/blogs` | write | `inbox:write` | Create Webchat Blog |
+| [`createWebchatButton`](#op-createwebchatbutton) | `POST /api/v1/webchat/buttons` | write | `inbox:write` | Create Webchat Button |
+| [`createWebchatQuestion`](#op-createwebchatquestion) | `POST /api/v1/webchat/questions` | write | `inbox:write` | Create Webchat Question |
+| [`createWebchatSettings`](#op-createwebchatsettings) | `POST /api/v1/webchat/settings` | write | `inbox:write` | Create Webchat Settings |
+| [`deleteAssessment`](#op-deleteassessment) | `DELETE /api/v1/webchat/assessments/{assessment_id}` | destructive | `inbox:delete` | Delete Assessment |
+| [`deleteChatBot`](#op-deletechatbot) | `DELETE /api/v1/webchat/chat-bots/{bot_id}` | destructive | `inbox:delete` | Delete Chat Bot |
+| [`deleteWebchatAgent`](#op-deletewebchatagent) | `DELETE /api/v1/webchat/agents/{agent_id}` | destructive | `inbox:delete` | Delete Webchat Agent |
+| [`deleteWebchatBlog`](#op-deletewebchatblog) | `DELETE /api/v1/webchat/blogs/{blog_id}` | destructive | `inbox:delete` | Delete Webchat Blog |
+| [`deleteWebchatButton`](#op-deletewebchatbutton) | `DELETE /api/v1/webchat/buttons/{button_id}` | destructive | `inbox:delete` | Delete Webchat Button |
+| [`deleteWebchatQuestion`](#op-deletewebchatquestion) | `DELETE /api/v1/webchat/questions/{question_id}` | destructive | `inbox:delete` | Delete Webchat Question |
+| [`deleteWebchatSettings`](#op-deletewebchatsettings) | `DELETE /api/v1/webchat/settings` | destructive | `inbox:delete` | Delete Webchat Settings |
+| [`fetchWebchatBlogMetadata`](#op-fetchwebchatblogmetadata) | `POST /api/v1/webchat/blogs/fetch-metadata` | write | `inbox:write` | Fetch Webchat Blog Metadata |
+| [`getAssessment`](#op-getassessment) | `GET /api/v1/webchat/assessments/{assessment_id}` | read | `inbox:read` | Get Assessment |
+| [`getWebchatHandoffPool`](#op-getwebchathandoffpool) | `GET /api/v1/webchat/handoff-pool` | read | `inbox:read` | Get Webchat Handoff Pool |
+| [`getWebchatHandoffPoolStatus`](#op-getwebchathandoffpoolstatus) | `GET /api/v1/webchat/handoff-pool-status` | read | `inbox:read` | Get Webchat Handoff Pool Status |
+| [`getWebchatHumanAvailability`](#op-getwebchathumanavailability) | `GET /api/v1/webchat/human-availability` | read | `inbox:read` | Get Webchat Human Availability |
+| [`getWebchatSettings`](#op-getwebchatsettings) | `GET /api/v1/webchat/settings` | read | `inbox:read` | Get Webchat Settings |
+| [`getWebchatVisitorFunnel`](#op-getwebchatvisitorfunnel) | `GET /api/v1/webchat/visitors/funnel` | read | `inbox:read` | Get Webchat Visitor Funnel |
+| [`listAssessments`](#op-listassessments) | `GET /api/v1/webchat/assessments` | read | `inbox:read` | List Assessments |
+| [`listChatBots`](#op-listchatbots) | `GET /api/v1/webchat/chat-bots` | read | `inbox:read` | List Chat Bots |
+| [`listWebchatAgents`](#op-listwebchatagents) | `GET /api/v1/webchat/agents` | read | `inbox:read` | List Webchat Agents |
+| [`listWebchatBlogs`](#op-listwebchatblogs) | `GET /api/v1/webchat/blogs` | read | `inbox:read` | List Webchat Blogs |
+| [`listWebchatButtons`](#op-listwebchatbuttons) | `GET /api/v1/webchat/buttons` | read | `inbox:read` | List Webchat Buttons |
+| [`listWebchatQuestions`](#op-listwebchatquestions) | `GET /api/v1/webchat/questions` | read | `inbox:read` | List Webchat Questions |
+| [`listWebchatTeamEventTypes`](#op-listwebchatteameventtypes) | `GET /api/v1/webchat/teams/{team_id}/event-types` | read | `inbox:read` | List Webchat Team Event Types |
+| [`listWebchatTeams`](#op-listwebchatteams) | `GET /api/v1/webchat/teams` | read | `inbox:read` | List Webchat Teams |
+| [`listWebchatVisitors`](#op-listwebchatvisitors) | `GET /api/v1/webchat/visitors` | read | `inbox:read` | List Webchat Visitors |
+| [`promoteChatBotToDefault`](#op-promotechatbottodefault) | `POST /api/v1/webchat/chat-bots/{bot_id}/promote-default` | write | `inbox:write` | Promote Chat Bot To Default |
+| [`putWebchatHumanAvailability`](#op-putwebchathumanavailability) | `PUT /api/v1/webchat/human-availability` | write | `inbox:write` | Put Webchat Human Availability |
+| [`removeWebchatHandoffPoolTeam`](#op-removewebchathandoffpoolteam) | `DELETE /api/v1/webchat/handoff-pool/teams/{team_id}` | destructive | `inbox:delete` | Remove Webchat Handoff Pool Team |
+| [`removeWebchatHandoffPoolUser`](#op-removewebchathandoffpooluser) | `DELETE /api/v1/webchat/handoff-pool/users/{user_id}` | destructive | `inbox:delete` | Remove Webchat Handoff Pool User |
+| [`updateAssessment`](#op-updateassessment) | `PATCH /api/v1/webchat/assessments/{assessment_id}` | write | `inbox:write` | Update Assessment |
+| [`updateChatBot`](#op-updatechatbot) | `PATCH /api/v1/webchat/chat-bots/{bot_id}` | write | `inbox:write` | Update Chat Bot |
+| [`updateWebchatAgent`](#op-updatewebchatagent) | `PATCH /api/v1/webchat/agents/{agent_id}` | write | `inbox:write` | Update Webchat Agent |
+| [`updateWebchatBlog`](#op-updatewebchatblog) | `PATCH /api/v1/webchat/blogs/{blog_id}` | write | `inbox:write` | Update Webchat Blog |
+| [`updateWebchatButton`](#op-updatewebchatbutton) | `PATCH /api/v1/webchat/buttons/{button_id}` | write | `inbox:write` | Update Webchat Button |
+| [`updateWebchatHandoffPoolTeamScope`](#op-updatewebchathandoffpoolteamscope) | `PATCH /api/v1/webchat/handoff-pool/teams/{team_id}/scope` | write | `inbox:write` | Update Webchat Handoff Pool Team Scope |
+| [`updateWebchatHandoffPoolUserScope`](#op-updatewebchathandoffpooluserscope) | `PATCH /api/v1/webchat/handoff-pool/users/{user_id}/scope` | write | `inbox:write` | Update Webchat Handoff Pool User Scope |
+| [`updateWebchatQuestion`](#op-updatewebchatquestion) | `PATCH /api/v1/webchat/questions/{question_id}` | write | `inbox:write` | Update Webchat Question |
+| [`updateWebchatSettings`](#op-updatewebchatsettings) | `PATCH /api/v1/webchat/settings` | write | `inbox:write` | Update Webchat Settings |
+| [`uploadWebchatImage`](#op-uploadwebchatimage) | `POST /api/v1/webchat/images` | write | `inbox:write` | Upload Webchat Image |
+
+---
+
+<a id="op-addwebchathandoffpoolteams"></a>
+
+### `g8.api.webChat.addWebchatHandoffPoolTeams(input)`
+
+**Add Webchat Handoff Pool Teams**
+
+- HTTP: `POST /api/v1/webchat/handoff-pool/teams`
+- operationId: `add_webchat_handoff_pool_teams_webchat_handoff_pool_teams_post` (also callable as `g8.api.call("add_webchat_handoff_pool_teams_webchat_handoff_pool_teams_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Add whole teams to the handoff pool. Returns the whole pool afterwards.
+
+A team's members are expanded when a chat is routed, so someone joining
+the team later is reachable without another call.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `HandoffPoolTeamsRequest` | yes | Request body; fields below. |
+
+Body fields (`HandoffPoolTeamsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.team_ids` | `Array<string (uuid)>` | yes | min items 1, max items 200 |
+| `body.chat_bot_ids` | `Array<string (uuid)>` | no | max items 200 |
+| `body.pool` | `"external" \| "internal"` | no | default `"external"` |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.addWebchatHandoffPoolTeams({ body: { team_ids: ["00000000-0000-0000-0000-000000000000"] } });
+```
+
+---
+
+<a id="op-addwebchathandoffpoolusers"></a>
+
+### `g8.api.webChat.addWebchatHandoffPoolUsers(input)`
+
+**Add Webchat Handoff Pool Users**
+
+- HTTP: `POST /api/v1/webchat/handoff-pool/users`
+- operationId: `add_webchat_handoff_pool_users_webchat_handoff_pool_users_post` (also callable as `g8.api.call("add_webchat_handoff_pool_users_webchat_handoff_pool_users_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Add people to the handoff pool. Returns the whole pool afterwards.
+
+Adding someone already in it is a no-op, not an error. From the first
+member on, handed-off chats go ONLY to the pool.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `HandoffPoolUsersRequest` | yes | Request body; fields below. |
+
+Body fields (`HandoffPoolUsersRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.user_ids` | `Array<string>` | yes | min items 1, max items 200 |
+| `body.chat_bot_ids` | `Array<string (uuid)>` | no | max items 200 |
+| `body.pool` | `"external" \| "internal"` | no | default `"external"` |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.addWebchatHandoffPoolUsers({ body: { user_ids: ["id"] } });
+```
+
+---
+
+<a id="op-createassessment"></a>
+
+### `g8.api.webChat.createAssessment(input)`
+
+**Create Assessment**
+
+- HTTP: `POST /api/v1/webchat/assessments`
+- operationId: `create_assessment_webchat_assessments_post` (also callable as `g8.api.call("create_assessment_webchat_assessments_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Create an assessment.
+
+`definition` is the flow itself and is validated HERE, against the app's
+own model - so a graph whose `start_step_id` names a step it does not
+define is a 422 rather than a dead end a visitor walks into.
+
+Note `chat_bot_id` is a QUERY parameter on this one and a BODY field on
+every other webchat create. That is the app's own inconsistency, mirrored
+rather than tidied: moving it into the body would send the handler a
+parameter it does not take.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body` | `AssessmentCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key. Replaying it returns the FIRST result. |
+
+Body fields (`AssessmentCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.definition` | `AssessmentDefinition` | yes | The flow: `{start_step_id, steps[], results[]}`. |
+| `body.name` | `string` | yes | min length 1, max length 200 |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createAssessment({
+  query: { chat_bot_id: "id" },
+  body: { definition: { start_step_id: "id" }, name: "Example" },
+});
+```
+
+---
+
+<a id="op-createchatbot"></a>
+
+### `g8.api.webChat.createChatBot(input)`
+
+**Create Chat Bot**
+
+- HTTP: `POST /api/v1/webchat/chat-bots`
+- operationId: `create_chat_bot_webchat_chat_bots_post` (also callable as `g8.api.call("create_chat_bot_webchat_chat_bots_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Create a chat bot.
+
+`agent_id` seeds the bot with an answering agent. Omitted, the bot is
+created with none and answers nothing until an agent is mapped with
+`POST /webchat/agents`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ChatBotCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`ChatBotCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 120 |
+| `body.agent_id` | `string \| null` | no | Optional voice/text agent id used to seed the new bot's external chat agent. When omitted, no agent row is created. max length 255 |
+| `body.agent_name` | `string \| null` | no | Display name of the selected agent. Stored on the agent row so the widget shows the AGENT's name, not the bot's. Falls back to the bot name when omitted. max length 255 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createChatBot({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-createwebchatagent"></a>
+
+### `g8.api.webChat.createWebchatAgent(input)`
+
+**Create Webchat Agent**
+
+- HTTP: `POST /api/v1/webchat/agents`
+- operationId: `create_webchat_agent_webchat_agents_post` (also callable as `g8.api.call("create_webchat_agent_webchat_agents_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Map an agent onto the URLs it answers on.
+
+`url_filter` is matched against the page the widget is embedded on.
+`default: true` is the fallback when nothing matches - without one, a
+visitor on an unlisted page gets no agent.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AgentCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`AgentCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent_name` | `string` | yes | min length 1, max length 255 |
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.active` | `boolean` | no | default `true` |
+| `body.agent_id` | `string \| null` | no | Agent id from agent settings. max length 255 |
+| `body.default` | `boolean` | no | Used when no URL filter matches. default `false` |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.url_filter` | `Array<string>` | no | URL paths where this agent is active. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createWebchatAgent({ body: { agent_name: "Example", chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-createwebchatblog"></a>
+
+### `g8.api.webChat.createWebchatBlog(input)`
+
+**Create Webchat Blog**
+
+- HTTP: `POST /api/v1/webchat/blogs`
+- operationId: `create_webchat_blog_webchat_blogs_post` (also callable as `g8.api.call("create_webchat_blog_webchat_blogs_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Add an article card. `display_order` is ascending; ties break newest-first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BlogCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`BlogCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.url` | `string` | yes | min length 1, max length 1000 |
+| `body.active` | `boolean` | no | default `true` |
+| `body.description` | `string \| null` | no |  |
+| `body.display_order` | `integer` | no | Lower sorts first; ties break newest-first. default `0`, min 0, max 9999 |
+| `body.image_url` | `string \| null` | no | max length 1000 |
+| `body.paths` | `Array<string>` | no |  |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createWebchatBlog({
+  body: { chat_bot_id: "id", title: "Example", url: "https://example.com" },
+});
+```
+
+---
+
+<a id="op-createwebchatbutton"></a>
+
+### `g8.api.webChat.createWebchatButton(input)`
+
+**Create Webchat Button**
+
+- HTTP: `POST /api/v1/webchat/buttons`
+- operationId: `create_webchat_button_webchat_buttons_post` (also callable as `g8.api.call("create_webchat_button_webchat_buttons_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Add a quick-action button.
+
+`value` is read according to `action`: a URL for `link`, the question text
+for `question`, a calendar slug for `calendar`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ButtonCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`ButtonCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action` | `"link" \| "question" \| "calendar"` | yes |  |
+| `body.category` | `string` | yes | min length 1, max length 100 |
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.label` | `string` | yes | min length 1, max length 255 |
+| `body.value` | `string` | yes | URL for `link`, question text for `question`, slug for `calendar`. min length 1, max length 1000 |
+| `body.active` | `boolean` | no | default `true` |
+| `body.icon` | `string \| null` | no | max length 100 |
+| `body.paths` | `Array<string>` | no | URL paths where the button appears. |
+| `body.surface` | `"external" \| "internal" \| null` | no | NULL shows it on BOTH widgets. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createWebchatButton({
+  body: {
+    action: "link",
+    category: "example",
+    chat_bot_id: "id",
+    label: "example",
+    value: "example",
+  },
+});
+```
+
+---
+
+<a id="op-createwebchatquestion"></a>
+
+### `g8.api.webChat.createWebchatQuestion(input)`
+
+**Create Webchat Question**
+
+- HTTP: `POST /api/v1/webchat/questions`
+- operationId: `create_webchat_question_webchat_questions_post` (also callable as `g8.api.call("create_webchat_question_webchat_questions_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Offer a preset question in the widget.
+
+`placements` NULL or empty means EVERY placement, not none.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `QuestionCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`QuestionCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.question` | `string` | yes | min length 1, max length 1000 |
+| `body.active` | `boolean` | no | default `true` |
+| `body.category` | `string \| null` | no | max length 100 |
+| `body.paths` | `Array<string>` | no |  |
+| `body.placements` | `Array<"launcher" \| "home" \| "conversation"> \| null` | no | NULL or [] means every placement. |
+| `body.sort_order` | `integer \| null` | no | Order within a placement. NULL sorts last. |
+| `body.surface` | `"external" \| "internal" \| null` | no | NULL shows it on BOTH widgets. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createWebchatQuestion({ body: { chat_bot_id: "id", question: "example" } });
+```
+
+---
+
+<a id="op-createwebchatsettings"></a>
+
+### `g8.api.webChat.createWebchatSettings(input)`
+
+**Create Webchat Settings**
+
+- HTTP: `POST /api/v1/webchat/settings`
+- operationId: `create_webchat_settings_webchat_settings_post` (also callable as `g8.api.call("create_webchat_settings_webchat_settings_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Create the theme for one bot and surface. ONE ROW PER PAIR.
+
+409 when one already exists - use `PATCH /webchat/settings` for that.
+
+Colours must be hex and dimensions must be CSS lengths; two model-level
+guards additionally refuse an illegible text/background pair and an absurd
+design-token magnitude. All of them run at THIS boundary, so a violation
+is a 422 naming the field.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SettingsCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. |
+
+Body fields (`SettingsCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.assistantMessageBgColor` | `string` | no | default `"#fcfcfc"`, max length 20 |
+| `body.assistantMessageTextColor` | `string` | no | default `"#000000"`, max length 20 |
+| `body.assistantName` | `string` | no | default `"Assistant"`, max length 100 |
+| `body.borderRadius` | `string` | no | default `"0.5rem"`, max length 20 |
+| `body.botAvatarCustomUrl` | `string \| null` | no | max length 1000 |
+| `body.botAvatarMode` | `"agent" \| "preset" \| "custom"` | no | default `"agent"` |
+| `body.botAvatarPresetUrl` | `string \| null` | no | max length 1000 |
+| `body.botIconType` | `string` | no | default `"bot"`, max length 50 |
+| `body.chatWidth` | `string` | no | default `"350px"`, max length 20 |
+| `body.copyOverrides` | `Record<string, string> \| null` | no |  |
+| `body.darkMode` | `boolean` | no | default `false` |
+| `body.designTokens` | `DesignTokens \| null` | no | Design-token tree. The app's own model, so the magnitude guard runs here rather than inside the proxy. |
+| `body.fontFamily` | `string` | no | default `"Inter"`, max length 100 |
+| `body.fontSize` | `string` | no | default `"14px"`, max length 20 |
+| `body.headerImageUrlExternal` | `string \| null` | no | max length 1000 |
+| `body.headerImageUrlInternal` | `string \| null` | no | max length 1000 |
+| `body.headerTextColor` | `string` | no | default `"#000000"`, max length 20 |
+| `body.primaryColor` | `string` | no | default `"#7E2DF3"`, max length 20 |
+| `body.robotIconColor` | `string` | no | default `"#ffffff"`, max length 20 |
+| `body.robotIconType` | `string` | no | default `"message"`, max length 50 |
+| `body.secondaryColor` | `string` | no | default `"#f8fafc"`, max length 20 |
+| `body.showHeader` | `boolean` | no | default `true` |
+| `body.showQuickActions` | `boolean` | no | default `true` |
+| `body.showSuggestedQuestions` | `boolean` | no | default `true` |
+| `body.suggestedQuestionsBgColor` | `string` | no | default `"#f0f9ff"`, max length 20 |
+| `body.suggestedQuestionsSectionBgColor` | `string` | no | default `"#f8fafc"`, max length 20 |
+| `body.surface` | `"external" \| "internal" \| null` | no | Which widget this theme applies to. Omitted means `external`. `internal` is graph8's own support widget and is refused for any other org. |
+| `body.themeSource` | `"default" \| "brand_kit" \| "custom"` | no | default `"default"` |
+| `body.userMessageBgColor` | `string` | no | default `"#d7d5d5"`, max length 20 |
+| `body.userMessageTextColor` | `string` | no | default `"#000000"`, max length 20 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.createWebchatSettings({ body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-deleteassessment"></a>
+
+### `g8.api.webChat.deleteAssessment(input)`
+
+**Delete Assessment**
+
+- HTTP: `DELETE /api/v1/webchat/assessments/{assessment_id}`
+- operationId: `delete_assessment_webchat_assessments__assessment_id__delete` (also callable as `g8.api.call("delete_assessment_webchat_assessments__assessment_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Delete an assessment permanently.
+
+Sessions already taken against it are historical records and are not
+rewritten. To retire one reversibly, PATCH it with `active: false`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.assessment_id` | `string` | yes | Assessment id. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteAssessment({ path: { assessment_id: "id" } });
+```
+
+---
+
+<a id="op-deletechatbot"></a>
+
+### `g8.api.webChat.deleteChatBot(input)`
+
+**Delete Chat Bot**
+
+- HTTP: `DELETE /api/v1/webchat/chat-bots/{bot_id}`
+- operationId: `delete_chat_bot_webchat_chat_bots__bot_id__delete` (also callable as `g8.api.call("delete_chat_bot_webchat_chat_bots__bot_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Delete a chat bot, and with it the content that belongs to it.
+
+Deleting the bot a live embed points at takes that widget down. Check
+which bot is default with `GET /webchat/chat-bots` first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.bot_id` | `string` | yes | Chat bot id (UUID). |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteChatBot({ path: { bot_id: "id" } });
+```
+
+---
+
+<a id="op-deletewebchatagent"></a>
+
+### `g8.api.webChat.deleteWebchatAgent(input)`
+
+**Delete Webchat Agent**
+
+- HTTP: `DELETE /api/v1/webchat/agents/{agent_id}`
+- operationId: `delete_webchat_agent_webchat_agents__agent_id__delete` (also callable as `g8.api.call("delete_webchat_agent_webchat_agents__agent_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Remove an agent mapping. The agent itself is untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.agent_id` | `string` | yes | Agent row id. |
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteWebchatAgent({ path: { agent_id: "id" }, query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-deletewebchatblog"></a>
+
+### `g8.api.webChat.deleteWebchatBlog(input)`
+
+**Delete Webchat Blog**
+
+- HTTP: `DELETE /api/v1/webchat/blogs/{blog_id}`
+- operationId: `delete_webchat_blog_webchat_blogs__blog_id__delete` (also callable as `g8.api.call("delete_webchat_blog_webchat_blogs__blog_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Remove an article card.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.blog_id` | `string` | yes | Article card id. |
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteWebchatBlog({ path: { blog_id: "id" }, query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-deletewebchatbutton"></a>
+
+### `g8.api.webChat.deleteWebchatButton(input)`
+
+**Delete Webchat Button**
+
+- HTTP: `DELETE /api/v1/webchat/buttons/{button_id}`
+- operationId: `delete_webchat_button_webchat_buttons__button_id__delete` (also callable as `g8.api.call("delete_webchat_button_webchat_buttons__button_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Remove a button from the widget.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.button_id` | `string` | yes | Button id. |
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteWebchatButton({ path: { button_id: "id" }, query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-deletewebchatquestion"></a>
+
+### `g8.api.webChat.deleteWebchatQuestion(input)`
+
+**Delete Webchat Question**
+
+- HTTP: `DELETE /api/v1/webchat/questions/{question_id}`
+- operationId: `delete_webchat_question_webchat_questions__question_id__delete` (also callable as `g8.api.call("delete_webchat_question_webchat_questions__question_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Remove a preset question.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.question_id` | `string` | yes | Question id. |
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteWebchatQuestion({ path: { question_id: "id" }, query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-deletewebchatsettings"></a>
+
+### `g8.api.webChat.deleteWebchatSettings(input)`
+
+**Delete Webchat Settings**
+
+- HTTP: `DELETE /api/v1/webchat/settings`
+- operationId: `delete_webchat_settings_webchat_settings_delete` (also callable as `g8.api.call("delete_webchat_settings_webchat_settings_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Delete the theme for one bot and surface.
+
+The widget falls back to the defaults, which is a VISIBLE change to every
+visitor rather than a tidy-up.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.surface` | `"external" \| "internal" \| null` | no | Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.deleteWebchatSettings({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-fetchwebchatblogmetadata"></a>
+
+### `g8.api.webChat.fetchWebchatBlogMetadata(input)`
+
+**Fetch Webchat Blog Metadata**
+
+- HTTP: `POST /api/v1/webchat/blogs/fetch-metadata`
+- operationId: `fetch_webchat_blog_metadata_webchat_blogs_fetch_metadata_post` (also callable as `g8.api.call("fetch_webchat_blog_metadata_webchat_blogs_fetch_metadata_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Read a page's Open Graph metadata, to pre-fill an article card.
+
+Fetches the URL and returns its `og:title`, `og:description` and
+`og:image`. PERSISTS NOTHING and spends nothing - create the card with
+`POST /webchat/blogs` afterwards.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BlogMetadataRequest` | yes | Request body; fields below. |
+
+Body fields (`BlogMetadataRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.url` | `string` | yes | Page to read og:title / og:description / og:image from. min length 1, max length 1000 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.fetchWebchatBlogMetadata({ body: { url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getassessment"></a>
+
+### `g8.api.webChat.getAssessment(input)`
+
+**Get Assessment**
+
+- HTTP: `GET /api/v1/webchat/assessments/{assessment_id}`
+- operationId: `get_assessment_webchat_assessments__assessment_id__get` (also callable as `g8.api.call("get_assessment_webchat_assessments__assessment_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+One assessment, with its full question graph.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.assessment_id` | `string` | yes | Assessment id. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getAssessment({ path: { assessment_id: "id" } });
+```
+
+---
+
+<a id="op-getwebchathandoffpool"></a>
+
+### `g8.api.webChat.getWebchatHandoffPool(input?)`
+
+**Get Webchat Handoff Pool**
+
+- HTTP: `GET /api/v1/webchat/handoff-pool`
+- operationId: `get_webchat_handoff_pool_webchat_handoff_pool_get` (also callable as `g8.api.call("get_webchat_handoff_pool_webchat_handoff_pool_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+The people and teams a handed-off chat can be routed to.
+
+Returns `users` and `teams`, each with the bots it is scoped to (an empty
+`chat_bot_ids` means every bot). An EMPTY pool is not "nobody": it means
+the app falls back to its default round-robin.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getWebchatHandoffPool();
+```
+
+---
+
+<a id="op-getwebchathandoffpoolstatus"></a>
+
+### `g8.api.webChat.getWebchatHandoffPoolStatus(input?)`
+
+**Get Webchat Handoff Pool Status**
+
+- HTTP: `GET /api/v1/webchat/handoff-pool-status`
+- operationId: `get_webchat_handoff_pool_status_webchat_handoff_pool_status_get` (also callable as `g8.api.call("get_webchat_handoff_pool_status_webchat_handoff_pool_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Whether anyone is actually in the handoff pool.
+
+The other half of the office-hours question: a schedule can say "open"
+while the pool is empty, and this is what tells them apart.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string \| null` | no | Chat bot the widget serves; the pool is scoped per bot. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getWebchatHandoffPoolStatus();
+```
+
+---
+
+<a id="op-getwebchathumanavailability"></a>
+
+### `g8.api.webChat.getWebchatHumanAvailability(input?)`
+
+**Get Webchat Human Availability**
+
+- HTTP: `GET /api/v1/webchat/human-availability`
+- operationId: `get_webchat_human_availability_webchat_human_availability_get` (also callable as `g8.api.call("get_webchat_human_availability_webchat_human_availability_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+When a human is available to take a handed-off conversation.
+
+Unlike the content routes, `chat_bot_id` is OPTIONAL here: omitting it
+reads the org-wide default schedule rather than erroring.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string \| null` | no | Chat bot id. OMIT for the org-wide default schedule. |
+| `query.surface` | `"external" \| "internal" \| null` | no | Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getWebchatHumanAvailability();
+```
+
+---
+
+<a id="op-getwebchatsettings"></a>
+
+### `g8.api.webChat.getWebchatSettings(input)`
+
+**Get Webchat Settings**
+
+- HTTP: `GET /api/v1/webchat/settings`
+- operationId: `get_webchat_settings_webchat_settings_get` (also callable as `g8.api.call("get_webchat_settings_webchat_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+The widget's appearance and behaviour, for one bot and surface.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+| `query.surface` | `"external" \| "internal" \| null` | no | Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getWebchatSettings({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-getwebchatvisitorfunnel"></a>
+
+### `g8.api.webChat.getWebchatVisitorFunnel(input?)`
+
+**Get Webchat Visitor Funnel**
+
+- HTTP: `GET /api/v1/webchat/visitors/funnel`
+- operationId: `get_webchat_visitor_funnel_webchat_visitors_funnel_get` (also callable as `g8.api.call("get_webchat_visitor_funnel_webchat_visitors_funnel_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Engagement funnel for the widget: per-event counts, top pages, denominators.
+
+`abandonment_window_minutes` IS NOT YET APPLIED by the app: it is validated
+and echoed back, but no number in the response depends on it. Do not build
+on it expecting the figures to move. `answer_feedback` and
+`conversation_abandoned` are declared stages the app does not yet produce,
+so they are absent rather than zero.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.bot_id` | `string \| null` | no |  |
+| `query.page_url` | `string \| null` | no |  |
+| `query.date_from` | `string \| null` | no | ISO date, inclusive. |
+| `query.date_to` | `string \| null` | no | ISO date, inclusive. |
+| `query.abandonment_window_minutes` | `integer` | no | Validated and echoed back; not yet applied to any figure. default `30` |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.getWebchatVisitorFunnel();
+```
+
+---
+
+<a id="op-listassessments"></a>
+
+### `g8.api.webChat.listAssessments(input?)`
+
+**List Assessments**
+
+- HTTP: `GET /api/v1/webchat/assessments`
+- operationId: `list_assessments_webchat_assessments_get` (also callable as `g8.api.call("list_assessments_webchat_assessments_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Assessments in this organisation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string \| null` | no | Filter to one bot. OPTIONAL here, unlike the other webchat content routes - omitted returns every assessment in the org. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listAssessments();
+```
+
+---
+
+<a id="op-listchatbots"></a>
+
+### `g8.api.webChat.listChatBots(input?)`
+
+**List Chat Bots**
+
+- HTTP: `GET /api/v1/webchat/chat-bots`
+- operationId: `list_chat_bots_webchat_chat_bots_get` (also callable as `g8.api.call("list_chat_bots_webchat_chat_bots_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Every chat bot in this organisation.
+
+START HERE. Each bot's id is the `chat_bot_id` that nearly every other
+call on this surface requires.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listChatBots();
+```
+
+---
+
+<a id="op-listwebchatagents"></a>
+
+### `g8.api.webChat.listWebchatAgents(input)`
+
+**List Webchat Agents**
+
+- HTTP: `GET /api/v1/webchat/agents`
+- operationId: `list_webchat_agents_webchat_agents_get` (also callable as `g8.api.call("list_webchat_agents_webchat_agents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Agent-to-URL mappings for one bot, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatAgents({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-listwebchatblogs"></a>
+
+### `g8.api.webChat.listWebchatBlogs(input)`
+
+**List Webchat Blogs**
+
+- HTTP: `GET /api/v1/webchat/blogs`
+- operationId: `list_webchat_blogs_webchat_blogs_get` (also callable as `g8.api.call("list_webchat_blogs_webchat_blogs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Article cards in the widget's rail, for one bot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatBlogs({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-listwebchatbuttons"></a>
+
+### `g8.api.webChat.listWebchatButtons(input)`
+
+**List Webchat Buttons**
+
+- HTTP: `GET /api/v1/webchat/buttons`
+- operationId: `list_webchat_buttons_webchat_buttons_get` (also callable as `g8.api.call("list_webchat_buttons_webchat_buttons_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Quick-action buttons for one bot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatButtons({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-listwebchatquestions"></a>
+
+### `g8.api.webChat.listWebchatQuestions(input)`
+
+**List Webchat Questions**
+
+- HTTP: `GET /api/v1/webchat/questions`
+- operationId: `list_webchat_questions_webchat_questions_get` (also callable as `g8.api.call("list_webchat_questions_webchat_questions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Preset questions for one bot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatQuestions({ query: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-listwebchatteameventtypes"></a>
+
+### `g8.api.webChat.listWebchatTeamEventTypes(input)`
+
+**List Webchat Team Event Types**
+
+- HTTP: `GET /api/v1/webchat/teams/{team_id}/event-types`
+- operationId: `list_webchat_team_event_types_webchat_teams__team_id__event_types_get` (also callable as `g8.api.call("list_webchat_team_event_types_webchat_teams__team_id__event_types_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Bookable event types for one team.
+
+These are the slugs a `calendar` button's `value` refers to.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.team_id` | `string` | yes | Scheduling team id. |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatTeamEventTypes({ path: { team_id: "id" } });
+```
+
+---
+
+<a id="op-listwebchatteams"></a>
+
+### `g8.api.webChat.listWebchatTeams(input?)`
+
+**List Webchat Teams**
+
+- HTTP: `GET /api/v1/webchat/teams`
+- operationId: `list_webchat_teams_webchat_teams_get` (also callable as `g8.api.call("list_webchat_teams_webchat_teams_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Scheduling teams the widget can book into.
+
+NOTE: the app's own gate docstring lists `GET /teams` among the public
+widget-runtime routes, but the route itself carries the `webchat:read`
+gate and a `get_current_user` dependency, and has done since it was
+written. The CODE is authoritative and is what this mirrors; the comment is
+stale. Flagged in the PR body rather than changed here.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatTeams();
+```
+
+---
+
+<a id="op-listwebchatvisitors"></a>
+
+### `g8.api.webChat.listWebchatVisitors(input?)`
+
+**List Webchat Visitors**
+
+- HTTP: `GET /api/v1/webchat/visitors`
+- operationId: `list_webchat_visitors_webchat_visitors_get` (also callable as `g8.api.call("list_webchat_visitors_webchat_visitors_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+People who used the widget, identified where possible.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | default `1` |
+| `query.page_size` | `integer` | no | default `50` |
+| `query.identified_only` | `boolean` | no | Only visitors the widget managed to identify. default `false` |
+| `query.search` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatListPayload_`: the envelope `{ data: WebchatListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebchatListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.listWebchatVisitors();
+```
+
+---
+
+<a id="op-promotechatbottodefault"></a>
+
+### `g8.api.webChat.promoteChatBotToDefault(input)`
+
+**Promote Chat Bot To Default**
+
+- HTTP: `POST /api/v1/webchat/chat-bots/{bot_id}/promote-default`
+- operationId: `promote_chat_bot_to_default_webchat_chat_bots__bot_id__promote_default_post` (also callable as `g8.api.call("promote_chat_bot_to_default_webchat_chat_bots__bot_id__promote_default_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Make this the org's DEFAULT bot.
+
+The default is what a legacy embed snippet with no bot id resolves to, so
+promoting one CHANGES WHAT LIVE VISITORS SEE on every such page - not just
+what the admin shows.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.bot_id` | `string` | yes | Chat bot id (UUID). |
+| `query.expected_revision` | `integer \| null` | no | Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.promoteChatBotToDefault({ path: { bot_id: "id" } });
+```
+
+---
+
+<a id="op-putwebchathumanavailability"></a>
+
+### `g8.api.webChat.putWebchatHumanAvailability(input)`
+
+**Put Webchat Human Availability**
+
+- HTTP: `PUT /api/v1/webchat/human-availability`
+- operationId: `put_webchat_human_availability_webchat_human_availability_put` (also callable as `g8.api.call("put_webchat_human_availability_webchat_human_availability_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Set the office hours that decide whether a visitor is offered a person.
+
+`enabled: true` with no reachable interval is worse than off: the widget
+offers a handover nobody answers. The app refuses the unreachable shapes
+and this forwards its answer rather than inventing a second opinion.
+
+Overlapping and zero-length windows are refused at THIS boundary, because
+the request model is the app's own.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `HumanAvailabilityRequest` | yes | Request body; fields below. |
+
+Body fields (`HumanAvailabilityRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string \| null` | no | Bot this schedule applies to. NULL is the org default. |
+| `body.enabled` | `boolean` | no | default `false` |
+| `body.intervals` | `Array<AvailabilityInterval>` | no | Weekly windows: `{day: 0-6, start: 'HH:MM', end: 'HH:MM'}`. |
+| `body.overrides` | `Array<AvailabilityOverride>` | no | Date overrides: `{date: 'YYYY-MM-DD', intervals: [...]}`. |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.timezone` | `string` | no | IANA zone the intervals are expressed in. default `"UTC"`, min length 1, max length 64 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.putWebchatHumanAvailability({ body: {} });
+```
+
+---
+
+<a id="op-removewebchathandoffpoolteam"></a>
+
+### `g8.api.webChat.removeWebchatHandoffPoolTeam(input)`
+
+**Remove Webchat Handoff Pool Team**
+
+- HTTP: `DELETE /api/v1/webchat/handoff-pool/teams/{team_id}`
+- operationId: `remove_webchat_handoff_pool_team_webchat_handoff_pool_teams__team_id__delete` (also callable as `g8.api.call("remove_webchat_handoff_pool_team_webchat_handoff_pool_teams__team_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Take a team out of the handoff pool. 404 if it is not in it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.team_id` | `string (uuid)` | yes | Team id (UUID). |
+| `query.pool` | `"external" \| "internal" \| null` | no | Only the row in this pool. Omitted removes the person or team from every pool. `internal` is graph8's own support widget. |
+| `query.chat_bot_id` | `string (uuid) \| null` | no | Only the row scoped to this chat bot. Omitted removes it across every bot. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.removeWebchatHandoffPoolTeam({ path: { team_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-removewebchathandoffpooluser"></a>
+
+### `g8.api.webChat.removeWebchatHandoffPoolUser(input)`
+
+**Remove Webchat Handoff Pool User**
+
+- HTTP: `DELETE /api/v1/webchat/handoff-pool/users/{user_id}`
+- operationId: `remove_webchat_handoff_pool_user_webchat_handoff_pool_users__user_id__delete` (also callable as `g8.api.call("remove_webchat_handoff_pool_user_webchat_handoff_pool_users__user_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Take a person out of the handoff pool. 404 if they are not in it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.user_id` | `string` | yes | Member user id. |
+| `query.pool` | `"external" \| "internal" \| null` | no | Only the row in this pool. Omitted removes the person or team from every pool. `internal` is graph8's own support widget. |
+| `query.chat_bot_id` | `string (uuid) \| null` | no | Only the row scoped to this chat bot. Omitted removes it across every bot. |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.webChat.removeWebchatHandoffPoolUser({ path: { user_id: "id" } });
+```
+
+---
+
+<a id="op-updateassessment"></a>
+
+### `g8.api.webChat.updateAssessment(input)`
+
+**Update Assessment**
+
+- HTTP: `PATCH /api/v1/webchat/assessments/{assessment_id}`
+- operationId: `update_assessment_webchat_assessments__assessment_id__patch` (also callable as `g8.api.call("update_assessment_webchat_assessments__assessment_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of an assessment.
+
+`active: false` takes it out of the widget without deleting it, which is
+the reversible way to retire one.
+
+The concurrency field is `revision` here, not `expected_revision`. That is
+the app's spelling on this model alone and is mirrored deliberately - a
+tidier name would be a field the handler does not read, silently switching
+the check off.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.assessment_id` | `string` | yes | Assessment id. |
+| `body` | `AssessmentUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AssessmentUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.active` | `boolean \| null` | no |  |
+| `body.definition` | `AssessmentDefinition \| null` | no |  |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.name` | `string \| null` | no | min length 1, max length 200 |
+| `body.revision` | `integer \| null` | no | Revision you last read. See the note above on the name. |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateAssessment({ path: { assessment_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatechatbot"></a>
+
+### `g8.api.webChat.updateChatBot(input)`
+
+**Update Chat Bot**
+
+- HTTP: `PATCH /api/v1/webchat/chat-bots/{bot_id}`
+- operationId: `update_chat_bot_webchat_chat_bots__bot_id__patch` (also callable as `g8.api.call("update_chat_bot_webchat_chat_bots__bot_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Rename a chat bot. `name` is required - it is the only mutable field.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.bot_id` | `string` | yes | Chat bot id (UUID). |
+| `body` | `ChatBotUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ChatBotUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 120 |
+| `body.expected_revision` | `integer \| null` | no | Revision you last read. Omit to overwrite unconditionally. min 1 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateChatBot({ path: { bot_id: "id" }, body: { name: "Example" } });
+```
+
+---
+
+<a id="op-updatewebchatagent"></a>
+
+### `g8.api.webChat.updateWebchatAgent(input)`
+
+**Update Webchat Agent**
+
+- HTTP: `PATCH /api/v1/webchat/agents/{agent_id}`
+- operationId: `update_webchat_agent_webchat_agents__agent_id__patch` (also callable as `g8.api.call("update_webchat_agent_webchat_agents__agent_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of an agent mapping.
+
+`chat_bot_id` is required in the body and is not a field being changed - it
+is how the row is FOUND, because agent ids are unique per bot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.agent_id` | `string` | yes | Agent row id. |
+| `body` | `AgentUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.active` | `boolean \| null` | no |  |
+| `body.agent_id` | `string \| null` | no | max length 255 |
+| `body.agent_name` | `string \| null` | no | min length 1, max length 255 |
+| `body.default` | `boolean \| null` | no |  |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.url_filter` | `Array<string> \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatAgent({ path: { agent_id: "id" }, body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-updatewebchatblog"></a>
+
+### `g8.api.webChat.updateWebchatBlog(input)`
+
+**Update Webchat Blog**
+
+- HTTP: `PATCH /api/v1/webchat/blogs/{blog_id}`
+- operationId: `update_webchat_blog_webchat_blogs__blog_id__patch` (also callable as `g8.api.call("update_webchat_blog_webchat_blogs__blog_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of an article card. `chat_bot_id` locates the row.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.blog_id` | `string` | yes | Article card id. |
+| `body` | `BlogUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`BlogUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.active` | `boolean \| null` | no |  |
+| `body.description` | `string \| null` | no |  |
+| `body.display_order` | `integer \| null` | no | min 0, max 9999 |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.image_url` | `string \| null` | no | max length 1000 |
+| `body.paths` | `Array<string> \| null` | no |  |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.title` | `string \| null` | no | min length 1, max length 500 |
+| `body.url` | `string \| null` | no | min length 1, max length 1000 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatBlog({ path: { blog_id: "id" }, body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-updatewebchatbutton"></a>
+
+### `g8.api.webChat.updateWebchatButton(input)`
+
+**Update Webchat Button**
+
+- HTTP: `PATCH /api/v1/webchat/buttons/{button_id}`
+- operationId: `update_webchat_button_webchat_buttons__button_id__patch` (also callable as `g8.api.call("update_webchat_button_webchat_buttons__button_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of a button. `chat_bot_id` locates the row.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.button_id` | `string` | yes | Button id. |
+| `body` | `ButtonUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ButtonUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.action` | `"link" \| "question" \| "calendar" \| null` | no |  |
+| `body.active` | `boolean \| null` | no |  |
+| `body.category` | `string \| null` | no | min length 1, max length 100 |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.icon` | `string \| null` | no | max length 100 |
+| `body.label` | `string \| null` | no | min length 1, max length 255 |
+| `body.paths` | `Array<string> \| null` | no |  |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.value` | `string \| null` | no | min length 1, max length 1000 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatButton({ path: { button_id: "id" }, body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-updatewebchathandoffpoolteamscope"></a>
+
+### `g8.api.webChat.updateWebchatHandoffPoolTeamScope(input)`
+
+**Update Webchat Handoff Pool Team Scope**
+
+- HTTP: `PATCH /api/v1/webchat/handoff-pool/teams/{team_id}/scope`
+- operationId: `update_webchat_handoff_pool_team_scope_webchat_handoff_pool_teams__team_id__scope_patch` (also callable as `g8.api.call("update_webchat_handoff_pool_team_scope_webchat_handoff_pool_teams__team_id__scope_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+REPLACE which bots a team takes handoffs for. Empty list = every bot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.team_id` | `string (uuid)` | yes | Team id (UUID). |
+| `body` | `HandoffPoolScopeRequest` | yes | Request body; fields below. |
+| `query.pool` | `"external" \| "internal"` | no | Pool to re-scope. Only `external` is accepted by the app: the internal pool is not per-bot. default `"external"` |
+
+Body fields (`HandoffPoolScopeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_ids` | `Array<string (uuid)>` | no | max items 200 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatHandoffPoolTeamScope({
+  path: { team_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatewebchathandoffpooluserscope"></a>
+
+### `g8.api.webChat.updateWebchatHandoffPoolUserScope(input)`
+
+**Update Webchat Handoff Pool User Scope**
+
+- HTTP: `PATCH /api/v1/webchat/handoff-pool/users/{user_id}/scope`
+- operationId: `update_webchat_handoff_pool_user_scope_webchat_handoff_pool_users__user_id__scope_patch` (also callable as `g8.api.call("update_webchat_handoff_pool_user_scope_webchat_handoff_pool_users__user_id__scope_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+REPLACE which bots a person takes handoffs for. Empty list = every bot.
+
+A replace, not a merge: bots left out of the list are dropped.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.user_id` | `string` | yes | Member user id. |
+| `body` | `HandoffPoolScopeRequest` | yes | Request body; fields below. |
+| `query.pool` | `"external" \| "internal"` | no | Pool to re-scope. Only `external` is accepted by the app: the internal pool is not per-bot. default `"external"` |
+
+Body fields (`HandoffPoolScopeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_ids` | `Array<string (uuid)>` | no | max items 200 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatHandoffPoolUserScope({ path: { user_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatewebchatquestion"></a>
+
+### `g8.api.webChat.updateWebchatQuestion(input)`
+
+**Update Webchat Question**
+
+- HTTP: `PATCH /api/v1/webchat/questions/{question_id}`
+- operationId: `update_webchat_question_webchat_questions__question_id__patch` (also callable as `g8.api.call("update_webchat_question_webchat_questions__question_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of a preset question. `chat_bot_id` locates the row.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.question_id` | `string` | yes | Question id. |
+| `body` | `QuestionUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`QuestionUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.active` | `boolean \| null` | no |  |
+| `body.category` | `string \| null` | no | min length 1, max length 100 |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.paths` | `Array<string> \| null` | no |  |
+| `body.placements` | `Array<"launcher" \| "home" \| "conversation"> \| null` | no |  |
+| `body.question` | `string \| null` | no | min length 1, max length 1000 |
+| `body.sort_order` | `integer \| null` | no |  |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatQuestion({ path: { question_id: "id" }, body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-updatewebchatsettings"></a>
+
+### `g8.api.webChat.updateWebchatSettings(input)`
+
+**Update Webchat Settings**
+
+- HTTP: `PATCH /api/v1/webchat/settings`
+- operationId: `update_webchat_settings_webchat_settings_patch` (also callable as `g8.api.call("update_webchat_settings_webchat_settings_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Partial edit of the theme. An unset field is left untouched.
+
+THIS IS LIVE. A saved theme is what the next visitor sees, with no publish
+step in between.
+
+To REMOVE a design-token override, list its path in
+`themeOverridesRemove`. Sending `null` for it does not remove it - under a
+partial update that reads as "leave it alone".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SettingsUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`SettingsUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chat_bot_id` | `string` | yes | Owning chat bot id (UUID). |
+| `body.assistantMessageBgColor` | `string \| null` | no | max length 20 |
+| `body.assistantMessageTextColor` | `string \| null` | no | max length 20 |
+| `body.assistantName` | `string \| null` | no | max length 100 |
+| `body.borderRadius` | `string \| null` | no | max length 20 |
+| `body.botAvatarCustomUrl` | `string \| null` | no | max length 1000 |
+| `body.botAvatarMode` | `"agent" \| "preset" \| "custom" \| null` | no |  |
+| `body.botAvatarPresetUrl` | `string \| null` | no | max length 1000 |
+| `body.botIconType` | `string \| null` | no | max length 50 |
+| `body.chatWidth` | `string \| null` | no | max length 20 |
+| `body.conversationQuestionLimit` | `integer \| null` | no | min 0, max 20 |
+| `body.conversationQuestionsAfterFirstMessage` | `"hide" \| "remain" \| "collapse" \| null` | no |  |
+| `body.copyOverrides` | `Record<string, string> \| null` | no |  |
+| `body.darkMode` | `boolean \| null` | no |  |
+| `body.designTokens` | `DesignTokens \| null` | no |  |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.fontFamily` | `string \| null` | no | max length 100 |
+| `body.fontSize` | `string \| null` | no | max length 20 |
+| `body.headerImageUrlExternal` | `string \| null` | no | max length 1000 |
+| `body.headerImageUrlInternal` | `string \| null` | no | max length 1000 |
+| `body.headerTextColor` | `string \| null` | no | max length 20 |
+| `body.homeQuestionLimit` | `integer \| null` | no | min 0, max 20 |
+| `body.launcherQuestionLimit` | `integer \| null` | no | min 0, max 20 |
+| `body.primaryColor` | `string \| null` | no | max length 20 |
+| `body.robotIconColor` | `string \| null` | no | max length 20 |
+| `body.robotIconType` | `string \| null` | no | max length 50 |
+| `body.secondaryColor` | `string \| null` | no | max length 20 |
+| `body.showHeader` | `boolean \| null` | no |  |
+| `body.showQuickActions` | `boolean \| null` | no |  |
+| `body.showSuggestedQuestions` | `boolean \| null` | no |  |
+| `body.suggestedQuestionsBgColor` | `string \| null` | no | max length 20 |
+| `body.suggestedQuestionsSectionBgColor` | `string \| null` | no | max length 20 |
+| `body.surface` | `"external" \| "internal" \| null` | no |  |
+| `body.themeOverridesRemove` | `Array<string> \| null` | no | Token paths to REMOVE. Unsetting a token is not the same as this. max items 64 |
+| `body.themeSource` | `"default" \| "brand_kit" \| "custom" \| null` | no |  |
+| `body.userMessageBgColor` | `string \| null` | no | max length 20 |
+| `body.userMessageTextColor` | `string \| null` | no | max length 20 |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.updateWebchatSettings({ body: { chat_bot_id: "id" } });
+```
+
+---
+
+<a id="op-uploadwebchatimage"></a>
+
+### `g8.api.webChat.uploadWebchatImage(input?)`
+
+**Upload Webchat Image**
+
+- HTTP: `POST /api/v1/webchat/images`
+- operationId: `upload_webchat_image_webchat_images_post` (also callable as `g8.api.call("upload_webchat_image_webchat_images_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Upload an image for the widget and get back its public URL.
+
+STATELESS: this does not change the widget. Write the returned URL into
+the theme with `PATCH /webchat/settings` - `headerImageUrlExternal` /
+`headerImageUrlInternal` for a header, `botAvatarCustomUrl` for an avatar.
+The file type is checked from its bytes, not its declared content type.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.purpose` | `"header" \| "avatar"` | no | `header` (the widget header image) or `avatar` (the assistant avatar). Only selects where the file is stored. default `"header"` |
+
+**Returns** `ApiResponse_WebchatPayload_`: the envelope `{ data: WebchatPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.webChat.uploadWebchatImage();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-assessmentdefinition"></a>
+
+### `AssessmentDefinition`
+
+Complete branching graph stored as JSONB in chat_assessments.definition.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `start_step_id` | `string` | yes | min length 1, max length 64 |
+| `results` | `Array<AssessmentResultDef>` | no |  |
+| `steps` | `Array<AssessmentStepDef>` | no |  |
+
+<a id="type-availabilityinterval"></a>
+
+### `AvailabilityInterval`
+
+A weekly recurring window. `day` is 0-6 with Monday = 0.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `day` | `integer` | yes | min 0, max 6 |
+| `end` | `string` | yes | min length 5, max length 5, pattern `^(([01]\\d\|2[0-3]):[0-5]\\d\|24:00)$` |
+| `start` | `string` | yes | min length 5, max length 5, pattern `^([01]\\d\|2[0-3]):[0-5]\\d$` |
+
+<a id="type-availabilityoverride"></a>
+
+### `AvailabilityOverride`
+
+A single calendar date whose windows REPLACE that weekday's windows. An empty `intervals` list means closed all day — that is the whole point of an override, so it is not treated as "unset". Window `day` values are ignored here (the date already fixes the day), and a client that sends one has it dropped by Pydantic's default `extra="ignore"`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `date` | `string` | yes | min length 10, max length 10, pattern `^\\d{4}-\\d{2}-\\d{2}$` |
+| `intervals` | `Array<AvailabilityWindow>` | no | max items 10 |
+
+<a id="type-designtokens"></a>
+
+### `DesignTokens`
+
+Extended widget theme tokens stored in chat_widget_settings.designTokens. Shape is the shared FE/BE contract — the TypeScript twin lives in frontend/features/webchat/widget-preview/chat-design-settings.ts.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `badge` | `DesignTokenBadge \| null` | no |  |
+| `colors` | `DesignTokenColors \| null` | no |  |
+| `colorsDark` | `DesignTokenColorsDark \| null` | no |  |
+| `geometry` | `DesignTokenGeometry \| null` | no |  |
+| `header` | `DesignTokenHeader \| null` | no |  |
+| `input` | `DesignTokenInput \| null` | no |  |
+| `motion` | `DesignTokenMotion \| null` | no |  |
+| `radius` | `DesignTokenRadius \| null` | no |  |
+| `shadows` | `DesignTokenShadows \| null` | no |  |
+| `spacing` | `DesignTokenSpacing \| null` | no |  |
+| `transform` | `DesignTokenTransform \| null` | no |  |
+| `typography` | `DesignTokenTypography \| null` | no |  |
+| `version` | `integer` | no | default `1` |