API

Chat API.

Send a visitor message to a team and get back the agent that answered, the reply, and its citations. This is the same engine the widget runs on.

POSThttps://desk.whizztech.ai/v1/chat

Authenticate with a wz_live_ key — see Authentication. If you specify no team, the request uses your organization's published team.

Request parameters#

Field	Type		Description
visitorId	string	required	Stable identifier for the end user. Keys cross-conversation memory, so reuse it for a returning visitor.
message	string	required	The visitor's message to answer.
teamId	string	optional	Target a specific team. Omit to use the organization's published team.
widgetKey	string	optional	Public wd_pub_ key identifying a published team. Alternative to teamId.
conversationId	string	optional	Continue an existing conversation. Omit to start a new one; the response returns the new id.

Choosing a teamPass teamId or widgetKeyto target one team. Pass neither and the org's published team answers — the simplest setup when you run a single front office.

Request#

curl

curl https://desk.whizztech.ai/v1/chat \
  -H "Authorization: Bearer wz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "v_9f2a",
    "message": "Do you offer refunds after 30 days?",
    "conversationId": "conv_7c41"
  }'

Response#

Field	Type	Description
conversation_id	string	Id for this conversation. Pass it back as conversationId to continue the thread.
agent	string	Name of the agent the Router picked to answer.
reply	string	The answer to return to the visitor.
citations	array	Sources the reply is grounded in — title and reference per item. Empty when no knowledge was used.

200 OK

{
  "conversation_id": "conv_7c41",
  "agent": "Support",
  "reply": "Refunds are available within 30 days of purchase. After that, store credit applies — I can start either for you.",
  "citations": [
    {
      "title": "Returns & Refunds Policy",
      "source": "https://acme.com/policies/refunds"
    }
  ]
}

Credits and rate limits#

Each answered message costs 1 credit. Requests are rate limited per API key. When your organization is out of credits, the API returns 402 and does not answer.

Errors#

Errors use one envelope across the API: { "error": { "code", "message" } }.

Status	Code		When
400	invalid_request		A required parameter is missing or malformed.
401	invalid_api_key		Missing or invalid API key.
402	insufficient_credits	required	The organization is out of credits. Top up or upgrade to resume answering.
404	team_not_found		The teamId or widgetKey does not resolve to a published team.
429	rate_limited		Too many requests for this key. Retry after backing off.

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "Out of credits. Top up or upgrade to keep answering."
  }
}

NextWebhooks→