{"openapi":"3.1.0","info":{"title":"FLOW (AIFLOW) Public API","version":"2.0.0","summary":"Multi-channel messaging, conversations, flow triggers, partner provisioning, MCP and reporting webhooks.","description":"FLOW is an Israeli multi-channel automation platform: WhatsApp (official Cloud API, personal lines, desktop lines), Messenger, Instagram, Telegram, email and a website widget.\n\nHuman guide: https://flow.txi.co.il/developers · Agent reference: https://flow.txi.co.il/llms-full.txt · MCP tools: https://flow.txi.co.il/api/mcp-tools.json\n\nCredentials (each endpoint lists the one it takes):\n- External API key — /api/external/*. From /settings/webhooks or partner provisioning.\n- API token (JWT) / per-flow token — /api/webhook/outbound*. From /api/auth/api-token with credentials from /settings/api-access.\n- Partner key — /api/partner/*. Issued by the FLOW team.\n- MCP key — /api/mcp. From /settings/mcp or partner provisioning.\n- Embed site key — /api/embed/* (public, origin-checked).\n\nOperations may carry `x-flow-notes`: behaviour a caller should know that differs from what one would assume.","contact":{"name":"FLOW","url":"https://flow.txi.co.il/developers"}},"servers":[{"url":"https://flow.txi.co.il","description":"Production"}],"tags":[{"name":"Messaging","description":"Proactive sends."},{"name":"Conversations","description":"Read, reply, release."},{"name":"Content","description":"Quick replies and templates."},{"name":"Desktop lines","description":"WhatsApp running on an agent's computer."},{"name":"Flow triggers","description":"Start flows from a CRM, form or call center."},{"name":"Partner","description":"Machine provisioning of tenants (PARSI, SITISELL, your platform)."},{"name":"MCP","description":"The full builder toolset for AI agents."},{"name":"Embed widget","description":"Website chat / search / form widget backend."},{"name":"Reporting webhooks","description":"Events FLOW POSTs to your URL."},{"name":"Meta","description":"This document."}],"paths":{"/api/external/send":{"x-flow-route":"src/pages/api/external/send.js","post":{"operationId":"sendMessage","tags":["Messaging"],"summary":"Send a proactive message on any channel","description":"Sends one message to a recipient on WhatsApp personal (Green / desktop lines), WhatsApp official (template only), Messenger, Instagram DM, Telegram or email.\n\nAfter authentication the HTTP status is ALWAYS 200 (except 429): read `ok` and `status`. Every attempt also fires a `message.sent` or `message.failed` reporting webhook carrying the same `requestId`.\n\nWhatsApp personal sends are logged into the conversation, stamped `sentBy: external_api` and — unless `system: true` — claim the thread for `external_api` and pause the bot permanently (an operator resumes it, or call /unclaim).","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendRequest"},"examples":{"whatsappPersonalText":{"summary":"WhatsApp personal — text","value":{"channel":"whatsapp_green","instanceId":"3f0c…-uuid","to":"972501234567","type":"text","text":"שלום! ההזמנה שלך מוכנה"}},"whatsappOfficialTemplate":{"summary":"WhatsApp official — approved template","value":{"channel":"whatsapp_official","to":"972501234567","type":"template","templateName":"order_ready","templateLanguage":"he","templateParams":["דנה","#1234"]}},"systemNotice":{"summary":"Informational notice that does not take over the thread","value":{"channel":"whatsapp_green","instanceId":"3f0c…-uuid","to":"972501234567","text":"המוקד סגור כעת, נחזור אליך מחר ב-8:00","system":true,"senderName":"מוקד"}},"telegramImage":{"summary":"Telegram — image with caption","value":{"channel":"telegram","chatId":"123456789","type":"image","mediaUrl":"https://example.com/a.jpg","text":"Your receipt"}},"email":{"summary":"Email","value":{"channel":"email","configId":"email-config-id","to":"dana@example.com","emailSubject":"Your order","text":"Hi Dana, …"}}}}}},"responses":{"200":{"description":"Attempt finished. `ok` tells success; `status` tells why not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"},"examples":{"sent":{"value":{"ok":true,"requestId":"9b2f…","status":"sent","messageId":"BAE5F…","instancePhone":"972535551234","channel":"whatsapp_unofficial:7105123456","docs":"https://flow.txi.co.il/docs/external-send-api"}},"invalid":{"value":{"ok":false,"requestId":"9b2f…","status":"invalid_params","error":"\"to\" is required","docs":"https://flow.txi.co.il/docs/external-send-api"}},"config":{"value":{"ok":false,"requestId":"9b2f…","status":"config_error","error":"Multiple active WhatsApp Cloud configs. Pass \"phoneNumberId\" to select one."}}}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"description":"More than 100 requests/minute for this tenant (in-memory, per server process). Body includes requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["Rate limit is 100/min per tenant (the old docs said 60).","A line in warm-up or flagged by WhatsApp answers ok=false with status = the gate code (instance_warming, instance_flagged_low_delivery, instance_requires_warmup).","Every channel is written to the conversation transcript (message_sent, direction outgoing) and the response carries `conversationId`. Only whatsapp_green claims the thread and pauses the bot (unless system:true); other channels log without claiming.","`conversationId` in the body is used when it is this tenant's and the same recipient; otherwise it is ignored and the response says `conversationIdIgnored` (not_found / recipient_mismatch). Without it the recipient's active conversation on that channel is used, else a new one (status completed for non-personal channels, so the customer's reply still starts the channel's flow).","channel=email answers provider_error when the mail provider rejects the message (it used to report sent).","channel=email ignores type/mediaUrl (text only).","messenger/instagram do not validate that `text` / `mediaUrl` is present."]}},"/api/external/conversations":{"x-flow-route":"src/pages/api/external/conversations/index.js","get":{"operationId":"listConversations","tags":["Conversations"],"summary":"List conversations (newest activity first)","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"channel","in":"query","description":"`email` and `whatsapp_unofficial` match by prefix; any other value must equal the stored channel string exactly (e.g. `whatsapp`, `telegram`, or `messenger:<pageId>`).","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","completed","abandoned","error"]}}],"responses":{"200":{"description":"Page of conversations.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":""},"offset":{"type":"integer","description":""},"hasMore":{"type":"boolean","description":""}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"list_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["`channel` is a family: it matches the bare name and any `<family>:<id>` (messenger, telegram:<configId>, email:<configId>, whatsapp_unofficial:<idInstance>); instagram also matches instagram_dm; whatsapp_official / whatsapp_green are accepted aliases. A value containing \":\" matches that one stored channel exactly.","No rate limit on this endpoint."]}},"/api/external/conversations/{id}":{"x-flow-route":"src/pages/api/external/conversations/[id]/index.js","get":{"operationId":"getConversation","tags":["Conversations"],"summary":"Get a conversation with its latest messages","description":"Messages are returned oldest-first; `limit` takes the most recent N.","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id. (Unlike reply/unclaim, a Lead handle is NOT accepted here.)","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Conversation and messages.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"conversation":{"$ref":"#/components/schemas/ConversationSummary"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":""},"hasMore":{"type":"boolean","description":""},"oldestTimestamp":{"type":["string","null"]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"conversation_not_found_or_not_yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"fetch_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["No cursor: only the newest 500 messages are reachable (hasMore=true but no `before` parameter)."]}},"/api/external/conversations/{id}/reply":{"x-flow-route":"src/pages/api/external/conversations/[id]/reply.js","post":{"operationId":"replyToConversation","tags":["Conversations"],"summary":"Reply into an existing conversation (channel-aware)","description":"Routes by the conversation's own channel — the caller does not need to know the line.\n\n| Channel | Supports |\n|---|---|\n| WhatsApp personal / desktop | text + media, no 24h window, groups, `replyToMessageId` |\n| WhatsApp official | text inside 24h, template any time; media → 501 |\n| Messenger | text + media, 24h (7d with Human Agent tag once approved) |\n| Instagram DM | text + media, 24h |\n| Telegram | text + image/video/document |\n| Email | text, threaded; media → 501 |\n| fb_comment / ig_comment | text; `replyMode` public/private |\n\nUnless `system: true`, a reply claims the thread as `external_api:<agentId|account>` and pauses the bot permanently.","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id OR a stable Lead id (the reporting webhook emits a Lead id when \"stable reply handle\" is on). A Lead id resolves to the live conversation for that phone.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyRequest"},"examples":{"text":{"value":{"type":"text","text":"היי, אני דנה מהמוקד — איך אפשר לעזור?","agentName":"דנה","agentId":"crm-17"}},"template":{"value":{"type":"template","templateName":"followup_24h","templateLanguage":"he","templateParams":["דנה"]}},"notice":{"value":{"type":"text","text":"כל הנציגים תפוסים, נחזור בהקדם","system":true}}}}}},"responses":{"200":{"description":"Sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyResult"}}}},"400":{"description":"Bad params or missing config: type_must_be_text_image_video_document_template, text_required_for_text_type, mediaUrl_required_for_media_types, templateName_required_for_template_type, template_only_for_cloud, template_not_found, template_not_approved, *_config_missing, instance_not_active, channel_not_yet_supported, comment_replies_are_text_only, …","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"conversation_not_found_or_not_yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"description":"Outside the send window (outside_24h_window, outside_messenger_window) or the line is warming/flagged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"501":{"description":"media_via_cloud_not_yet_supported_in_external_api / media_via_email_not_yet_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"502":{"description":"Upstream provider error (provider_error: …, email_send_failed: …, comment_graph_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["No rate limit on reply (send has one).","Reply and send both log direction `outgoing`. Older rows may hold inbound/outbound; the read endpoints return incoming/outgoing only, and receivers of reporting webhooks should accept both spellings."]}},"/api/external/conversations/{id}/unclaim":{"x-flow-route":"src/pages/api/external/conversations/[id]/unclaim.js","post":{"operationId":"unclaimConversation","tags":["Conversations"],"summary":"Release a conversation the API claimed (and resume the bot)","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id or Lead id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resumeBot":{"type":"boolean","description":"Also clear the bot pause.","default":true},"force":{"type":"boolean","description":"Release a human operator's claim too.","default":false}}}}}},"responses":{"200":{"description":"Released.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"id":{"type":"string","description":""},"cleared":{"type":"boolean","enum":[true]},"resumedBot":{"type":"boolean","description":""},"released":{"type":"string","description":"","enum":["not_claimed","external_api_claim","forced"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"conversation_not_found_or_not_yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"description":"claimed_by_human — an operator (or someone answering from the phone) holds the conversation. Resend with force:true to release it anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"500":{"description":"unclaim_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["Only claims the API made (claimedBy external_api or external_api:<agent>) are released by default; a human claim needs force:true."]}},"/api/external/conversations/unclaim-bulk":{"x-flow-route":"src/pages/api/external/conversations/unclaim-bulk.js","post":{"operationId":"unclaimConversationsBulk","tags":["Conversations"],"summary":"Release every conversation claimed by a given marker prefix","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claimedByPrefix":{"type":"string","description":"Required guard: only rows whose claimedBy starts with this (e.g. \"external_api:\")."},"since":{"type":"string","description":"Only rows claimed at/after this ISO time.","format":"date-time"},"resumeBot":{"type":"boolean","description":"","default":true}},"required":["claimedByPrefix"]},"example":{"claimedByPrefix":"external_api:","since":"2026-11-18T00:00:00Z"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"updated":{"type":"integer","description":"Rows changed."},"resumedBot":{"type":"boolean","description":""},"filter":{"type":"object","properties":{"claimedByPrefix":{"type":"string","description":""},"since":{"type":["string","null"]}}}}}}}},"400":{"description":"claimedByPrefix_required / bad_since_iso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"unclaim_bulk_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/external/device-jobs":{"x-flow-route":"src/pages/api/external/device-jobs.js","get":{"operationId":"listDeviceJobs","tags":["Content"],"summary":"TikTok drafts waiting to be finished on the tenant's phone (device runner)","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"responses":{"200":{"description":"Waiting jobs: post id, target id, caption with its attributed link, AI-label flag, upload time.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"jobs":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}},"post":{"operationId":"deviceJobAction","tags":["Content"],"summary":"Mark a job live after publishing, or raise an alert to the owner","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"mark-live | alert"},"targetId":{"type":"string","description":"Target to mark live (mark-live)."},"kind":{"type":"string","description":"Alert kind (alert)."},"message":{"type":"string","description":"Alert text (alert)."}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""}}}}}},"400":{"description":"Bad request.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"error":{"type":"string","description":""}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/external/quick-replies":{"x-flow-route":"src/pages/api/external/quick-replies.js","get":{"operationId":"listQuickReplies","tags":["Content"],"summary":"List the tenant's quick replies (\"/\" shortcuts)","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"responses":{"200":{"description":"Items.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"items":{"type":"array","items":{"$ref":"#/components/schemas/QuickReply"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"server_error (ok=false, empty items).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/external/templates":{"x-flow-route":"src/pages/api/external/templates.js","get":{"operationId":"listPersonalTemplates","tags":["Content"],"summary":"List personal WhatsApp templates, grouped by category","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"responses":{"200":{"description":"Items + groups (uncategorised → \"כללי\").","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"items":{"type":"array","items":{"$ref":"#/components/schemas/PersonalTemplate"}},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/PersonalTemplate"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"server_error (ok=false, empty items/groups).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/external/wa-templates":{"x-flow-route":"src/pages/api/external/wa-templates.js","get":{"operationId":"listWhatsAppTemplates","tags":["Content"],"summary":"List Meta (WhatsApp official) templates per line, live from Meta","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"parameters":[{"name":"phoneNumberId","in":"query","schema":{"type":"string"},"description":"Restrict to one line."},{"name":"status","in":"query","schema":{"type":"string"},"description":"e.g. APPROVED (case-insensitive)."}],"responses":{"200":{"description":"One entry per WABA.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"lines":{"type":"array","items":{"$ref":"#/components/schemas/WaTemplateLine"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"server_error (ok=false, empty lines).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["Only the first 100 templates per WABA (no paging).","Lines sharing a WABA are listed once, under the first line's phoneNumberId.","A line whose Graph call fails is still listed, with templates: [] and error: graph_unreachable (the call itself answers 200)."]}},"/api/external/desktop-lines":{"x-flow-route":"src/pages/api/external/desktop-lines/index.js","get":{"operationId":"listDesktopLines","tags":["Desktop lines"],"summary":"List desktop lines (WhatsApp on an agent's computer) with live device status","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"responses":{"200":{"description":"Lines.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DesktopLine"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"description":"read_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/external/desktop-lines/command":{"x-flow-route":"src/pages/api/external/desktop-lines/command.js","post":{"operationId":"runDesktopCommand","tags":["Desktop lines"],"summary":"Run one command on a desktop line's device","description":"Allowed methods — read: account.info, account.sendStats, message.get, message.downloadMedia, chat.list, chat.get, chat.messages, contact.check, contact.get, contact.profilePic, contact.resolve, group.info, group.inviteCode, label.list. Write: account.logout, message.send/reply/forward/react/edit/delete, chat.markRead/markUnread/archive/unarchive/pin/unpin/mute/unmute/presence, contact.block/unblock, group.create/addParticipants/removeParticipants/promote/demote/setSubject/setDescription/setSettings/revokeInvite/join/leave, label.setForChat. Param shapes: LINK_PROTOCOL.md §4.","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineId":{"type":"string","description":"Desktop line id."},"method":{"type":"string","description":"Allow-listed method name."},"params":{"type":"object"},"id":{"type":"string","description":"Idempotency key (≤100 chars): resending the same id returns the device's cached result instead of running twice."},"timeoutMs":{"type":"integer","description":"Wait for the device this long."}},"required":["lineId","method"]},"example":{"lineId":"line-uuid","method":"chat.list","params":{"limit":20},"id":"crm-req-0001"}}}},"responses":{"200":{"description":"Device answered: ok=true with `result`, or ok=false with the device's refusal { code: NOT_READY | NOT_ON_WHATSAPP | BAD_PARAMS | … }.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"id":{"type":"string","description":""},"result":{},"error":{"type":"object","properties":{"code":{"type":"string","description":""},"message":{"type":"string","description":""}}}}}}}},"400":{"description":"lineId and method are required / method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Access denied for this line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"404":{"description":"line_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"description":"device_offline / device_timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/external/desktop-lines/import-groups":{"x-flow-route":"src/pages/api/external/desktop-lines/import-groups.js","post":{"operationId":"importDesktopGroups","tags":["Desktop lines"],"summary":"Pull every WhatsApp group of a desktop line into the inbox","security":[{"externalApiKey":[]},{"externalApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineId":{"type":"string","description":""},"messagesPerGroup":{"type":"integer","description":"0–200.","default":30}},"required":["lineId"]}}}},"responses":{"200":{"description":"Imported.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"groups":{"type":"integer","description":""},"createdConversations":{"type":"integer","description":""},"importedMessages":{"type":"integer","description":""}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"line_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"502":{"description":"Device error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"503":{"description":"device_offline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}}},"/api/auth/api-token":{"x-flow-route":"src/pages/api/auth/api-token.js","post":{"operationId":"issueApiToken","tags":["Flow triggers"],"summary":"Exchange API client credentials for a short-lived JWT","description":"Client credentials are created at /settings/api-access. The JWT authorises /api/webhook/outbound and /api/webhook/outbound-status (and lead triggers) for flows the client's owner owns.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","description":""},"apiKey":{"type":"string","description":""},"ttlSec":{"type":"integer","description":"600–86400.","default":3600}},"required":["clientId","apiKey"]}}}},"responses":{"200":{"description":"Token.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"tokenType":{"type":"string","description":"","enum":["Bearer"]},"accessToken":{"type":"string","description":""},"expiresInSec":{"type":"integer","description":""},"clientNumber":{},"clientId":{"type":"string","description":""}}}}}},"400":{"description":"clientId and apiKey are required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"401":{"description":"Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"Rate limited (per IP).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/webhook/outbound":{"x-flow-route":"src/pages/api/webhook/outbound.js","post":{"operationId":"triggerOutboundFlow","tags":["Flow triggers"],"summary":"Start a flow for a recipient (proactive WhatsApp)","description":"Queues the flow for the recipient and answers 202 immediately (default queue mode). Poll /api/webhook/outbound-status?queueId= or subscribe to reporting webhooks.\n\nEverything inside `data` becomes a flow variable ({{key}}). `FETCH_DATA` (aliases fetchData, fetch_data; object, array or JSON string) is stored on the conversation and echoed as `data.fetchData` on every reporting webhook for it.\n\nIdempotency: an identical body for the same flow + recipient within 10 minutes is not enqueued again — the first queueId is replayed with `deduplicated: true`.\nCase file guard: if the recipient already completed this flow (station) the call answers 200 `skipped: true` — pass `_allowResend: true` to force. Disabled while the flow is in debug mode.","security":[{"outboundToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"Recipient: digits with or without +, or a WhatsApp BSUID."},"flowId":{"type":"string","description":"Flow to start. Required. Must be active."},"data":{"type":"object","additionalProperties":true,"description":"Flow variables. `text` here goes through the compliance check."},"templateId":{"type":"string","description":"Shortcut for data.templateId."},"templateGroupId":{"type":"string","description":"Shortcut for data.templateGroupId."},"templateName":{"type":"string","description":"Shortcut for data.templateName."},"FETCH_DATA":{"description":"Opaque correlation payload echoed on webhooks."},"forceSend":{"type":"boolean","description":"Send although compliance answered \"review\"."},"allowMarketing":{"type":"boolean","description":"Evaluate data.text as marketing-allowed."},"_allowResend":{"type":"boolean","description":"Bypass the case-file \"already completed\" guard."}},"required":["phone","flowId"]},"example":{"phone":"972501234567","flowId":"flow-uuid","data":{"name":"דנה","code":"1234"},"FETCH_DATA":{"crmLeadId":"L-991"}}}}},"responses":{"200":{"description":"Synchronous mode result (OUTBOUND_QUEUE_MODE=0) or `skipped: true` (station_already_completed).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":""},"skipped":{"type":"boolean","description":""},"reason":{"type":"string","description":""},"hint":{"type":"string","description":""}}}}}},"202":{"description":"Queued (or deduplicated replay).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"queued":{"type":"boolean","enum":[true]},"deduplicated":{"type":"boolean","description":""},"queueId":{"type":"string","description":""},"flowId":{"type":"string","description":""},"phone":{"type":"string","description":""},"queuedAt":{"type":"string","format":"date-time"}}},"example":{"success":true,"queued":true,"queueId":"q-uuid","flowId":"flow-uuid","phone":"972501234567","queuedAt":"2026-11-19T08:00:00.000Z"}}}},"400":{"description":"Valid phone number is required / Flow ID is required / Invalid phone number format / Flow is not active / WhatsApp not configured for the flow owner / template / start-trigger validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"Token is valid but not allowed for this flow owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"Flow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"409":{"description":"Compliance requires review — resubmit with forceSend=true. Body includes `compliance`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"422":{"description":"Compliance blocked the text/template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"Rate limited: 50 requests/second per IP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"Failed to trigger outbound flow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}},"x-flow-notes":["Error shape here is { error } (no ok/docs), unlike /api/external/*.","Idempotency memory is per server process and lost on restart."]}},"/api/webhook/outbound-status":{"x-flow-route":"src/pages/api/webhook/outbound-status.js","get":{"operationId":"getOutboundStatus","tags":["Flow triggers"],"summary":"Status of a queued outbound trigger","security":[{"outboundToken":[]}],"parameters":[{"name":"queueId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Queue row.","content":{"application/json":{"schema":{"type":"object","properties":{"queueId":{"type":"string","description":""},"status":{"type":"string","description":"pending / processing / done / failed …"},"success":{"type":["boolean","null"]},"queuedAt":{"type":"string","description":""},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"attempts":{"type":"integer","description":""},"error":{"type":["string","null"]},"result":{}}}}}},"400":{"description":"queueId is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"401":{"description":"Invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"Not allowed for this flow owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"Queue item / flow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/webhook/flow/{flowId}/lead":{"x-flow-route":"src/pages/api/webhook/flow/[flowId]/lead.js","post":{"operationId":"submitLead","tags":["Flow triggers"],"summary":"Push a lead into a flow's \"API lead\" trigger","description":"The flow's API-lead start node decides auth (none / api_key header / basic / bearer / hmac-sha256 of the JSON body, header default X-Signature-256, optional \"sha256=\" prefix) and maps body fields (dot paths) to variables. An API JWT from /api/auth/api-token is also accepted. The whole body is kept as `_leadData`. `secondarySource` (integer 0–1,000,000) tags the lead.","security":[{"leadTriggerAuth":[]},{"outboundToken":[]},{}],"parameters":[{"name":"flowId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"phone":"972501234567","name":"דנה","source":"landing-a","secondarySource":12}}}},"responses":{"200":{"description":"Lead received and flow started.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","description":""},"variables":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Missing flowId / Flow does not have an API Lead Trigger node.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"401":{"description":"Auth failed (message names the reason).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"Flow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"Failed to process lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}},"x-flow-notes":["HMAC-SHA256 is verified over the raw request bytes (hex, optional sha256= prefix, any case). Signatures over the compact JSON re-serialisation are still accepted for older senders.","A missing, malformed or wrong-length signature answers 401. Body limit 1 MB (413).","Only the first engine result of type \"message\" is sent, directly via the Cloud API."]}},"/api/webhook/external/{stream}":{"x-flow-route":"src/pages/api/webhook/external/[stream].js","post":{"operationId":"captureExternalWebhook","tags":["Flow triggers"],"summary":"Inbound capture endpoint for a third-party system (GET/PUT/PATCH/DELETE also accepted)","description":"Accepts JSON, urlencoded or text-only multipart (≤5 MB), logs it, and — when the stream is configured by FLOW for the tenant — dispatches it (e.g. a call-center event that starts a flow). Always answers 200 so the sender does not retry. Streams are provisioned by the FLOW team.","security":[{"externalStreamToken":[]},{}],"parameters":[{"name":"stream","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._\\-]{1,80}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}},"application/x-www-form-urlencoded":{"schema":{"type":"object"}},"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Captured.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"stream":{"type":"string","description":""},"received":{"type":"object","properties":{"method":{"type":"string","description":""},"contentType":{"type":"string","description":""},"bodyKeys":{"type":["array","null"],"items":{"type":"string"}},"receivedAt":{"type":"string","description":""}}}}}}}},"400":{"description":"invalid stream slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}},"401":{"description":"unauthorized (only when the server has EXTERNAL_WEBHOOK_TOKEN set)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}},"x-flow-notes":["Open (no auth) unless the server sets EXTERNAL_WEBHOOK_TOKEN — one token for all streams."]}},"/api/partner/provision":{"x-flow-route":"src/pages/api/partner/provision.js","post":{"operationId":"provisionTenant","tags":["Partner"],"summary":"Create or attach a FLOW tenant and return every credential it needs","description":"One call connects a project: tenant + external API key + login-free connect link + embed widget site + MCP key (+ optional PARSI store).\n\nWith `source` + `externalRef` the tenant is linked one-to-one to your record: the same pair always returns the same tenant, whatever the name. Without a link, a name never selects an existing tenant: a taken name answers 409 tenant_name_taken (no credentials); attach with mode=attach + existingUserId.\nRepeat calls are safe: the API key is returned as-is, the MCP key is kept (only its prefix is returned), the embed site is reused. Use want.regenerate* to rotate.","security":[{"partnerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionRequest"},"examples":{"simple":{"value":{"projectName":"My Clinic","email":"owner@clinic.co.il"}},"parsiStore":{"summary":"PARSI store (one tenant per store)","value":{"projectName":"חנות הפרחים","source":"parsi","externalRef":"site_8812","store":{"host":"flowers.parsi.co.il","apiKey":"pmk_…"},"want":{"embed":false}}}}}}},"responses":{"200":{"description":"Provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionResult"}}}},"400":{"description":"projectName_required / existingUserId_required_for_attach / invalid_source / invalid_external_ref","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"401":{"description":"invalid_partner_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"404":{"description":"tenant_not_found (attach)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"409":{"description":"tenant_name_taken (an existing tenant has this name — no credentials are returned; attach by userId or resend with confirmNew:true) / possible_duplicate_tenant (candidates without userId — attach by userId or resend with confirmNew:true) / linked_tenant_missing / external_ref_linked_to_other_tenant / tenant_already_linked / link_race","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"500":{"description":"Unexpected error (message truncated to 200 chars).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"503":{"description":"partner_provisioning_disabled (FLOW_PARTNER_KEY not set on the server)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}}},"x-flow-notes":["A name never selects an existing tenant: mode=new whose slug matches an existing username answers 409 tenant_name_taken with no credentials. Credentials come back only for a tenant the call creates, the tenant linked to source+externalRef, or mode=attach + existingUserId.","Duplicate-candidate 409s list username/displayName but not userId; get the userId from the FLOW admin to attach.","confirmNew:true with a taken name creates a separate tenant under a free username (name-2, …)."]}},"/api/partner/tenant-link":{"x-flow-route":"src/pages/api/partner/tenant-link.js","get":{"operationId":"getTenantLink","tags":["Partner"],"summary":"Look up a linked tenant and its integration health","security":[{"partnerKey":[]}],"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string"}},{"name":"externalRef","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Linked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"link":{"$ref":"#/components/schemas/PartnerLink"},"tenant":{"type":"object","properties":{"userId":{"type":"string","description":""},"username":{"type":"string","description":""},"displayName":{"type":"string","description":""},"isActive":{"type":"boolean","description":""}}},"health":{"type":"object","properties":{"apiKey":{"type":"boolean","description":""},"mcp":{"type":"boolean","description":""},"mcpKeyPrefix":{"type":"string","description":""},"embedSites":{"type":"integer","description":""}}}}}}}},"400":{"description":"invalid_source / invalid_external_ref","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"401":{"description":"invalid_partner_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"404":{"description":"not_linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"409":{"description":"linked_tenant_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"503":{"description":"partner_provisioning_disabled (FLOW_PARTNER_KEY not set on the server)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}}}},"delete":{"operationId":"deleteTenantLink","tags":["Partner"],"summary":"Unlink (and by default revoke the partner's credentials)","description":"revoke (default true) replaces the tenant's external API key and turns off its MCP key. The tenant, its conversations and flows are kept. The embed site key is NOT revoked.","security":[{"partnerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":""},"externalRef":{"type":"string","description":""},"revoke":{"type":"boolean","description":"","default":true}},"required":["source","externalRef"]}}}},"responses":{"200":{"description":"Unlinked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"unlinked":{"$ref":"#/components/schemas/PartnerLink"},"revoked":{"type":"boolean","description":""}}}}}},"400":{"description":"invalid_source / invalid_external_ref","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"401":{"description":"invalid_partner_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"404":{"description":"not_linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}},"503":{"description":"partner_provisioning_disabled (FLOW_PARTNER_KEY not set on the server)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerError"}}}}}}},"/api/mcp":{"x-flow-route":"src/pages/api/mcp.js","post":{"operationId":"mcpJsonRpc","tags":["MCP"],"summary":"MCP server (stateless streamable HTTP, JSON-RPC 2.0)","description":"Methods: `initialize`, `ping`, `tools/list`, `tools/call`. Notifications (no id) answer 202 with no body. Batches (arrays) are supported.\nLive tool catalog without auth: https://flow.txi.co.il/api/mcp-tools.json. A scoped (extra) key sees only its allow-listed tools; a draft-only key cannot publish social posts.\nTool results come back as `content[0].text` = pretty JSON; tool failures as `isError: true` with the error text.\nEvery tools/call is audited per tenant (see the get_mcp_audit tool). Request body limit 36 MB (upload_media sends base64).","security":[{"mcpKey":[]},{"mcpHeaders":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","integer"]},"method":{"type":"string","description":"","enum":["initialize","ping","tools/list","tools/call"]},"params":{"type":"object"}},"required":["jsonrpc","method"]},"examples":{"list":{"value":{"jsonrpc":"2.0","id":1,"method":"tools/list"}},"call":{"value":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_flows","arguments":{}}}}}}}},"responses":{"200":{"description":"JSON-RPC response (also used for -32603 internal errors).","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{ \"flows\": [ … ] }"}]}}}}},"202":{"description":"Notification accepted (no body)."},"400":{"description":"Parse error (-32700).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Unauthorized (-32001). WWW-Authenticate: Bearer realm=\"aiflow-mcp\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"405":{"description":"Only POST (-32600).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"429":{"description":"Rate limited (-32002).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}},"x-flow-notes":["Rate limit: 60 requests per minute per tenant by default (server env MCP_RATE_LIMIT_PER_MIN). initialize, ping, tools/list, resources/list, prompts/list and notifications/* do not count; a batch counts once if it holds any other call. 429 carries Retry-After.","The handler's header comment still describes the retired 3-factor, read-only phase."]}},"/api/mcp-tools.json":{"x-flow-route":"src/pages/api/mcp-tools.json.js","get":{"operationId":"listMcpTools","tags":["MCP"],"summary":"Public catalog of every MCP tool (name, group, description, input schema)","security":[],"responses":{"200":{"description":"Catalog generated from the running server's tool registry.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"endpoint":{"type":"string","description":""},"count":{"type":"integer","description":""},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":""},"group":{"type":"string","description":""},"description":{"type":"string","description":""},"inputSchema":{"type":"object"}}}}}}}}}}}},"/api/openapi.json":{"x-flow-route":"src/pages/api/openapi.json.js","get":{"operationId":"getOpenApiSpec","tags":["Meta"],"summary":"This OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON (CORS open, cached 1h).","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/embed/verify-key":{"x-flow-route":"src/pages/api/embed/verify-key.js","post":{"operationId":"embedVerifyKey","tags":["Embed widget"],"summary":"Check a site key (plugin \"test connection\"). Origin is not enforced. 60/min.","security":[{"embedSiteKey":[]},{"embedSiteKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteKey":{"type":"string","description":"Public site key from /settings/embed or partner provision (may also be sent as ?siteKey= or the X-AIFLOW-SiteKey header)."},"host":{"type":"string","description":"Informational."}},"required":["siteKey"]}}}},"responses":{"200":{"description":"Valid.","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","enum":[true]},"displayName":{"type":"string","description":""},"mode":{"type":"string","description":""},"primaryColor":{"type":"string","description":""},"locale":{"type":"string","description":""}}}}}},"400":{"description":"missing_site_key / bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"origin_not_allowed — the request Origin is not in the site's allowed origins.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"site_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"405":{"description":"method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"rate_limited (per siteKey + IP, per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/embed/session":{"x-flow-route":"src/pages/api/embed/session.js","post":{"operationId":"embedSession","tags":["Embed widget"],"summary":"Create or resume a widget session. 120/min.","security":[{"embedSiteKey":[]},{"embedSiteKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteKey":{"type":"string","description":"Public site key from /settings/embed or partner provision (may also be sent as ?siteKey= or the X-AIFLOW-SiteKey header)."},"sessionId":{"type":"string","description":"Resume this session (must belong to the site)."}},"required":["siteKey"]}}}},"responses":{"200":{"description":"Session + widget appearance.","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":""},"openingMessage":{"type":"string","description":""},"locale":{"type":"string","description":""},"primaryColor":{"type":"string","description":""},"mode":{"type":"string","description":"chatbot / search / form"},"position":{"type":"string","description":""},"theme":{"type":"string","description":""},"appearance":{"type":"object"},"displayName":{"type":"string","description":""}}}}}},"400":{"description":"missing_site_key / bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"origin_not_allowed — the request Origin is not in the site's allowed origins.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"site_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"405":{"description":"method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"rate_limited (per siteKey + IP, per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/embed/chat":{"x-flow-route":"src/pages/api/embed/chat.js","post":{"operationId":"embedChat","tags":["Embed widget"],"summary":"One chat turn. Runs the site's flow, or knowledge-base RAG when no flow is attached. 30/min.","security":[{"embedSiteKey":[]},{"embedSiteKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteKey":{"type":"string","description":"Public site key from /settings/embed or partner provision (may also be sent as ?siteKey= or the X-AIFLOW-SiteKey header)."},"sessionId":{"type":"string","description":""},"message":{"type":"string","description":"≤4000 chars."},"customerName":{"type":"string","description":""}},"required":["siteKey","message"]}}}},"responses":{"200":{"description":"Reply. Flow sites add menu/ended/handover/media fields; RAG sites return sources.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"string","description":""},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":""},"title":{"type":"string","description":""}}}},"menu":{"type":["array","null"]},"menuDisplayType":{"type":["string","null"]},"headerText":{"type":["string","null"]},"ended":{"type":"boolean","description":""},"handover":{"type":"boolean","description":""},"mediaUrl":{"type":"string","description":""},"mediaType":{"type":"string","description":""},"conversationId":{"type":"string","description":""}}}}}},"400":{"description":"missing_site_key / bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"origin_not_allowed / session_mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"site_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"405":{"description":"method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"rate_limited (per siteKey + IP, per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/embed/search":{"x-flow-route":"src/pages/api/embed/search.js","post":{"operationId":"embedSearch","tags":["Embed widget"],"summary":"Semantic search over the site's knowledge base. 60/min.","security":[{"embedSiteKey":[]},{"embedSiteKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteKey":{"type":"string","description":"Public site key from /settings/embed or partner provision (may also be sent as ?siteKey= or the X-AIFLOW-SiteKey header)."},"query":{"type":"string","description":"Short queries return [] without cost."}},"required":["siteKey","query"]}}}},"responses":{"200":{"description":"Results (empty on any internal failure).","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":""},"excerpt":{"type":"string","description":""},"url":{"type":"string","description":""},"similarity":{"type":"number"}}}}}}}}},"400":{"description":"missing_site_key / bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"origin_not_allowed — the request Origin is not in the site's allowed origins.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"site_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"405":{"description":"method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"rate_limited (per siteKey + IP, per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}}}},"/api/embed/form":{"x-flow-route":"src/pages/api/embed/form.js","post":{"operationId":"embedForm","tags":["Embed widget"],"summary":"Contact-form submission from the widget. 10/min.","security":[{"embedSiteKey":[]},{"embedSiteKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteKey":{"type":"string","description":"Public site key from /settings/embed or partner provision (may also be sent as ?siteKey= or the X-AIFLOW-SiteKey header)."},"sessionId":{"type":"string","description":""},"formData":{"type":"object","properties":{"name":{"type":"string","description":""},"email":{"type":"string","description":""},"phone":{"type":"string","description":""},"message":{"type":"string","description":""}},"additionalProperties":true,"description":"name + message + (email or phone ≥6 chars) required; ≤30 fields."}},"required":["siteKey","formData"]}}}},"responses":{"200":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}}}}}},"400":{"description":"missing_site_key / bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"403":{"description":"origin_not_allowed — the request Origin is not in the site's allowed origins.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"404":{"description":"site_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"405":{"description":"method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"429":{"description":"rate_limited (per siteKey + IP, per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}},"500":{"description":"internal_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainError"}}}}},"x-flow-notes":["Stored as a Lead of the site's tenant (source embed_form), keyed by the phone (E.164) or, without one, the email. The text and any consent fields (consent / agree / marketing / privacy / terms …) are appended to the lead notes; a phone also creates the contact when missing.","With a sessionId whose widget chat already has a conversation, the submission is logged there as an incoming message.","Emits embed.form_submitted, plus lead.created / lead.updated.","Spam guard: a filled _hp / _gotcha honeypot is answered ok and dropped; the same contact + message on the same site within 10 minutes is stored once (per server process).","phone must be 9–15 digits (local 05x is converted to 972…) and email a valid address; otherwise 400 missing_required_fields."]}}},"webhooks":{"conversation.created":{"post":{"operationId":"webhook_conversation_created","tags":["Reporting webhooks"],"summary":"conversation.created","description":"A flow started for a customer (log action flow_started).\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.created"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.message_received":{"post":{"operationId":"webhook_conversation_message_received","tags":["Reporting webhooks"],"summary":"conversation.message_received","description":"Inbound customer message. The richest event: with \"include channels\" it also carries availableChannels + _sendApi.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.message_received"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.message_sent":{"post":{"operationId":"webhook_conversation_message_sent","tags":["Reporting webhooks"],"summary":"conversation.message_sent","description":"Outbound message logged (bot, operator, API).\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.message_sent"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.ai_response":{"post":{"operationId":"webhook_conversation_ai_response","tags":["Reporting webhooks"],"summary":"conversation.ai_response","description":"AI node answered.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.ai_response"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.agent_requested":{"post":{"operationId":"webhook_conversation_agent_requested","tags":["Reporting webhooks"],"summary":"conversation.agent_requested","description":"Customer asked for a human.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.agent_requested"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.flow_completed":{"post":{"operationId":"webhook_conversation_flow_completed","tags":["Reporting webhooks"],"summary":"conversation.flow_completed","description":"Flow reached its end — also fired by the idle worker together with conversation.abandoned.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.flow_completed"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.flow_paused":{"post":{"operationId":"webhook_conversation_flow_paused","tags":["Reporting webhooks"],"summary":"conversation.flow_paused","description":"Flow paused / failed.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.flow_paused"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportingEvent"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationEventData"}}}]}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.abandoned":{"post":{"operationId":"webhook_conversation_abandoned","tags":["Reporting webhooks"],"summary":"conversation.abandoned","description":"Customer stopped answering (idle worker).\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.abandoned"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"conversation.operator_action":{"post":{"operationId":"webhook_conversation_operator_action","tags":["Reporting webhooks"],"summary":"conversation.operator_action","description":"Operator released / marked spam / marked handled. data: { conversationId, kind, by, byUserId, … }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.operator_action"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"group.mention":{"post":{"operationId":"webhook_group_mention","tags":["Reporting webhooks"],"summary":"group.mention","description":"A desktop-line WhatsApp group addressed the line (mention, reply, keyword). data: { conversationId, groupId, groupName, line, sender, message, messageType, messageId }. Reply with replyToMessageId.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"group.mention"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"message.sent":{"post":{"operationId":"webhook_message_sent","tags":["Reporting webhooks"],"summary":"message.sent","description":"/api/external/send succeeded. data: { requestId, channel, to, type, sentAt, messageId, … }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"message.sent"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"message.failed":{"post":{"operationId":"webhook_message_failed","tags":["Reporting webhooks"],"summary":"message.failed","description":"/api/external/send failed. data: { requestId, channel, to, type, reason, error }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"message.failed"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"lead.created":{"post":{"operationId":"webhook_lead_created","tags":["Reporting webhooks"],"summary":"lead.created","description":"A lead row was created (new customer conversation, API lead trigger, embed form, operator). Bulk imports do not emit. data: { leadId, phone, status, secondarySource, source, createdAt, updatedAt }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"lead.created"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"lead.updated":{"post":{"operationId":"webhook_lead_updated","tags":["Reporting webhooks"],"summary":"lead.updated","description":"A lead was written again (status, notes, secondary source). Same data plus previousStatus.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"lead.updated"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"lead.status_changed":{"post":{"operationId":"webhook_lead_status_changed","tags":["Reporting webhooks"],"summary":"lead.status_changed","description":"Sent together with lead.updated when the status changed. data.previousStatus holds the old value.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"lead.status_changed"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"embed.form_submitted":{"post":{"operationId":"webhook_embed_form_submitted","tags":["Reporting webhooks"],"summary":"embed.form_submitted","description":"Website widget contact form. data: { siteKey, siteName, leadId, conversationId, name, phone, email, message, consent, fields, submittedAt }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"embed.form_submitted"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"social.post_published":{"post":{"operationId":"webhook_social_post_published","tags":["Reporting webhooks"],"summary":"social.post_published","description":"Facebook / Instagram post went live. data: { postId, targetId, platform, accountId, accountName, format, seriesId, … }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"social.post_published"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"social.post_failed":{"post":{"operationId":"webhook_social_post_failed","tags":["Reporting webhooks"],"summary":"social.post_failed","description":"Publishing failed. Same data as social.post_published plus the error.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"social.post_failed"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"facebook.lead_received":{"post":{"operationId":"webhook_facebook_lead_received","tags":["Reporting webhooks"],"summary":"facebook.lead_received","description":"Facebook / Instagram lead form submission. data: { leadgenId, pageId, pageName, formId, createdAt, fields }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"facebook.lead_received"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"outbound.duplicate_burst_blocked":{"post":{"operationId":"webhook_outbound_duplicate_burst_blocked","tags":["Reporting webhooks"],"summary":"outbound.duplicate_burst_blocked","description":"The same message to one customer was blocked as a burst. data: { phone, flowId, flowName, count, threshold, windowMinutes }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"outbound.duplicate_burst_blocked"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}},"billing.charge.notified":{"post":{"operationId":"webhook_billing_charge_notified","tags":["Reporting webhooks"],"summary":"billing.charge.notified","description":"A WhatsApp charge notice went out. data: { chargeId, billingPeriod, amountIls, channels, … }.\n\nHeaders: X-AIFLOW-Event, X-AIFLOW-Delivery (= body.id), X-AIFLOW-Timestamp, X-AIFLOW-Signature (when a secret is set), User-Agent AIFLOW-Webhook/1.0.","parameters":[{"name":"X-AIFLOW-Event","in":"header","required":true,"schema":{"type":"string","const":"billing.charge.notified"}},{"name":"X-AIFLOW-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-AIFLOW-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of THIS attempt."},{"name":"X-AIFLOW-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"standard: sha256=<hex HMAC-SHA256(secret, rawBody)>. strict: t=<ts>,v1=<hex HMAC-SHA256(secret, ts + \".\" + rawBody)> — reject when |now − t| > 300 s."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingEvent"}}}},"responses":{"2XX":{"description":"Acknowledge within 10 s. Any other status or a timeout is retried."}}}}},"components":{"securitySchemes":{"externalApiKey":{"type":"http","scheme":"bearer","description":"Tenant external API key (64 hex chars): `Authorization: Bearer <key>`."},"externalApiKeyQuery":{"type":"apiKey","in":"query","name":"apiKey","description":"Same key as ?apiKey= (or `apiKey` in the JSON body). Discouraged — ends up in logs."},"outboundToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API JWT from /api/auth/api-token, or the flow's own outbound token (outboundApiToken in the flow description / deterministic per-flow token)."},"partnerKey":{"type":"http","scheme":"bearer","description":"Shared partner key (FLOW_PARTNER_KEY)."},"mcpKey":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <username>:<mcp_key>` (a legacy username:password:key form is accepted; the password is ignored). Extra scoped keys work the same way."},"mcpHeaders":{"type":"apiKey","in":"header","name":"x-mcp-key","description":"Alternative: x-mcp-username + x-mcp-key headers."},"embedSiteKey":{"type":"apiKey","in":"query","name":"siteKey","description":"Public embed site key (normally in the JSON body as `siteKey`)."},"embedSiteKeyHeader":{"type":"apiKey","in":"header","name":"X-AIFLOW-SiteKey"},"leadTriggerAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Whatever the flow's API-lead node configures: api_key header (name configurable), Basic, Bearer or HMAC-SHA256 (X-Signature-256)."},"externalStreamToken":{"type":"apiKey","in":"header","name":"x-webhook-token","description":"Only when the server sets EXTERNAL_WEBHOOK_TOKEN; also ?token=."}},"schemas":{"ExternalError":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Machine-readable error code or message. Codes are snake_case where the handler sets one."},"message":{"type":"string","description":"Human detail, when present."},"hint":{"type":"string","description":"What to do next, when present."},"docs":{"type":"string","description":"Link to the docs.","format":"uri"}},"required":["ok","error"]},"PlainError":{"type":"object","properties":{"error":{"type":"string","description":"Error message."}},"required":["error"],"description":"Error shape of the older trigger endpoints (/api/webhook/*, /api/auth/api-token, /api/embed/*)."},"PartnerError":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"snake_case error code."},"hint":{"type":"string","description":"Present on partner_provisioning_disabled."},"link":{"$ref":"#/components/schemas/PartnerLink"},"candidates":{"type":"array","items":{"type":"object"},"description":"On possible_duplicate_tenant: tenants that resemble the request."},"attachExample":{"type":"object","description":"On possible_duplicate_tenant: a body fragment to attach to the first candidate."}},"required":["ok","error"]},"JsonRpcError":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","integer","null"]},"error":{"type":"object","properties":{"code":{"type":"integer","description":"-32001 unauthorized, -32002 rate limited, -32600 bad method, -32601 unknown method, -32700 parse error, -32603 internal."},"message":{"type":"string","description":""}}}}},"SendRequest":{"type":"object","properties":{"channel":{"type":"string","description":"Channel family. Omit and pass `instanceId` for legacy WhatsApp-personal sends. Dashes are accepted (whatsapp-green).","enum":["whatsapp_green","whatsapp_official","messenger","instagram","telegram","email"]},"to":{"type":"string","description":"Recipient. E.164 digits for WhatsApp/Telegram (0-prefixed Israeli numbers are converted to 972), email address for email, PSID for Messenger, IGSID for Instagram, chat id for Telegram. Required except for messenger/instagram when psid/igsid is given."},"type":{"type":"string","description":"Message type. WhatsApp official accepts only `template`; Messenger/Instagram reject `template`.","enum":["text","image","video","document","template"],"default":"text"},"text":{"type":"string","description":"Body, or caption for media. Required for type=text (except Messenger/Instagram, where it is not checked)."},"mediaUrl":{"type":"string","description":"Public HTTPS URL. Required for image/video/document on WhatsApp personal and Telegram.","format":"uri"},"fileName":{"type":"string","description":"Display file name for documents (WhatsApp personal)."},"instanceId":{"type":"string","description":"whatsapp_green: the line id (GreenApiWhatsappInstance.id UUID — NOT the numeric idInstance). Desktop lines from GET /api/external/desktop-lines use their `id` here too."},"templateName":{"type":"string","description":"type=template. whatsapp_green: a personal template name (GET /api/external/templates). whatsapp_official: an APPROVED Meta template name (GET /api/external/wa-templates)."},"templateLanguage":{"type":"string","description":"whatsapp_official template language.","default":"he"},"templateParams":{"description":"whatsapp_official: either a flat array of body values ([\"Dana\",\"10:30\"]) — wrapped into one body component — or a ready Meta `components` array.","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object"}}]},"phoneNumberId":{"type":"string","description":"whatsapp_official: pick a line when the tenant has more than one active Cloud line (required in that case)."},"psid":{"type":"string","description":"messenger: recipient PSID (alias of `to`)."},"pageId":{"type":"string","description":"messenger: pick a Facebook Page config."},"igsid":{"type":"string","description":"instagram: recipient IGSID (alias of `to`)."},"igAccountId":{"type":"string","description":"instagram: pick an Instagram account config."},"chatId":{"type":"string","description":"telegram: chat id (alias of `to`)."},"configId":{"type":"string","description":"telegram: bot config id (optional). email: EmailConfig.id (required)."},"emailSubject":{"type":"string","description":"email subject.","default":"(no subject)"},"emailThreadId":{"type":"string","description":"email: thread to reply in."},"conversationId":{"type":"string","description":"Log the send into this conversation (must be the tenant's and the same recipient; otherwise ignored, see conversationIdIgnored)."},"system":{"type":"boolean","description":"Informational notice (hours, overload). Logged with authorType system; does not claim the thread or pause the bot (only whatsapp_green ever claims).","default":false},"senderName":{"type":"string","description":"Shown as the author of a system notice (max 120 chars)."},"apiKey":{"type":"string","description":"Discouraged: the API key in the body instead of the Authorization header."}}},"SendResult":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"requestId":{"type":"string","description":"UUID on every post-auth response. Matches `data.requestId` on the message.sent / message.failed webhook.","format":"uuid"},"status":{"type":"string","description":"","enum":["sent","failed","invalid_params","config_error","provider_error","instance_warming","instance_flagged_low_delivery","instance_requires_warmup"]},"error":{"type":"string","description":"Present when ok=false."},"messageId":{"type":"string","description":"Provider message id (WhatsApp wamid / Green idMessage / Telegram message_id). Messenger/Instagram fall back to a random UUID when the provider returns none."},"channel":{"type":"string","description":"Channel the message went out on. For whatsapp_green this is the raw conversation channel `whatsapp_unofficial:<idInstance>`."},"instancePhone":{"type":"string","description":"whatsapp_green: the sending line number."},"templateName":{"type":"string","description":""},"templateLanguage":{"type":"string","description":""},"phoneNumberId":{"type":"string","description":""},"pageId":{"type":"string","description":""},"igAccountId":{"type":"string","description":""},"chatId":{"type":"string","description":""},"botUsername":{"type":"string","description":""},"emailTo":{"type":"string","description":""},"emailSubject":{"type":"string","description":""},"conversationId":{"type":"string","description":"Conversation the send was logged into (every channel)."},"conversationIdIgnored":{"type":"string","description":"Set when the body's conversationId was not used.","enum":["not_found","recipient_mismatch"]},"docs":{"type":"string","description":"","format":"uri"}},"required":["ok","requestId","status"]},"ConversationSummary":{"type":"object","properties":{"id":{"type":"string","description":"Conversation id."},"channel":{"type":"string","description":"Raw channel string: whatsapp, whatsapp_unofficial:<idInstance>, messenger:<pageId>, instagram:<igId>, email:<configId>, telegram, fb_comment:…, ig_comment:…, embed:…"},"status":{"type":"string","description":"","enum":["active","completed","abandoned","error"]},"waPhoneNumber":{"type":"string","description":"Customer identifier (E.164 digits, a group jid ending @g.us, PSID, …)."},"customerName":{"type":"string","description":""},"lastMessage":{"type":"string","description":""},"lastCustomerMessageAt":{"type":["string","null"],"format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isFavorite":{"type":"boolean","description":""},"needsHandling":{"type":"boolean","description":"Waiting for an agent."},"hasSpam":{"type":"boolean","description":""}}},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Log row id."},"waMessageId":{"type":"string","description":"Provider message id, when known."},"action":{"type":"string","description":"message_received, message_sent, ai_response, flow_started, …"},"direction":{"type":"string","description":"inbound / outbound. NOTE: older rows and /api/external/send rows use incoming / outgoing."},"channel":{"type":"string","description":""},"type":{"type":"string","description":"text, image, video, document, audio, template, …"},"text":{"type":"string","description":""},"mediaUrl":{"type":"string","description":""},"fileName":{"type":"string","description":""},"templateName":{"type":"string","description":""},"templateCategory":{"type":"string","description":""},"sentBy":{"type":"string","description":"external_api, system, bot, an operator id, …"},"deliveryStatus":{"type":"string","description":"sent / delivered / read / failed, when tracked."},"spam":{"type":["object","null"]},"timestamp":{"type":"string","format":"date-time"}}},"ReplyRequest":{"type":"object","properties":{"type":{"type":"string","description":"","enum":["text","image","video","document","template"],"default":"text"},"text":{"type":"string","description":"Required for type=text; caption for media."},"mediaUrl":{"type":"string","description":"Required for image/video/document.","format":"uri"},"fileName":{"type":"string","description":"Document display name."},"templateName":{"type":"string","description":"type=template (WhatsApp official only)."},"templateLanguage":{"type":"string","description":"","default":"he"},"templateParams":{"type":"array","description":"Flat values or Meta components (see SendRequest)."},"system":{"type":"boolean","description":"Informational notice: no claim, no bot pause, \"waiting for agent\" kept.","default":false},"senderName":{"type":"string","description":"Author shown for a system notice."},"agentName":{"type":"string","description":"Real human agent name shown as the thread handler (instead of the API account)."},"agentId":{"type":"string","description":"Stable agent id; the claim marker becomes external_api:<agentId>."},"replyToMessageId":{"type":"string","description":"WhatsApp personal / desktop lines: quote this message id (e.g. the one a group.mention named)."},"replyMode":{"type":"string","description":"fb_comment / ig_comment conversations: public reply under the comment, or the one private DM Meta allows per comment (7 days).","enum":["public","private"],"default":"public"}}},"ReplyResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"messageId":{"type":"string","description":""},"channel":{"type":"string","description":""},"type":{"type":"string","description":""},"instancePhone":{"type":"string","description":"WhatsApp personal only."},"templateName":{"type":"string","description":""},"templateLanguage":{"type":"string","description":""},"replyMode":{"type":"string","description":"Comment threads only."}}},"QuickReply":{"type":"object","properties":{"id":{"type":"string","description":""},"trigger":{"type":"string","description":"The \"/\" shortcut."},"text":{"type":"string","description":""},"mediaType":{"type":"string","description":"Empty for text replies."},"mediaUrl":{"type":"string","description":""},"mediaName":{"type":"string","description":""},"sortOrder":{"type":"integer","description":""}}},"PersonalTemplate":{"type":"object","properties":{"id":{"type":"string","description":""},"name":{"type":"string","description":"Pass as templateName to /api/external/send (whatsapp_green)."},"category":{"type":"string","description":"Group label."},"body":{"type":"string","description":"May contain #variable# tokens (e.g. #שם_לקוח#, #R# = line break). /api/external/send renders only phone; substitute others yourself and send as text."},"mediaType":{"type":"string","description":""},"mediaUrl":{"type":"string","description":""},"mediaName":{"type":"string","description":""},"variables":{"type":"array","items":{}},"sortOrder":{"type":"integer","description":""}}},"WaTemplateLine":{"type":"object","properties":{"phoneNumberId":{"type":"string","description":""},"displayPhoneName":{"type":"string","description":""},"error":{"type":"string","description":"graph_unreachable when Meta could not be reached for this line."},"templates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":""},"status":{"type":"string","description":"APPROVED, PENDING, REJECTED, PAUSED, …"},"category":{"type":"string","description":""},"language":{"type":"string","description":""},"bodyText":{"type":"string","description":""},"paramCount":{"type":"integer","description":"Number of {{n}} placeholders in the body."},"buttons":{"type":"array","items":{"type":"string"}}}}}}},"DesktopLine":{"type":"object","properties":{"id":{"type":"string","description":"Use as instanceId on /api/external/send and lineId on the desktop-lines endpoints."},"provider":{"type":"string","description":"","enum":["desktop"]},"name":{"type":"string","description":""},"idInstance":{"type":"string","description":""},"phoneNumber":{"type":"string","description":""},"accountName":{"type":"string","description":""},"state":{"type":"string","description":"authorized / notAuthorized / …"},"whatsappStatus":{"type":"string","description":""},"isActive":{"type":"boolean","description":""},"device":{"type":"object","properties":{"online":{"type":"boolean","description":""},"lastSeenAt":{"type":["string","null"]},"name":{"type":"string","description":""},"platform":{"type":"string","description":""},"appVersion":{"type":"string","description":""},"wwebjsVersion":{"type":"string","description":""},"employeeId":{"type":"string","description":""},"pinnedToComputer":{"type":"boolean","description":""},"disabled":{"type":"boolean","description":""}}},"qrPending":{"type":"boolean","description":""}}},"PartnerLink":{"type":"object","properties":{"source":{"type":"string","description":""},"externalRef":{"type":"string","description":""},"userId":{"type":"string","description":""},"linkedAt":{"type":"string","format":"date-time"}}},"ProvisionRequest":{"type":"object","properties":{"projectName":{"type":"string","description":"Tenant display name. Required for mode=new."},"mode":{"type":"string","description":"","enum":["new","attach"],"default":"new"},"existingUserId":{"type":"string","description":"Required for mode=attach."},"email":{"type":"string","description":"Owner email (optional)."},"confirmNew":{"type":"boolean","description":"Create even when a similar tenant exists (otherwise 409 possible_duplicate_tenant)."},"source":{"type":"string","description":"One-to-one link: partner system name, ^[a-z][a-z0-9_-]{1,39}$ (e.g. parsi)."},"externalRef":{"type":"string","description":"One-to-one link: the record id in that system (≤191 chars). Same pair → same tenant, always."},"connectTtlMinutes":{"type":"integer","description":"Lifetime of the connect link.","default":10080},"want":{"type":"object","properties":{"apiKey":{"type":"boolean","description":"","default":true},"connectLink":{"type":"boolean","description":"","default":true},"embed":{"type":"boolean","description":"","default":true},"mcp":{"type":"boolean","description":"","default":true},"regenerateApiKey":{"type":"boolean","description":"Rotate the external API key (old one stops working).","default":false},"regenerateMcpKey":{"type":"boolean","description":"Rotate the MCP key (old one stops working).","default":false},"newEmbed":{"type":"boolean","description":"Create another embed site instead of reusing the first.","default":false}}},"store":{"type":"object","properties":{"host":{"type":"string","description":"Store host, e.g. shop.example.com (checked against the key's store)."},"apiKey":{"type":"string","description":"PARSI site key (pmk_…) with site:catalog + site:orders:create. Validated live, stored encrypted, never returned."}},"description":"PARSI store for WhatsApp store mode (one tenant per store)."}}},"ProvisionResult":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"tenant":{"type":"object","properties":{"userId":{"type":"string","description":""},"username":{"type":"string","description":""},"displayName":{"type":"string","description":""}}},"link":{"$ref":"#/components/schemas/PartnerLink"},"endpoints":{"type":"object","properties":{"outbound":{"type":"string","description":""},"externalSend":{"type":"string","description":""},"reply":{"type":"string","description":""},"quickReplies":{"type":"string","description":""},"docs":{"type":"string","description":""},"developers":{"type":"string","description":""},"openapi":{"type":"string","description":""},"mcp":{"type":"string","description":""}}},"apiKey":{"type":"string","description":"External API key (64 hex). Returned every call; an existing key is returned as-is."},"connectUrl":{"type":"string","description":"Login-free WhatsApp/Facebook connect link for the owner.","format":"uri"},"connectExpiresAt":{"type":"string","format":"date-time"},"connectWarning":{"type":"string","description":""},"embed":{"type":"object","properties":{"siteKey":{"type":"string","description":""},"widgetScript":{"type":"string","description":"Ready <script> tag."},"manage":{"type":"string","description":""}}},"embedWarning":{"type":"string","description":""},"mcp":{"type":"object","properties":{"endpoint":{"type":"string","description":""},"username":{"type":"string","description":""},"key":{"type":"string","description":"Returned ONCE when minted (only a salted hash is stored). Absent when an existing key was kept."},"keyPrefix":{"type":"string","description":""},"authHeader":{"type":"string","description":""},"transport":{"type":"string","description":""},"tools":{"type":"string","description":""},"existing":{"type":"boolean","description":"true when the tenant already had a key and it was kept."},"hint":{"type":"string","description":""}}},"mcpWarning":{"type":"string","description":""},"store":{"type":"object","properties":{"ok":{"type":"boolean","description":""},"error":{"type":"string","description":"","enum":["store_apiKey_required","store_key_rejected","store_host_mismatch","store_site_mismatch"]},"connectionId":{"type":"string","description":""},"host":{"type":"string","description":""},"siteId":{"type":"string","description":""},"storeName":{"type":"string","description":""},"demo":{"type":"boolean","description":""},"testMode":{"type":"boolean","description":""},"enabled":{"type":"boolean","description":""},"phoneNumberId":{"type":"string","description":""},"next":{"type":"string","description":""},"status":{"type":"integer","description":"store_key_rejected: PARSI HTTP status."},"detail":{"type":"string","description":""},"keyStoreUrl":{"type":"string","description":""},"keySiteId":{"type":"string","description":""}},"description":"Only when `store` was sent. A store failure does not fail the provision (HTTP stays 200)."}}},"ReportingEvent":{"type":"object","properties":{"id":{"type":"string","description":"Unique event id (same as the X-AIFLOW-Delivery header). Retries of one event reuse it — dedupe on it.","format":"uuid"},"event":{"type":"string","description":"Event name."},"createdAt":{"type":"string","format":"date-time"},"userId":{"type":"string","description":"Tenant id."},"platform":{"$ref":"#/components/schemas/EventPlatform"},"data":{"type":"object","description":"Event-specific payload."}},"required":["id","event","createdAt","userId","platform","data"]},"EventPlatform":{"type":"object","properties":{"type":{"type":"string","description":"","enum":["whatsapp_official","whatsapp_green","messenger","instagram","email","telegram","tiktok","unknown"]},"channelString":{"type":"string","description":"Raw conversation channel (lower-cased)."},"displayLabel":{"type":"string","description":""},"icon":{"type":"string","description":""},"customerPhone":{"type":"string","description":""},"customerEmail":{"type":"string","description":""},"customerName":{"type":"string","description":""},"phoneNumberId":{"type":"string","description":""},"businessPhoneNumber":{"type":"string","description":""},"idInstance":{"type":"string","description":""},"instanceId":{"type":"string","description":""},"instancePhone":{"type":"string","description":""},"pageId":{"type":"string","description":""},"igAccountId":{"type":"string","description":""},"emailConfigId":{"type":"string","description":""},"emailAddress":{"type":"string","description":""},"emailSubject":{"type":"string","description":""},"emailThreadId":{"type":"string","description":""},"botUsername":{"type":"string","description":""},"telegramChatId":{"type":"string","description":""},"replyEndpoint":{"type":"object","properties":{"url":{"type":"string","description":"https://flow.txi.co.il/api/external/conversations/{conversationId}/reply — or /{leadId}/reply when the webhook has \"stable reply handle\" on.","format":"uri"},"method":{"type":"string","description":"","enum":["POST"]},"auth":{"type":"string","description":""},"docsUrl":{"type":"string","description":""}},"description":"Only when the event has a conversationId."}},"description":"Always present: the channel this specific event belongs to."},"ConversationEventData":{"type":"object","properties":{"conversationId":{"type":"string","description":""},"flowId":{"type":"string","description":""},"phone":{"type":"string","description":""},"customerName":{"type":"string","description":""},"channel":{"type":"string","description":""},"status":{"type":"string","description":""},"currentNodeId":{"type":["string","null"]},"action":{"type":"string","description":"Log action that produced the event."},"direction":{"type":["string","null"],"description":"As stored on the log row: mostly incoming/outgoing; some older writers stored inbound/outbound. The external read API normalises to incoming/outgoing."},"nodeId":{"type":["string","null"]},"nodeType":{"type":["string","null"]},"timestamp":{"type":"string","format":"date-time"},"message":{"type":["string","null"]},"messageType":{"type":["string","null"]},"mediaUrl":{"type":["string","null"]},"phoneNumberId":{"type":["string","null"]},"waMessageId":{"type":["string","null"]},"fetchData":{"description":"The FETCH_DATA passthrough given to /api/webhook/outbound when this conversation was started, else null."},"availableChannels":{"type":"array","items":{"type":"object"},"description":"Only on conversation.message_received when the webhook has \"include channels\" on."},"_sendApi":{"type":"object","description":"Only with \"include channels\": endpoint, method, docs and an example body. It carries no credential — authenticate with the API key you already store."}}}},"responses":{"Unauthorized":{"description":"Missing API key / Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"},"example":{"ok":false,"error":"Invalid API key","docs":"https://flow.txi.co.il/docs/external-send-api"}}}},"MethodNotAllowed":{"description":"Wrong HTTP method (Allow header lists the right one).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalError"}}}}}},"x-rate-limits":{"/api/external/send":"100 requests / minute / tenant (per server process)","/api/external/* (other)":"none","/api/webhook/outbound":"50 requests / second / IP","/api/mcp":"60 requests / minute / tenant (MCP_RATE_LIMIT_PER_MIN); setup calls are free","/api/embed/*":"per siteKey+IP per minute: verify-key 60, session 120, chat 30, search 60, form 10"},"x-changelog":[{"date":"2026-11-19","version":"2.0.0","items":["Complete OpenAPI 3.1 spec: every external, partner, MCP, embed and trigger endpoint (was 5 paths).","OpenAPI 3.1 `webhooks` section for all reporting events, with signature modes and retry policy.","New developer portal at /developers and an agent-oriented reference at /llms-full.txt.","Public live MCP tool catalog at /api/mcp-tools.json.","Partner provision no longer returns credentials for a tenant matched only by name (409 tenant_name_taken); duplicate candidates no longer carry userId.","Reporting webhooks: the tenant API key is no longer sent in _sendApi; lead.created / lead.updated / lead.status_changed and embed.form_submitted are emitted; outbound.duplicate_burst_blocked and billing.charge.notified are selectable.","Embed form submissions are stored as leads (source embed_form).","/api/external/send logs every channel to the transcript and honours conversationId.","Conversation list channel filter matches suffixed channels (messenger, instagram_dm, telegram:<id>, …).","Lead trigger HMAC verifies the raw body; a malformed signature answers 401.","Message direction in the external API is always incoming / outgoing.","Quick replies / templates / WA templates answer 500 on server errors.","/unclaim leaves a human operator's claim alone unless force:true (409 claimed_by_human).","MCP rate limit: 60/min/tenant (MCP_RATE_LIMIT_PER_MIN); initialize, tools/list, ping and notifications are free."]},{"date":"2026-11","version":"1.9","items":["Desktop lines: GET /api/external/desktop-lines, POST .../command, POST .../import-groups.","Partner provision accepts `store` (PARSI store mode)."]},{"date":"2026-10","version":"1.8","items":["Partner one-to-one links (`source` + `externalRef`) and GET/DELETE /api/partner/tenant-link."]},{"date":"2026-09","version":"1.7","items":["`system: true` on send/reply: informational notices that do not claim the thread or mute the bot.","POST /api/external/conversations/{id}/unclaim and /unclaim-bulk."]}]}