Developers

xyzChat widget installation and developer reference.

One tag embeds the widget, one envelope carries realtime frames, and authenticated workspace REST reads chat data. The webhook shown below is the fixed internal gateway-to-bot-engine contract, not a tenant-configurable public webhook. No versioned public integration API, OAuth app model, or webhook subscription system is offered yet.

Embed

One tag, the whole install.

The whole install

<script async src="https://xyzchat.net/widget/widget.js"
  data-organization-id="YOUR-ORG-ID"></script>

The async tag does not block HTML parsing and initializes from its attributes; XyzChat.init() stays available for programmatic setups. Your workspace shows this snippet with your organization id filled in. Get your snippet

The widget talks to the origin the script came from; add data-host only to point it somewhere else. Try it in the widget playground.

Wire contracts

Three current runtime contracts.

Resume is seq > last_seq. Clients catch up in order after a reconnect.

request   {"action":"send_message","payload":{"chat_id":"…","content":"…"},"request_id":"…"}
response  {"type":"response","request_id":"…","action":"send_message","success":true,
           "payload":{"message":{"seq":42,…}}}
push      {"type":"push","event":"message","payload":{"message":{"seq":43,…}}}

reconnect {"action":"resume","payload":{"chat_id":"…","last_seq":42}}
          → replays persisted messages after seq 42, in sequence.

One envelope for every frame. The server pings every 15 seconds; unauthenticated sockets close after 30.

A paged inbox response embeds each chat's newest message.

POST /v1/agent/login {"email":"…","password":"…"}   → {"token":"…"}

curl -H "Authorization: Bearer $TOKEN" https://xyzchat.net/v1/agent/chats

{"chats":[{"id":"…","status":"open","last_seq":7,
  "last_message":{"author_type":"customer","content":"Do you have an API?","seq":7}}]}

GET /v1/agent/chats/{id}/messages?since_seq=42   → only what you missed
GET /v1/agent/reports                            → daily counts + all-time totals

Log in with your workspace email and password to mint a 256-bit random bearer scoped to one organization. History reads apply the current plan's visibility rules.

This fixed service-to-service webhook is best effort. Empty responses mean silence; timeout or non-200 responses are logged and skipped while the customer message remains persisted.

POST /v1/webhook                   within 10 s, or we move on
{"organization_id":"…","chat_id":"…",
 "message":{"content":"Are you open on weekends?","seq":3},
 "customer":{"id":"…","name":"Dana"},
 "rules":[…],"assigned":false,"ai":{…}}

200 {"responses":[{"content":"You can leave a message here. It stays in this thread for the team to answer."}],"ai_used":false}

rules / ai       = the workspace's own answers + AI knowledge grounding, embedded per message
ai_used          = one AI answer ran this turn; it counts on the plan's monthly allowance
empty responses  = the automaton stays silent, a human picks up
timeout/non-200  = logged and skipped; the persisted customer message remains

Authenticated with a configured shared-secret header. This endpoint is not a customer integration webhook.

Health and metrics: application containers expose health checks, including /healthz; gateway and bot-engine export Prometheus metrics
Persisted chat state: conversation state lives in PostgreSQL and Valkey; automation and mail jobs remain process-local best effort
bcrypt cost 10: for stored agent passwords; agent bearer tokens are 256-bit random values
TLS edge configuration: the deployed edge supports TLS 1.2/1.3, HTTP/2, and 3600 s WebSocket timeouts

Build on it

Start with the widget and workspace API.

Sign up to get the widget organization id and an authenticated agent session. The internal bot webhook is operated by the platform and is not a tenant integration surface.

Get Started Open the widget playground