# Znatoka — Integration guide (LLM-ready)

> Chat as a service, multi-tenant. Two ways to use it:
>  1. Contact-safe buyer<->seller dispute chat: both parties chat over a secret
>     link WITHOUT seeing each other's real phone/username/contact. You drive it
>     over a REST API + HMAC webhook.
>  2. Support widget for your own site: one <script> line, visitor -> you, no
>     backend call. See "Support widget" below.

Base URL: https://znatoka.com
OpenAPI 3.1 (machine-readable): https://znatoka.com/openapi.json
Human docs: https://znatoka.com/docs
Official SDK (Node/TypeScript): npm i chatdisiniaja

## Core concepts
- A "conversation" links a buyer and a seller. Each party opens it via a secret
  token link (https://znatoka.com/c/<token>) — no login, no API key on the client side.
- "name" of each party = the label the OTHER party sees. Anonymize here.
- On every incoming message, the SaaS POSTs an HMAC-signed webhook to your
  platform so you can notify the party who needs to reply.

## Authentication
- Tenant API (all /api/v1/*): send header  X-Api-Key: <api_key>
  Get api_key + webhook_secret by signing up free at https://znatoka.com/signup ,
  manage them at https://znatoka.com/portal .
- Participant endpoints (/c/:token/*) are opened directly by the buyer/seller
  via the secret link — they take NO api key. Keep api_key server-side only.

## Endpoints
POST /api/v1/conversations                 Create a conversation.
GET  /api/v1/conversations/:id             Conversation detail + full transcript.
POST /api/v1/conversations/:id/messages    Send a message as system/buyer/seller.
POST /api/v1/conversations/:id/close       Close the conversation.
GET  /c/:token/info                        Conversation info + the other party's label.
GET  /c/:token/messages                    List messages (participant).
POST /c/:token/messages                    Participant sends a message.
GET  /c/:token/stream                      Realtime SSE (text/event-stream).
GET  /widget.js                            Support-widget loader (public, no key).
POST /w/:widgetKey/session                 Public. {visitor_id} -> {token}: open/restore
                                           that visitor's conversation.

## 1. Create a conversation
Request:
  POST https://znatoka.com/api/v1/conversations
  X-Api-Key: <api_key>
  Content-Type: application/json

  {
    "external_ref": "REFUND-PR05001",     // your own id (optional)
    "subject": "Refund: account can't log in",
    "buyer":  { "name": "Buyer #4821", "self": "You (buyer)" },
    "seller": { "name": "Seller (anonymous)", "self": "You (seller)" }
  }

Response 201:
  {
    "id": "conv_ab12cd34ef",
    "status": "open",
    "external_ref": "REFUND-PR05001",
    "buyer_url":  "https://znatoka.com/c/<buyer_token>",
    "seller_url": "https://znatoka.com/c/<seller_token>",
    "buyer_embed":  "<script src=\"https://znatoka.com/embed.js\" data-token=\"<buyer_token>\" async></script>",
    "seller_embed": "<script src=\"https://znatoka.com/embed.js\" data-token=\"<seller_token>\" async></script>"
  }

Send buyer_url to the buyer and seller_url to the seller. Or drop the ready
buyer_embed / seller_embed <script> onto each party's page for a floating
chat bubble (no chat UI to build).

## 2. Send a platform / system message
  POST https://znatoka.com/api/v1/conversations/:id/messages
  X-Api-Key: <api_key>
  { "role": "system", "body": "Admin: refund approved.", "notify": true }
- role: "system" (default) | "buyer" | "seller"
- notify:false => goes into the transcript + SSE but does NOT fire a webhook.
Response 201: { "id": 12, "sender_role": "system", "body": "...", "created_at": "..." }

## 3. Webhook on every incoming message (OPTIONAL — recommended)
The chat itself works WITHOUT a webhook: any party with the chat page or embed
widget open receives messages in realtime over SSE (/c/:token/stream). A webhook
only adds server-to-server push, so you can alert a party who is NOT currently
viewing the chat. If you skip it, rely on the embed widget or poll
GET /api/v1/conversations/:id. To enable it, set your tenant webhook_url in the
Portal. On each incoming message the SaaS POSTs:
  POST <your webhook_url>
  X-Chatdisiniaja-Signature: sha256=<HMAC-SHA256(rawBody, webhook_secret)>

  {
    "event": "message.created",
    "sent_at": "2026-01-01T10:24:00.000Z",
    "conversation_id": "conv_ab12cd34ef",
    "external_ref": "REFUND-PR05001",
    "sender_role": "buyer",
    "preview": "Hi, the account won't log in...",
    "notify_role": "seller",
    "open_conversation_url": "https://znatoka.com/c/<token>"
  }
Use open_conversation_url to send an "open conversation" alert to notify_role.

## 4. Verify the webhook signature (Node.js)
  const crypto = require('crypto');
  function verify(rawBody, header, secret) {
    const sig = (header || '').replace(/^sha256=/, '');
    const exp = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
    return sig.length === exp.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(exp));
  }
Always compute the HMAC over the RAW request body (bytes), before JSON parsing.

## Official SDK (recommended)
  npm i chatdisiniaja

  import { Chatdisiniaja, verifyWebhookSignature } from 'chatdisiniaja';
  const cdj = new Chatdisiniaja({ apiKey: process.env.CHATDISINIAJA_API_KEY! });

  const conv = await cdj.createConversation({
    externalRef: 'REFUND-123',
    subject: 'Refund dispute',
    buyer:  { name: 'Buyer #4821' },
    seller: { name: 'Seller (anonymous)' },
  });
  // conv.buyer_url / conv.seller_url  — secret chat links
  // conv.buyer_embed / conv.seller_embed — ready-to-paste <script> snippets

  // webhook handler (verify raw body first):
  if (!verifyWebhookSignature(rawBody, req.headers['x-chatdisiniaja-signature'], secret)) return 401;

SDK methods: createConversation, getConversation(id), sendMessage(id, {role,body,notify}),
closeConversation(id). Helpers: verifyWebhookSignature, parseWebhookEvent, embedSnippet.

## Embed widget (no chat UI to build)
Paste on a party's page (token = the part after /c/ in buyer_url/seller_url, or
use buyer_embed/seller_embed directly):
  <script src="https://znatoka.com/embed.js" data-token="<party_token>" async></script>
Options: data-position="left|right", data-color="#5b7cfa", data-label="Help",
data-fullscreen="mobile|always|off" (default "mobile" = opens full-screen on phones).

## Support widget — visitor -> you (different from embed.js)
embed.js needs a token per party (buyer<->seller disputes you create from your
backend). For plain visitor->support chat on your OWN site, use widget.js: one
line on every page, no backend call, no token to manage.
  <script src="https://znatoka.com/widget.js" data-site="<widget_key>" async></script>
- widget_key ("wk_...") is PUBLIC — safe in page source. Your api_key is NOT.
- Each visitor gets a random id in localStorage; ONE open conversation per
  visitor is created/restored via POST /w/:widgetKey/session, so a returning
  visitor lands back in the same thread. Read/reply in the admin inbox.
- Options: data-position, data-color, data-label, data-fullscreen (as above),
  plus data-title-alert="on|off".

### Unread badge (on by default, no setup)
A red count appears on the bubble when a reply arrives while the panel is closed.
It works because widget.js loads the chat iframe HIDDEN as soon as the page does,
so its SSE stream is connected before the bubble is ever clicked; the iframe
posts {type:"cdj:unread", count} to the parent, which draws the badge. The count
resets when the visitor opens the panel, and last-read is kept per browser in
localStorage (cdj_read_<token>), so a reload does not re-announce read messages.
If the tab is in the BACKGROUND, the page title also blinks "(N) Pesan baru" and
is restored on return; disable with data-title-alert="off".
NOTE: the badge and the title blink are the only signals raisable on the host
page. Sound + desktop notifications exist inside the chat UI, but browsers block
both from a cross-origin frame — do not rely on them for a closed panel.

## Errors
Non-2xx returns { "error": "<code>" }, e.g. invalid_api_key (401),
quota_exceeded (402). During beta the Free plan has a monthly conversation quota;
Pro is unlimited.

## Integration checklist
[ ] Store api_key + webhook_secret server-side (never ship to the browser).
[ ] On a dispute/refund, POST /api/v1/conversations, keep the returned id.
[ ] Deliver buyer_url/seller_url (or buyer_embed/seller_embed) to each party.
[ ] (Optional) Expose a webhook endpoint; verify X-Chatdisiniaja-Signature over the raw body.
[ ] (Optional) On webhook, notify notify_role via open_conversation_url — skip if you
    rely on the embed widget / SSE, or poll the transcript.
[ ] Close the conversation when the dispute is resolved.