{
	"info": {
		"name": "StaqOn Internal Chatbot API",
		"_postman_id": "staqon-internal-chatbot-api-v1",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"description": "# StaqOn Internal Chatbot API\n\nStructural mirror of the **StaqOn Chatbot API** collection, aimed at your own staff instead of external partner/customer members. Like that collection, this documents an **inbound** contract from your side: StaqOn calls a webhook URL on *your* server, synchronously, while a real internal staff member waits in their team's own group conversation for the answer to their Internal `/help` tap.\n\nThis collection's single request is a **simulator** — point `crmWebhookUrl` at your own local/dev endpoint and send it yourself to test your handler against the exact real request shape StaqOn sends, headers and signature included.\n\n## Prerequisite — Internal Link, not Link\n\nThe staff member asking a question must already have a real, active `staqon_links` row (workspace × member × `link_type='internal'`, `status='approved'`) — established via the Internal surface's own `/link` flow, gated through `internal_link_keys` (genuinely separate from the External `link_keys` that gates the External Chatbot API). The Internal Chatbot API never creates this link — it only ever reads whether one already exists.\n\n## Getting your credentials\n\nA workspace admin/owner generates a webhook URL + API key + secret from **Workspace → Settings → API → Internal Chatbot API** (an internal team's card, `app/internal-chatbot-teams.php` → `app/internal-chatbot-edit.php`), one set per internal team. The secret is shown once, at generation time, and is never re-displayed — store it immediately.\n\n## ⚠️ `query_type` validation — opt in for real, or fall back to a written checklist\n\n**By default, `query_type` is free text with zero validation** — exactly as before, same as External. `query_type` is whatever the admin typed into the Internal /help tree editor's button config, verbatim. A mismatch between what the admin typed and what your CRM code checks for is **silent and permanent** — your webhook still returns 200 with a real `answer`, so it never trips failure tracking, it just answers the wrong thing forever.\n\n**You can now opt in to real, StaqOn-enforced validation.** In the Internal /help tree editor (**Workspace → Settings → API → Internal Chatbot API** → a team's edit page), the **\"Registered query types\"** section lets an admin register a list of valid `query_type` values for that key — editable anytime, no key rotation needed. Once a list is registered, StaqOn itself rejects any node saved with a `query_type` not on that list, with this real, visible error at save time:\n\n```\n\\\"<value>\\\" is not a registered query type for this CRM connection. Add it in \\\"Registered query types\\\" first, or use an existing one.\n```\n\nA key with **no registered list** (the default — every key created before this feature existed, and any new key until an admin opts in) behaves exactly as documented above: any `query_type` value is accepted, no validation happens.\n\n**Recommended:** register your list in the admin UI so StaqOn catches a mismatch the moment the tree is edited, rather than relying solely on an out-of-band agreement (see the External Chatbot API's own callout for a written-checklist format as a fallback for keys that haven't registered a list yet).\n\n## The request StaqOn sends you\n\n**Method:** `POST` · **Content-Type:** `application/json` · **Timeout:** StaqOn waits **3 seconds**. Respond fast, or fail fast.\n\nEvery request carries `X-StaqOn-Signature`: a hex-encoded HMAC-SHA256 of the **raw JSON body**, keyed by your Internal Chatbot secret (`internal_chatbot_keys.secret`). Compute the same HMAC and compare with `hash_equals()` before trusting the request.\n\n**This is bare hex only — no `t=` timestamp prefix**, confirmed byte-for-byte identical to External Chatbot's own outbound convention by reading `internal_call_chatbot_crm()` directly: always `hash_hmac('sha256', $payload, $secret)`, nothing else.\n\n```php\n$raw = file_get_contents('php://input');\n$expected = hash_hmac('sha256', $raw, $yourInternalChatbotSecret);\nif (!hash_equals($expected, $_SERVER['HTTP_X_STAQON_SIGNATURE'] ?? '')) {\n    http_response_code(401);\n    exit;\n}\n```\n\n## The response StaqOn expects\n\n`{\"ok\": true, \"answer\": \"...\", \"card\": {...}}` — HTTP 200, valid JSON, `ok` truthy, `answer` a non-empty string. `card` is **optional**: when present it is validated exactly like the card on the comment/message API (same schema — including `table`, and `mailto:` / `tel:` buttons); `\"card\": null` is treated as no card. Anything else (non-200, malformed JSON, missing/falsy `ok`, timeout, unreachable, or an invalid `card`) counts as one failure. **There is no retry** — exactly one attempt per tap.\n\nA card that fails validation counts as one failure, exactly like a missing or empty answer — the whole reply is rejected, nothing is partially sent.\n\nIf the tapped button also has a follow-up menu, the card and the menu are now sent as two separate messages (the card first, then the menu) — never merged or dropped.\n\n**The member sees only the card.** When a reply includes both `answer` and `card`, the member only ever sees the card — `answer` is stored (and included in the realtime event) but is not rendered next to the card, on web, Android, or iOS. Put everything the member needs to see inside the card itself; treat `answer` as a plain-text fallback for older clients only, not as visible accompanying text.\n\n**Card notes:** only one button is supported per card (no current plan for multiple buttons). Tables render on web and Android; iOS support is planned but not yet shipped, so put anything essential in the card `body` for now. A table wider than the screen scrolls horizontally — use 4 columns or fewer for phone-first content (maximum stays 6). On Android, digit runs of 6 or more characters inside table cells become tappable `tel:` links; web and iOS do not auto-link inside table cells yet. See the Card format section of the message API docs for the full schema.\n\n## What the staff member sees on any failure\n\nEvery failure, whatever the cause, shows the identical message on their end — StaqOn never reveals why it failed:\n\n> \"This needs a bit of setup on our end — please contact your admin directly for now.\"\n\n(`ICB_SETUP_NEEDED_MESSAGE` — same uniform-failure discipline as External, worded for an internal audience.)\n\n## Failure tracking\n\nOne shared counter per team, reset to zero on any single success — **identical thresholds to External**, confirmed by reading `ICB_WARN_THRESHOLD`/`ICB_DISABLE_THRESHOLD` in `includes/internal_chatbot.php`:\n\n- **20 consecutive failures** → the admin who set this up gets a warning email. The chatbot keeps trying.\n- **100 consecutive failures** → permanently disabled for that team. Recovery means the admin generates a brand-new key + secret from the Internal Chatbot API team list.\n\n## Rate limits\n\n**Not currently enforced** — same real gap as External. Make sure your endpoint can handle real, unthrottled volume from your team's actual Internal /help usage.\n\n## Optional: asking the staff member a question first\n\nAn API-based button can be configured (in the Internal /help tree editor) with a **prompt** plus one of the same 7 fixed validation types as External: any text, numeric, numeric exact-length, alphanumeric, alphanumeric exact-length, email, or phone (`icb_validate_free_text()` — byte-for-byte mirror of External's own validator, confirmed by reading the code).\n\nWhen configured, tapping the button sends the staff member the prompt and waits for their next chat message as the answer — StaqOn validates it itself, before ever calling your webhook. Invalid on the 1st try → one retry. Invalid again → StaqOn falls back to the main Internal /help menu; your webhook is never called for that attempt. Valid → your webhook is called normally with the answer in `user_input`.\n\n## Health endpoint — supported (since 2026-09-05)\n\n`POST /api/webhook-health.php?action=check` accepts `\"surface\":\"internal_chatbot\"` — its real allow-list is `['external', 'internal', 'chatbot', 'internal_chatbot']` — and authenticates against your Internal Chatbot key's own secret, the same way the External Chatbot branch does against its key. You can poll your key's live `failure_count` / `is_active` the same self-service, HMAC-authenticated way as every other surface. The admin-side team list in the StaqOn UI (**Workspace → Settings → API → Internal Chatbot API**) remains available too, but is no longer the only option.\n\n## Secret rotation\n\nSame real grace-period pattern as every other surface: rotating (`api/internal-chatbot-keys.php`'s `rotate` action) generates a brand-new `secret` immediately while the previous one stays valid for a real **15-minute** grace window. Note this grace window only matters for *inbound* verification (your calls to the health endpoint, `POST /api/webhook-health.php?action=check` with `\"surface\":\"internal_chatbot\"`, which accept a signature made with either the current or the previous secret during the window and report which one matched in `authenticated_with`) — `internal_call_chatbot_crm()`'s own outbound signing always uses whatever `secret` is currently on file, so no grace period is needed on that side; your webhook never needs to try both secrets.\n\n## Cross-API trace IDs\n\nEvery request carries a fresh **`trace_id`** (UUID v4) both in the JSON body and as the `X-StaqOn-Trace-Id` header — generated fresh for each call by `internal_call_chatbot_crm()`. Log it on your side for cross-referencing during debugging.\n"
	},
	"variable": [
		{
			"key": "crmWebhookUrl",
			"value": "https://your-crm.example.com/staqon-internal-chatbot",
			"type": "string"
		},
		{
			"key": "internalChatbotSecret",
			"value": "cbsec_xxx",
			"type": "string"
		}
	],
	"item": [
		{
			"name": "Internal Chatbot query",
			"item": [
				{
					"name": "Simulate StaqOn's request to your webhook",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							},
							{
								"key": "X-StaqOn-Signature",
								"value": "{{internalChatbotSignature}}",
								"type": "text",
								"description": "Hex-encoded HMAC-SHA256 of the raw request body, keyed by your Internal Chatbot secret. Compute this yourself in a pre-request script if testing against a real signature check."
							},
							{
								"key": "X-StaqOn-Trace-Id",
								"value": "b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{crmWebhookUrl}}",
							"host": [
								"{{crmWebhookUrl}}"
							]
						},
						"body": {
							"mode": "raw",
							"raw": "{\n  \"query_type\": \"leave_balance\",\n  \"username\": \"asha29104\",\n  \"external_ref\": \"CRM100\",\n  \"team_id\": 58,\n  \"workspace_id\": 1,\n  \"user_input\": null,\n  \"trace_id\": \"b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e\",\n  \"timestamp\": \"2026-09-05T09:20:11+00:00\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"description": "This is the exact real shape StaqOn sends to your `webhook_url`, one attempt per tap, no retry.\n\n**Body fields:**\n- `query_type` (string) — the tag the admin gave this button when building the Internal /help tree. Route on this field. **Free text by default** — an admin can now opt in to real, StaqOn-enforced validation by registering a list of valid values on the key; see the warning above for the full picture.\n- `username` (string) — the staff member's real StaqOn username, stable and unique.\n- `external_ref` (string | **null**) — the linked staff member's `staqon_links.external_ref` (their CRM ID, captured at Internal `/link` time). Unlike External (always `null` today), Internal's `icb_resolve_api_answer()` actually looks up and forwards the real value on file.\n- `team_id` (integer) — StaqOn's internal id for the internal team this request belongs to.\n- `workspace_id` (integer) — StaqOn's internal id for the workspace this request belongs to — read directly off `internal_chatbot_keys.workspace_id`.\n- `user_input` (string | **null**) — the staff member's validated free-text answer, only present when the tapped button had a prompt configured. **Null** if no prompt was configured for this button.\n- `trace_id` (string) — a fresh UUID v4 for this call, also sent as the `X-StaqOn-Trace-Id` header.\n- `timestamp` (string, ISO 8601) — informational only, not currently used for replay protection.\n\n**Verify the signature before trusting the request:**\n```php\n$expected = hash_hmac('sha256', $rawRequestBody, $yourSecret);\nif (!hash_equals($expected, $_SERVER['HTTP_X_STAQON_SIGNATURE'] ?? '')) {\n    http_response_code(401);\n    exit;\n}\n```"
					},
					"response": [
						{
							"name": "200 OK — real answer",
							"originalRequest": {
								"method": "POST",
								"header": [
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-StaqOn-Signature",
										"value": "{{internalChatbotSignature}}"
									}
								],
								"url": {
									"raw": "{{crmWebhookUrl}}",
									"host": [
										"{{crmWebhookUrl}}"
									]
								},
								"body": {
									"mode": "raw",
									"raw": "{\n  \"query_type\": \"leave_balance\",\n  \"username\": \"asha29104\",\n  \"external_ref\": \"CRM100\",\n  \"team_id\": 58,\n  \"workspace_id\": 1,\n  \"user_input\": null,\n  \"trace_id\": \"b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e\",\n  \"timestamp\": \"2026-09-05T09:20:11+00:00\"\n}"
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"body": "{\n  \"ok\": true,\n  \"answer\": \"You have 6 days of paid leave remaining this year.\"\n}"
						},
						{
							"name": "200 OK — answer + card (leave balance with a table)",
							"originalRequest": {
								"method": "POST",
								"header": [
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-StaqOn-Signature",
										"value": "{{internalChatbotSignature}}"
									}
								],
								"url": {
									"raw": "{{crmWebhookUrl}}",
									"host": [
										"{{crmWebhookUrl}}"
									]
								},
								"body": {
									"mode": "raw",
									"raw": "{\n  \"query_type\": \"leave_balance\",\n  \"username\": \"asha29104\",\n  \"external_ref\": \"CRM100\",\n  \"team_id\": 58,\n  \"workspace_id\": 1,\n  \"user_input\": null,\n  \"trace_id\": \"b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e\",\n  \"timestamp\": \"2026-09-05T09:20:11+00:00\"\n}"
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"body": "{\n  \"ok\": true,\n  \"answer\": \"You have 6 days of paid leave remaining this year.\",\n  \"card\": {\n    \"header_color\": \"#0D9488\",\n    \"icon\": \"person\",\n    \"meta_title\": \"Leave balance\",\n    \"title\": \"Your leave balance\",\n    \"body\": \"Here is what is left for this year.\",\n    \"table\": {\n      \"columns\": [\n        {\n          \"label\": \"Leave type\",\n          \"align\": \"left\"\n        },\n        {\n          \"label\": \"Days left\",\n          \"align\": \"right\"\n        }\n      ],\n      \"rows\": [\n        [\n          \"Paid leave\",\n          \"6\"\n        ],\n        [\n          \"Sick leave\",\n          \"4\"\n        ],\n        [\n          \"Casual leave\",\n          \"2\"\n        ]\n      ]\n    },\n    \"button\": {\n      \"label\": \"Email HR\",\n      \"url\": \"mailto:hr@crm.example.com?subject=Leave%20query\",\n      \"color\": \"#0D9488\"\n    }\n  }\n}"
						},
						{
							"name": "200 OK — free-text answer captured (user_input)",
							"originalRequest": {
								"method": "POST",
								"header": [
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-StaqOn-Signature",
										"value": "{{internalChatbotSignature}}"
									}
								],
								"url": {
									"raw": "{{crmWebhookUrl}}",
									"host": [
										"{{crmWebhookUrl}}"
									]
								},
								"body": {
									"mode": "raw",
									"raw": "{\n  \"query_type\": \"payslip_month\",\n  \"username\": \"asha29104\",\n  \"external_ref\": \"CRM100\",\n  \"team_id\": 58,\n  \"workspace_id\": 1,\n  \"user_input\": \"08-2026\",\n  \"trace_id\": \"9a12f0e3-1234-4a91-9c2e-1f6a8d0b3c5e\",\n  \"timestamp\": \"2026-09-05T09:25:44+00:00\"\n}"
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"body": "{\n  \"ok\": true,\n  \"answer\": \"Your August 2026 payslip has been emailed to you.\"\n}"
						},
						{
							"name": "Any failure — StaqOn's uniform staff-facing fallback",
							"originalRequest": {
								"method": "POST",
								"header": [
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-StaqOn-Signature",
										"value": "{{internalChatbotSignature}}"
									}
								],
								"url": {
									"raw": "{{crmWebhookUrl}}",
									"host": [
										"{{crmWebhookUrl}}"
									]
								},
								"body": {
									"mode": "raw",
									"raw": "{\n  \"query_type\": \"leave_balance\",\n  \"username\": \"asha29104\",\n  \"external_ref\": \"CRM100\",\n  \"team_id\": 58,\n  \"workspace_id\": 1,\n  \"user_input\": null,\n  \"trace_id\": \"b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e\",\n  \"timestamp\": \"2026-09-05T09:20:11+00:00\"\n}"
								}
							},
							"status": "Internal Server Error",
							"code": 500,
							"_postman_previewlanguage": "text",
							"header": [],
							"body": "(any non-2xx status, malformed JSON, missing/falsy ok, or no response within 3s all collapse to the SAME real staff-facing text: \"This needs a bit of setup on our end — please contact your admin directly for now.\" StaqOn never surfaces your actual error to the end user — check your own server logs.)"
						}
					]
				}
			]
		}
	]
}
