StaqOn API

Authentication

Every request must send your API key in a header:

Base URL

Each surface has its own base. Endpoints below are relative to [base_url] for their surface:

Which surface?

There are six real, distinct concepts on this page, not two. Four are API surfaces your CRM calls (or is called by); two are identity-verification mechanisms, separate from messaging entirely. Mixing these up — especially the two pairs that share a word ("Internal", "Chatbot") — is the single most common source of confusion integrating against StaqOn.

A key is bound to the surface of the team it was created against. This is the thing people get wrong first.

Everything is key-only except one endpoint per surface. Those two return 403 until the member's staqon_links row is approved, and again the moment it's revoked.

Consent is governed by staqon_links — one row per (workspace, member, surface) — StaqOn's replacement for the old, removed per-team account-linking flow this section used to describe. The old /link-request.php//link-status.php//link-revoke.php endpoints and the Account settings → Linking Requests tab no longer exist.

Both are outbound calls StaqOn makes to you (your Link/Internal Link webhook), bare-hex HMAC-signed, at the moment a member submits their /link details — not two views of the same payload, but two genuinely different shapes:

See the Link API and Internal Link API sections above for each payload's full, literal request example.

Rate limiting

100 requests/minute per key, rolling 60-second window — a real 429 "Rate limit exceeded. Max 100 requests/minute." with a Retry-After header when exceeded. This is the same limit for every endpoint on both surfaces — there is no per-endpoint override, so it is documented once here rather than repeated on each endpoint below.

20,000 requests/day per key, on top of the per-minute limit above, resetting at midnight Asia/Kolkata (IST). A real 429 when exceeded: {"ok":false,"error":"Daily API limit reached (20,000 requests). Resets in 3h 12m.","retry_after_seconds":11520}, with a matching Retry-After header (seconds until midnight IST). Both limits are checked on every authenticated request; whichever is hit first returns its own 429.

External API

Partner teams. Two-way. Writes need only the key. Base: https://staqon.one/api/v1/external

Internal API

Your own staff. One-way. Writes need an approved link. Base: https://staqon.one/api/v1/internal

Card format

Both comment.php (External) and message.php (Internal) accept an optional card object alongside the plain-text fallback (comment / message), rendering a structured card instead of plain text. The fallback text is still required and is used for push notifications and older clients.

{
  "header_color": "#059669",
  "title": "Approved — ₹5,000",
  "body": "Your wallet topup has been approved and credited.",
  "button": { "label": "View transaction", "url": "https://vistarkriya.com/wallet/txn/1234", "color": "#059669" }
}

{
  "header_color": "#DC2626",
  "title": "Payment failed",
  "body": "Your last payment attempt did not go through.",
  "button": { "label": "Retry payment", "url": "https://vistarkriya.com/wallet/retry/1002", "color": "#DC2626" }
}

{
  "header_color": "#D97706",
  "title": "KYC re-verification needed",
  "body": "Your KYC documents expire in 5 days.",
  "button": { "label": "Update KYC", "url": "https://vistarkriya.com/kyc/update", "color": "#D97706" }
}

{
  "header_color": "#2563EB",
  "title": "Application received",
  "body": "Your loan application is now under review.",
  "button": { "label": "Track status", "url": "https://vistarkriya.com/loan/LN-4521", "color": "#2563EB" }
}

{
  "header_color": "#0891B2",
  "icon": "pending",
  "meta_title": "MLS lead",
  "title": "Update \u2014 Applicant Name",
  "body": "Reference: **MLS26-T064-DB585C**\nStatus: *InProgress*\n\n- Received by partner\n- Awaiting document review\n- Next update within 24h"
}

{
  "username": "4821k9037",
  "message": "Payout processed. ₹12,500 released.",
  "external_ref": "crm-9005",
  "link_url": "https://crm.example.com/payouts/9005/receipt",
  "card": {
    "header_color": "#059669",
    "meta_title": "Payout",
    "title": "₹12,500 released",
    "body": "Your September payout has been released to your registered bank account.",
    "sub_body": "Reference: PAYOUT-9005",
    "button": { "label": "View payout", "url": "https://crm.example.com/payouts/9005", "color": "#059669" }
  }
}

External Chatbot API

Real, live /help answers powered by your own CRM. Unlike the two surfaces above, this is an inbound contract from your side — StaqOn calls a webhook URL on your server, synchronously, while a real external member waits for the answer.

Internal Chatbot API

Real, live Internal /help answers powered by your own CRM (2026-09-05) — the same real, inbound mechanism as the External Chatbot API above, aimed at your own staff instead of external partner/customer members. StaqOn calls a webhook URL on your server, synchronously, while a real internal staff member waits for the answer in their team's own group conversation.

Internal /help — the real 3-stage gate

A staff member types /help literally, inside their internal team's own group conversation (not a guest thread — internal teams have no guest concept; any genuine roster member typing it triggers this). api/messages.php resolves the conversation via icb_internal_team_conv_team_id() (must be a real type='group', is_external_thread=0 conversation belonging to a real, non-archived team_type='internal' team, and the sender must be on that team's roster) — anything else and /help falls straight through as an ordinary literal message, never a silent no-op. Structural mirror of External's own 3-stage gate, in the exact same order:

All three stages passed → StaqOn builds a real bot_menu from this team's root internal_chatbot_nodes (icb_build_menu_from_nodes()), validates it (icb_validate_bot_menu() — byte-for-byte mirror of External's validate_bot_menu()), and sends it via icb_send_bot_message() into the team's own conversation, attributed to the triggering staff member (not the key's created_by) — responds {"ok":true,"intercepted":"internal_help"}.

Internal Chatbot API — admin setup

Configured from Workspace → Settings → API → Internal Chatbot API (app/internal-chatbot-teams.php, owner/admin only, gated by require_workspace_member() + role check — identical auth model to every other admin surface on this page). Every real internal team in the workspace is listed, configured or not (a genuine LEFT JOIN internal_chatbot_keys, not a filtered list) — an unconfigured team's card links straight to the edit page's first-time-setup form rather than a dead end.

api/internal-chatbot-keys.php: create (rejects a second active key for a team already configured — "This team already has an active chatbot key. Revoke it first."), list, rotate (15-minute grace period on secret only — the sk_bot_ bearer key/hash is untouched, since nothing verifies it inbound today), revoke. The webhook URL is validated as a well-formed public http(s):// address (SSRF guard against private/loopback ranges) but never actually called at creation time — same honest gap as Link/Internal Link's own webhook setup.

api/internal-chatbot-nodes.php: list/create/update/delete against internal_chatbot_nodes, a real self-referential adjacency-list table (parent_id → id, ON DELETE CASCADE). Each node carries: question (max 255 chars), answer_type (static or api), answer_text (required for static), link_url (optional, static-only, must be genuine https://, max 500 chars), query_type (required for api — this is the exact free-text tag your webhook receives; free text by default, optionally validated at save time against the key's registered list if one exists, see the callout above), prompt_text/validation_type/validation_length (optional, api-only free-text capture), and follow_up.

Set on an api-type node alongside a real prompt_text. Byte-for-byte mirror of External's own chatbot_validate_free_text(), confirmed by reading icb_validate_free_text() directly:

Link API

/link is StaqOn's workspace-wide identity-linking mechanism (2026-09-01), and the replacement for the old, per-team account-linking flow this documentation used to describe. It has since been merged with the general Webhooks mechanism — one Link API key per workspace now carries the workspace's webhook URL, its shared secret, and its event subscriptions, all in one place.

One key per workspace, generated from Workspace → Settings → API → Link (or the dedicated Link API admin page it links to). You provide a webhook URL; StaqOn generates the bearer key and the shared secret. The secret is shown exactly once, at generation time — store it immediately, it is never re-displayed.

The same real checkbox list as the Webhooks section below — pick which of the seven real events this workspace's webhook receives. Subscriptions can be changed at any time without rotating the key or the webhook URL.

Same grace-period pattern as every other surface on StaqOn: rotating generates a new secret immediately while the previous one stays valid for a real 15-minute window, so an in-flight integration is never broken by a rotation.

Real, live, genuinely built (2026-09-02): the member types /link in chat, or clicks the workspace's "Link this workspace" button, and enters their email plus the answer to this workspace's configured second question (set on the Link admin page — required, not optional; it's the only thing that stops someone who merely knows a customer's email from impersonating them). StaqOn HMAC-signs and POSTs both values to your webhook URL. The member's staqon_links row is marked approved only if your webhook responds {"ok": true} — this is a genuine CRM-verified handshake, not an automatic approval.

POST <your webhook_url>
Content-Type: application/json
X-StaqOn-Signature: <hex>
X-StaqOn-Trace-Id: <uuid>
X-StaqOn-Event: link.verify

{
  "email": "customer@example.com",
  "question": "What's your registered mobile number?",
  "answer": "9876543210",
  "team_context": null,
  "username": "4821k9037",
  "trace_id": "b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e"
}

The signature is bare hex — hash_hmac('sha256', raw_body, your_link_secret) — sent as X-StaqOn-Signature, no t=/timestamp component (this is an outbound call StaqOn makes to you, not an inbound one StaqOn verifies). question is this workspace's real, current second-question text; team_context is always null today (reserved).

{"ok": true}

A real, working, read-only endpoint (2026-09-02) — the reverse direction from every other call on this page: you call StaqOn, HMAC-signed the same way the health endpoint verifies your inbound calls. Use it to show your own customers their real-time connection status on your own site, or to reconcile your own records against StaqOn's.

POST /api/link-list.php
Content-Type: application/json
X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>

{
  "key_id": 24,
  "timestamp": "2026-09-02T06:32:44Z"
}

key_id is your Link API key's numeric ID (shown on the Link admin page once configured). timestamp is an ISO-8601 string, checked for a real ±5 minute freshness window — same convention as the health endpoint. The signature covers the raw request body: hash_hmac('sha256', "{unix_timestamp}.{raw_body}", your_link_secret), sent as t=<unix_timestamp>,v1=<hex>. The older bare-hex format (no t= prefix) is also accepted, matching every other signature check on StaqOn.

{
  "ok": true,
  "links": [
    {
      "crm_email": "customer@example.com",
      "link_type": "external",
      "username": "4821k9037",
      "status": "approved",
      "linked_at": "2026-09-02 12:02:30"
    }
  ]
}

{"ok": false, "error": "Invalid signature or unknown key."}

$keyId = 24;                       // your real Link API key's id
$secret = 'lnksec_...';            // your real Link API secret
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$body = json_encode(['key_id' => $keyId, 'timestamp' => $timestamp]);
$unix = time();
$sig  = 't=' . $unix . ',v1=' . hash_hmac('sha256', $unix . '.' . $body, $secret);

$ch = curl_init('https://staqon.one/api/link-list.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-StaqOn-Signature: ' . $sig],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
// $response['links'] — your workspace's real, current approved External connections

Internal Link API

/link's Internal surface (2026-09-02) — a genuinely separate mechanism from the External Link API above, for linking your own staff's StaqOn identity to your CRM, rather than an external customer's. Its own dedicated table (internal_link_keys), its own admin page (Workspace → Settings → API → Link API → For Internal), its own key/secret/webhook/events, independent from External's.

One key per workspace, generated from the Internal Link admin page. You provide a webhook URL; StaqOn generates the bearer key and the shared secret. The secret is shown exactly once, at generation time — store it immediately, it is never re-displayed.

A staff member types /link in chat (a real two-step conversation: CRM ID first, then email) or uses the direct-click popup (both fields in one submission). StaqOn HMAC-signs and POSTs both to your Internal Link webhook URL. The member's staqon_links row (link_type='internal') is marked approved only if your webhook responds {"ok": true} — a genuine CRM-verified handshake, matching External's own rigor, not an automatic approval on bare free text.

POST <your webhook_url>
Content-Type: application/json
X-StaqOn-Signature: <hex>
X-StaqOn-Trace-Id: <uuid>
X-StaqOn-Event: internal_link.verify

{
  "crm_id": "CRM100",
  "email": "staff@yourcompany.com",
  "username": "4821k9037",
  "trace_id": "b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e"
}

The signature is bare hex — hash_hmac('sha256', raw_body, your_internal_link_secret) — sent as X-StaqOn-Signature, same outbound-call convention as External's own verify contract above (no t=/timestamp component — this is StaqOn calling you, not the reverse).

{"ok": true}

Internal Link keys carry their own independent events subscription list — genuinely separate from the External Link key's own subscriptions, even though both can subscribe to the same real event name. Today the only real event available here is link.status_changed, fired on a real Internal /link approval or revoke.

{
  "event": "link.status_changed",
  "timestamp": "2026-09-02T15:52:15+05:30",
  "data": {
    "user_id": 2,
    "username": "4821k9037",
    "link_type": "internal",
    "status": "approved",
    "workspace_id": 1,
    "team_id": 0
  }
}

Same real delivery discipline as every other webhook on StaqOn: X-StaqOn-Signature is a bare-hex HMAC-SHA256 of the raw body, keyed by your Internal Link secret, plus an X-StaqOn-Event header. One delivery attempt, no retry, no queue. status is "approved" or "revoked"; team_id is always 0 — /link has no team concept, it's workspace-scoped. username (added 2026-09-03) is StaqOn's own real username for the linked person, already resolved before the event fires — no separate lookup needed.

Same real grace-period pattern as every other surface: rotating generates a new secret immediately while the previous one stays valid for a real 15-minute window.

A real, working, read-only endpoint (2026-09-02) — the reverse direction from your Internal Link webhook, direct structural mirror of the External Link API's own link-list.php: you call StaqOn, HMAC-signed the same way the health endpoint verifies your inbound calls. Use it to check a staff member's real-time link status from your own system, or to reconcile your own records against StaqOn's.

POST /api/internal-link-list.php
Content-Type: application/json
X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>

{
  "key_id": 15,
  "timestamp": "2026-09-02T06:32:44Z"
}

key_id is your Internal Link API key's numeric ID (shown on the Internal Link admin page once configured). timestamp is an ISO-8601 string, checked for a real ±5 minute freshness window — same convention as every other real signature check on StaqOn. The signature covers the raw request body: hash_hmac('sha256', "{unix_timestamp}.{raw_body}", your_internal_link_secret), sent as t=<unix_timestamp>,v1=<hex>. The older bare-hex format (no t= prefix) is also accepted.

{
  "ok": true,
  "links": [
    {
      "crm_username": "CRM100",
      "crm_email": "staff@yourcompany.com",
      "username": "4821k9037",
      "status": "approved",
      "linked_at": "2026-09-02 16:29:42"
    }
  ]
}

{"ok": false, "error": "Invalid signature or unknown key."}

$keyId = 15;                            // your real Internal Link API key's id
$secret = 'ilnksec_...';                // your real Internal Link API secret
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$body = json_encode(['key_id' => $keyId, 'timestamp' => $timestamp]);
$unix = time();
$sig  = 't=' . $unix . ',v1=' . hash_hmac('sha256', $unix . '.' . $body, $secret);

$ch = curl_init('https://staqon.one/api/internal-link-list.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-StaqOn-Signature: ' . $sig],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
// $response['links'] — your workspace's real, current approved Internal (staff) connections

Webhooks

StaqOn POSTs a JSON callback to your subscribed URL when a workspace event fires. As of 2026-09-01, webhooks are configured as part of your Link API key — one webhook per workspace (not per team, as this section used to describe), using the same URL and shared secret as your Link key. Pick which events you want at Workspace → Settings → API → Link.

PHP:
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $yourWebhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_STAQON_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Node.js:
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', yourWebhookSecret).update(raw).digest('hex');
const sig = Buffer.from(req.headers['x-staqon-signature'] || '', 'utf8');
const exp = Buffer.from(expected, 'utf8');
const valid = sig.length === exp.length && crypto.timingSafeEqual(sig, exp);
if (!valid) return res.status(401).end();

Python:
import hmac, hashlib
expected = hmac.new(your_webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-StaqOn-Signature', '')):
    return Response(status=401)

{
  "event": "<name>",
  "timestamp": "<ISO-8601>",
  "data": { }
}

Health endpoint

POST /api/webhook-health.php?action=check — a single, read-only, unified endpoint shared across External, Internal and Chatbot. Lets you check your own key/webhook's real status without ever transmitting your secret over the wire.

{
  "surface": "external",
  "key_id": 123,
  "timestamp": "2026-08-30T12:00:00Z"
}

{
  "ok": true, "surface": "external", "is_active": true, "revoked_at": null,
  "last_used_at": "2026-08-30 11:27:24", "usage_count": 881,
  "authenticated_with": "current",
  "bearer_key_rotation": { "grace_period_active": false },
  "webhook": { "is_active": true, "failure_count": 0, "last_triggered_at": "2026-08-27 11:45:55" },
  "grace_period_active": false
}

{
  "ok": true, "surface": "chatbot", "is_active": true, "failure_count": 0,
  "warned_at": null, "last_used_at": "2026-08-30 14:34:30", "revoked_at": null,
  "authenticated_with": "current", "grace_period_active": false
}

Secret rotation

A rotate action now exists per surface (api/api-keys.php's rotate / webhook_rotate, api/chatbot-keys.php's rotate) — generates a brand-new secret/key immediately while keeping the previous one valid for a real 15-minute grace window. This replaces the old revoke-and-recreate pattern, which had zero overlap and would break an in-flight integration instantly.

The health endpoint's response includes rotation state when relevant: grace_period_active, previous_secret_expires_at, minutes_remaining. External/Internal additionally carry a separate bearer_key_rotation block, since the bearer key (api_keys) and the webhook secret (webhooks) rotate independently of each other.

Cross-API trace IDs

Every request across all three surfaces now supports X-StaqOn-Trace-Id: an optional request header, always present on the response.

A member taps /help → the External Chatbot API fires an outbound query to your CRM, tagged with a trace ID (both as a trace_id field in the JSON body and as the X-StaqOn-Trace-Id header) → your CRM later posts a reply to that same member via the External API, including that same trace ID on the call. Both real events are now queryable together by trace ID — the two separate API calls (different surface, different endpoint, different timing) are provably one logical transaction.

Postman collections

One collection per surface — deliberately separate, so a request can't be copied from one surface to the other and fail with a 400. Import, set apiKey + baseUrl once, and run every endpoint.