public

POST `/v1/public/chat-agents/{publicKey}/messages`

One visitor turn — a question, and the answer from that site's own pages.

所有 public 端点

所有开发者文档 →

身份验证

此端点是公开的。它不需要任何凭据或组织——这是我们自己的营销网站和 AI 问答引擎所读取的内容。

此端点不需要组织 ID。您的密钥已用于识别其所属的组织，且响应范围也仅限于该组织。

免费试用

将尖括号中的内容替换为您自己的值，并将键占位符替换为您仪表板中的一个键。

curl -X POST https://api.zinndigital.com/v1/public/chat-agents/{publicKey}/messages \
  -H "Content-Type: application/json" \
  -d '{ "message": <string> }'

已登录？您仪表板中的 API 控制台会自动填入您真实的组织 ID 和您自己的密钥，并针对实时 API 运行请求，以便您查看实际的响应。在 API 控制台中打开此端点

详细信息

The agent answers only from content belonging to this one site. That is enforced in the database query, not by instructing the model, so there is no phrasing a visitor can use to reach another customer's content. handoff_suggested is its own field and is not an error. It is true when the agent could not find the answer on the site — nothing is broken, those pages simply do not say — and the right response is to offer a person, never a guess. refusal is present only when the turn was refused rather than answered, and names the class so a widget can render the right thing: provider_outage, credential_problem, refused (a deliberate decline, such as a monthly cap reached) or unavailable (our fault, and no vendor is named). Answers 404 for an unauthorised Origin, exactly as the config route does and for the same reason.

参数

名称	类型	必填	内容简介
`publicKey (path)`	`string`	是	The agent's public key, as carried in the embed snippet.

请求正文

名称	类型	必填	内容简介
`message`	`string`	是	—
`conversation_id`	`string`	否	Continue an existing thread. Omit to start one.
`locale`	`string`	否	The visitor's language. The agent answers in this, not in the site owner's language.
`page_url`	`string`	否	—

响应

名称	类型	必填	内容简介
`conversation_id`	`string`	是	—
`reply`	`string`	是	—
`citations`	`object[]`	是	The pages of this site the answer was drawn from.
`handoff_suggested`	`boolean`	是	⛔ Not an error. `true` means the agent could not answer from this site's content and a person should take over. Rendering it as a fault would blame a vendor outage for an…
`refusal`	`string<provider_outage, credential_problem, refused, unavailable>`	否	Present only when the turn was refused rather than answered. `refused` is a deliberate decline of ours (a monthly cap reached, an agent switched off) and names no vendor;…
`failure`	`VendorFailure`	否	The classified §2.57 failure behind a refusal — which vendor, whose key, which door. ⛔ Returned ONLY by the owner's preview endpoint; the public widget endpoint never carries it,…

此端点可能返回的错误

404 · 429

POST /v1/public/chat-agents/{publicKey}/messages