public
POST /v1/public/chat-agents/{publicKey}/messages
One visitor turn — a question, and the answer from that site's own pages.
인증
이 엔드포인트는 공개되어 있습니다. 자격 증명이나 조직 정보가 필요하지 않으며, 당사의 마케팅 사이트와 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