{"openapi":"3.1.0","info":{"title":"OrcaFlo API","version":"2026-10-01","description":"Public REST API for OrcaFlo workspaces: contacts, conversations, messages, appointments, orders and webhooks. Create keys in the panel under Manage → Developers. Errors: `{ \"error\": { \"type\", \"code\", \"message\", \"param\" } }`. POSTs accept `Idempotency-Key`.","contact":{"name":"OrcaFlo support","email":"support@orcaflo-panel.com","url":"https://orcaflo-panel.com/developers"}},"servers":[{"url":"https://api.orcaflo-panel.com/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Workspace"},{"name":"Contacts"},{"name":"Conversations"},{"name":"Messages"},{"name":"Broadcasts"},{"name":"Appointments"},{"name":"Orders"},{"name":"Products"},{"name":"Webhooks"},{"name":"Incoming webhooks"},{"name":"Custom channels"}],"paths":{"/me":{"get":{"tags":["Workspace"],"summary":"Who am I (test a key)","description":"Scope: `any`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"workspace_id":{"type":"string"},"workspace_name":{"type":"string"},"key_id":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getMe"}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Scope: `contacts:read`.","parameters":[{"name":"phone","in":"query","schema":{"type":"string"},"description":"E.164"},{"name":"email","in":"query","schema":{"type":"string"},"description":""},{"name":"lifecycle","in":"query","schema":{"type":"string"},"description":""},{"name":"tag","in":"query","schema":{"type":"string"},"description":""},{"name":"temperature","in":"query","schema":{"type":"string"},"description":"hot|warm|cold"},{"name":"hubspot_id","in":"query","schema":{"type":"string"},"description":"Contact linked to this HubSpot record"},{"name":"salesforce_id","in":"query","schema":{"type":"string"},"description":"Contact linked to this Salesforce record"},{"name":"updated_since","in":"query","schema":{"type":"string"},"description":"ISO timestamp"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Name or phone search"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getContacts"},"post":{"tags":["Contacts"],"summary":"Create a contact","description":"Scope: `contacts:write`. Add `start_conversation` to queue an AI opener (sent at a safe pace in business hours). 409 if the phone exists.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"notes":{"type":"string"},"lifecycle":{"type":"string","description":"One of GET /lifecycles"},"custom_fields":{"type":"object","additionalProperties":true},"followups_paused":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["phone"],"properties":{"phone":{"type":"string"},"start_conversation":{"type":"object","properties":{"opener":{"type":"string","description":"What the lead asked for"}}}}}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postContacts"}},"/contacts/by-phone/{phone}":{"put":{"tags":["Contacts"],"summary":"Create or update a contact by phone","description":"Scope: `contacts:write`. Empty strings are ignored.","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"notes":{"type":"string"},"lifecycle":{"type":"string","description":"One of GET /lifecycles"},"custom_fields":{"type":"object","additionalProperties":true},"followups_paused":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"putContactsByPhoneByPhone"}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","description":"Scope: `contacts:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getContactsById"},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Scope: `contacts:write`. custom_fields are merged; null removes one.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"notes":{"type":"string"},"lifecycle":{"type":"string","description":"One of GET /lifecycles"},"custom_fields":{"type":"object","additionalProperties":true},"followups_paused":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patchContactsById"},"delete":{"tags":["Contacts"],"summary":"Delete a contact","description":"Scope: `contacts:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"},{"name":"purge_messages","in":"query","schema":{"type":"boolean"},"description":"true also deletes the message history"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactsById"}},"/contacts/{id}/tags":{"post":{"tags":["Contacts"],"summary":"Add tags","description":"Scope: `contacts:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postContactsByIdTags"}},"/contacts/{id}/tags/{tag}":{"delete":{"tags":["Contacts"],"summary":"Remove a tag","description":"Scope: `contacts:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"},{"name":"tag","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactsByIdTagsByTag"}},"/contacts/{id}/lifecycle":{"put":{"tags":["Contacts"],"summary":"Set lifecycle stage","description":"Scope: `contacts:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["lifecycle"],"properties":{"lifecycle":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"putContactsByIdLifecycle"}},"/lifecycles":{"get":{"tags":["Contacts"],"summary":"List lifecycle stages","description":"Scope: `contacts:read`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getLifecycles"}},"/custom-fields":{"get":{"tags":["Contacts"],"summary":"List custom fields","description":"Scope: `contacts:read`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getCustomFields"},"post":{"tags":["Contacts"],"summary":"Create a custom field","description":"Scope: `contacts:write`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"label":{"type":"string"},"type":{"enum":["text","number","date","bool","select"]},"options":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postCustomFields"}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"Scope: `conversations:read`.","parameters":[{"name":"unreplied","in":"query","schema":{"type":"boolean"},"description":"true = customer is waiting"},{"name":"escalated","in":"query","schema":{"type":"boolean"},"description":"true = open escalation"},{"name":"bot_paused","in":"query","schema":{"type":"boolean"},"description":""},{"name":"updated_since","in":"query","schema":{"type":"string"},"description":"ISO timestamp"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getConversations"}},"/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","description":"Scope: `conversations:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getConversationsById"}},"/conversations/{id}/messages":{"get":{"tags":["Conversations"],"summary":"List messages (newest first)","description":"Scope: `messages:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getConversationsByIdMessages"}},"/conversations/{id}/pause-bot":{"post":{"tags":["Conversations"],"summary":"Pause the AI (human takeover)","description":"Scope: `messages:send`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdPauseBot"}},"/conversations/{id}/resume-bot":{"post":{"tags":["Conversations"],"summary":"Resume the AI","description":"Scope: `messages:send`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdResumeBot"}},"/conversations/{id}/resolve":{"post":{"tags":["Conversations"],"summary":"Resolve open escalations","description":"Scope: `messages:send`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdResolve"}},"/messages":{"post":{"tags":["Messages"],"summary":"Send a message","description":"Scope: `messages:send`. Only into conversations where the customer has messaged you (422 `no_prior_conversation` otherwise). 30/min per key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"contact_id":{"type":"string"},"phone":{"type":"string"},"text":{"type":"string","maxLength":4096},"pause_bot":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postMessages"}},"/messages/template":{"post":{"tags":["Messages"],"summary":"Send an approved WhatsApp template","description":"Scope: `messages:send`. Official WhatsApp Business API numbers only (422 `templates_unavailable` otherwise). Works outside the 24-hour window, which is what templates are for. 30/min per key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id","template"],"properties":{"contact_id":{"type":"string"},"template":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"language":{"type":"string","default":"en"},"params":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Values for {{1}}, {{2}}… in order"}}}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string"},"template":{"type":"object"},"text":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postMessagesTemplate"}},"/whatsapp/templates":{"get":{"tags":["Messages"],"summary":"List WhatsApp templates","description":"Scope: `messages:read`. `connected: false` when the business has no official WhatsApp Business API number. Approved only unless `status=any`.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"approved (default), any, pending, rejected"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"body":{"type":"string"},"variables":{"type":"integer"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWhatsappTemplates"}},"/users":{"get":{"tags":["Team inbox"],"summary":"List teammates who can be assigned","description":"Scope: `conversations:read`. Needs the team inbox. No emails.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string"},"online":{"type":"boolean"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getUsers"}},"/teams":{"get":{"tags":["Team inbox"],"summary":"List teams","description":"Scope: `conversations:read`. Needs the team inbox.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTeams"}},"/conversations/{id}/assign":{"post":{"tags":["Team inbox"],"summary":"Assign a conversation","description":"Scope: `conversations:write`. Send `user_id` and/or `team_id`; `null` clears it. Emits conversation.assigned and notifies the teammate.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":["string","null"]},"team_id":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdAssign"}},"/conversations/{id}/close":{"post":{"tags":["Team inbox"],"summary":"Close a conversation","description":"Scope: `conversations:write`. It opens again when the customer writes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","description":"One of the business's close categories"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdClose"}},"/conversations/{id}/reopen":{"post":{"tags":["Team inbox"],"summary":"Reopen a conversation","description":"Scope: `conversations:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postConversationsByIdReopen"}},"/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","description":"Scope: `workflows:read`. `can_start_from_api` is true for published workflows with the \"Inbox shortcut\" or \"Started by another workflow\" trigger.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWorkflows"}},"/workflows/{id}/runs":{"get":{"tags":["Workflows"],"summary":"List runs","description":"Scope: `workflows:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Workflow ID"},{"name":"contact_id","in":"query","schema":{"type":"string"},"description":""},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"1–100, default 25"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWorkflowsByIdRuns"},"post":{"tags":["Workflows"],"summary":"Start a workflow for a contact","description":"Scope: `workflows:run`. Same loop protection as the panel (429 `workflow_rate_limited`).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Workflow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postWorkflowsByIdRuns"}},"/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"List broadcasts","description":"Scope: `broadcasts:read`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getBroadcasts"},"post":{"tags":["Broadcasts"],"summary":"Send a broadcast","description":"Scope: `broadcasts:write`. Audience is limited to contacts who have messaged you; sends are paced.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","text","audience"],"properties":{"name":{"type":"string"},"text":{"type":"string"},"audience":{"type":"object","properties":{"phones":{"type":"array","items":{"type":"string"}},"lifecycle":{"type":"string"},"tag":{"type":"string"},"temperature":{"enum":["hot","warm","cold"]}}}}}}}},"responses":{"201":{"description":"Started","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postBroadcasts"}},"/broadcasts/{id}":{"get":{"tags":["Broadcasts"],"summary":"Get a broadcast","description":"Scope: `broadcasts:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Broadcast ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getBroadcastsById"}},"/appointments":{"get":{"tags":["Appointments"],"summary":"List appointments","description":"Scope: `appointments:read`.","parameters":[{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO"},{"name":"to","in":"query","schema":{"type":"string"},"description":"ISO"},{"name":"status","in":"query","schema":{"type":"string"},"description":""},{"name":"contact_id","in":"query","schema":{"type":"string"},"description":""},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getAppointments"},"post":{"tags":["Appointments"],"summary":"Book an appointment","description":"Scope: `appointments:write`. In staff mode send `service_id` (or the service name as `service`) and optionally `staff_id`; without a staff member the least busy one who is free is picked.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["start_at"],"properties":{"service_id":{"type":"string"},"staff_id":{"type":"string"},"contact_id":{"type":"string"},"phone":{"type":"string"},"start_at":{"type":"string","format":"date-time"},"service":{"type":"string"},"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Booked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postAppointments"}},"/services":{"get":{"tags":["Appointments"],"summary":"List services and staff","description":"Scope: `appointments:read`. `staff_mode: true` when the business books per service and staff member; then availability and booking need a `service_id`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"staff_mode":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"duration_min":{"type":"integer"},"price":{"type":["number","null"]},"currency":{"type":["string","null"]},"staff":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":["string","null"]}}}}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getServices"}},"/appointments/availability":{"get":{"tags":["Appointments"],"summary":"Free slots","description":"Scope: `appointments:read`. For businesses in staff mode (GET /services), pass `service_id` (and optionally `staff_id`); each slot then lists the free `staff_ids`.","parameters":[{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO date"},{"name":"days","in":"query","schema":{"type":"integer"},"description":"1–31"},{"name":"service_id","in":"query","schema":{"type":"string"},"description":"Required in staff mode"},{"name":"staff_id","in":"query","schema":{"type":"string"},"description":"Only this staff member"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getAppointmentsAvailability"}},"/appointments/{id}":{"patch":{"tags":["Appointments"],"summary":"Reschedule or change status","description":"Scope: `appointments:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Appointment ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time"},"status":{"enum":["confirmed","cancelled","completed","no_show"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patchAppointmentsById"}},"/orders":{"get":{"tags":["Orders"],"summary":"List orders","description":"Scope: `orders:read`.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":""},{"name":"contact_id","in":"query","schema":{"type":"string"},"description":""},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":["string","null"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOrders"}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get an order","description":"Scope: `orders:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOrdersById"}},"/products":{"get":{"tags":["Products"],"summary":"List products","description":"Scope: `products:read`.","parameters":[{"name":"include_inactive","in":"query","schema":{"type":"boolean"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getProducts"},"post":{"tags":["Products"],"summary":"Create a product","description":"Scope: `products:write`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","price"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postProducts"}},"/products/{id}":{"patch":{"tags":["Products"],"summary":"Update a product","description":"Scope: `products:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Product ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patchProductsById"}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Scope: `webhooks:manage`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWebhooks"},"post":{"tags":["Webhooks"],"summary":"Subscribe a URL to events","description":"Scope: `webhooks:manage`. Returns the signing `secret` once. This is the REST-hook endpoint Zapier, Make and n8n use.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url","event_types"],"properties":{"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"enum":["*","contact.created","contact.updated","contact.deleted","contact.tag_added","contact.tag_removed","contact.lifecycle_updated","contact.temperature_updated","message.received","message.sent","message.failed","conversation.escalated","conversation.resolved","conversation.bot_paused","conversation.bot_resumed","conversation.opened","conversation.sla_first_response","conversation.sla_resolved","conversation.sla_breached","conversation.closed","conversation.summary_updated","conversation.assigned","contact.merged","contact.unmerged","appointment.booked","appointment.rescheduled","appointment.cancelled","appointment.completed","appointment.no_show","order.created","order.paid","order.cancelled","ad_conversion.sent","broadcast.completed","incoming_webhook.received"]}},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postWebhooks"}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook","description":"Scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWebhooksById"},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","description":"Scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patchWebhooksById"},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteWebhooksById"}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a signed test event","description":"Scope: `webhooks:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postWebhooksByIdTest"}},"/channels":{"get":{"tags":["Custom channels"],"summary":"List custom channels","description":"Scope: `channels:manage`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getChannels"},"post":{"tags":["Custom channels"],"summary":"Create a custom channel","description":"Scope: `channels:manage`. Plug any messaging app into OrcaFlo. Returns the signing `secret` once. OrcaFlo POSTs the AI's replies to `callback_url` as `{ type: \"message.outbound\", id, channel_id, to: { id }, message: { type, text | url, … } }`, signed with `OrcaFlo-Signature` like webhooks; answer 2xx (optionally `{ \"message_id\": \"…\" }`).","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","callback_url"],"properties":{"name":{"type":"string"},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postChannels"}},"/channels/{id}":{"get":{"tags":["Custom channels"],"summary":"Get a custom channel","description":"Scope: `channels:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getChannelsById"},"patch":{"tags":["Custom channels"],"summary":"Rename or change the callback URL","description":"Scope: `channels:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"patchChannelsById"},"delete":{"tags":["Custom channels"],"summary":"Disconnect a custom channel","description":"Scope: `channels:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteChannelsById"}},"/channels/{id}/rotate-secret":{"post":{"tags":["Custom channels"],"summary":"New signing secret","description":"Scope: `channels:manage`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postChannelsByIdRotateSecret"}},"/channels/{id}/inbound":{"post":{"tags":["Custom channels"],"summary":"Deliver a customer message","description":"Scope: `channels:inbound`. Your bridge calls this for every message a customer sends in your app. `message.id` is your id for the message (duplicates are ignored). The AI answers through your callback URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","message"],"properties":{"from":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}},"message":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"kind":{"enum":["image","audio","video","file"]},"mimetype":{"type":"string"},"filename":{"type":"string"},"caption":{"type":"string"}}}}}}}}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"conversation_key":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postChannelsByIdInbound"}},"/events":{"get":{"tags":["Webhooks"],"summary":"Recent events (30 days)","description":"Scope: `webhooks:manage`. Polling fallback; same envelopes as webhooks.","parameters":[{"name":"type","in":"query","schema":{"type":"string"},"description":"comma-separated"},{"name":"after","in":"query","schema":{"type":"string"},"description":"ISO timestamp"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getEvents"}},"/event-types":{"get":{"tags":["Webhooks"],"summary":"Event catalogue","description":"Public.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getEventTypes"}},"/hooks/in/{token}":{"post":{"tags":["Incoming webhooks"],"summary":"Receive data from another tool","description":"Public; the URL token is the secret. JSON, form or text bodies up to 64 KB. Emits incoming_webhook.received.","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Accepted"}},"operationId":"postHooksInByToken"}}},"webhooks":{"contact.created":{"post":{"summary":"contact.created","description":"A new contact was created (first WhatsApp message, lead form, API, panel or Shopify).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.created"}},"example":{"id":"…","type":"contact.created","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"source":"whatsapp_inbound"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.updated":{"post":{"summary":"contact.updated","description":"Contact details changed (name, email, address, notes or custom fields). `changed` lists the fields; `previous` has their old values.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.updated"}},"example":{"id":"…","type":"contact.updated","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"changed":["name"],"previous":{"name":"Sara"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.deleted":{"post":{"summary":"contact.deleted","description":"A contact was deleted.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.deleted"}},"example":{"id":"…","type":"contact.deleted","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.tag_added":{"post":{"summary":"contact.tag_added","description":"A tag was added to a contact.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.tag_added"}},"example":{"id":"…","type":"contact.tag_added","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"tag":"vip"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.tag_removed":{"post":{"summary":"contact.tag_removed","description":"A tag was removed from a contact.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.tag_removed"}},"example":{"id":"…","type":"contact.tag_removed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"tag":"vip"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.lifecycle_updated":{"post":{"summary":"contact.lifecycle_updated","description":"The contact moved to another lifecycle stage.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.lifecycle_updated"}},"example":{"id":"…","type":"contact.lifecycle_updated","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"from":"New Lead","to":"Interested","actor":"bot"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.temperature_updated":{"post":{"summary":"contact.temperature_updated","description":"The AI rated the lead cold, warm or hot.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.temperature_updated"}},"example":{"id":"…","type":"contact.temperature_updated","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"hot","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"from":"warm","to":"hot"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"message.received":{"post":{"summary":"message.received","description":"A customer sent a message.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"message.received"}},"example":{"id":"…","type":"message.received","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"message":{"id":"a3c1d9e0-7b55-4b8e-8f0e-1d2c3b4a5f60","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","conversation_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","channel":"whatsapp","direction":"inbound","sender":"contact","type":"text","text":"Hi, do you have availability this Thursday?","created_at":"2026-10-01T09:14:03.120Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"message.sent":{"post":{"summary":"message.sent","description":"A message was sent to a customer (by the AI, a team member, a follow-up, a broadcast or the API).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"message.sent"}},"example":{"id":"…","type":"message.sent","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"message":{"id":"a3c1d9e0-7b55-4b8e-8f0e-1d2c3b4a5f60","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","conversation_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","channel":"whatsapp","direction":"outbound","sender":"bot","type":"text","text":"Yes! We have 11:00 or 15:30 on Thursday. Which suits you?","created_at":"2026-10-01T09:14:03.120Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"message.failed":{"post":{"summary":"message.failed","description":"A message to a customer could not be delivered.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"message.failed"}},"example":{"id":"…","type":"message.failed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"message":{"id":"a3c1d9e0-7b55-4b8e-8f0e-1d2c3b4a5f60","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","conversation_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","channel":"whatsapp","direction":"outbound","sender":"bot","type":"text","text":"Yes! We have 11:00 or 15:30 on Thursday. Which suits you?","created_at":"2026-10-01T09:14:03.120Z"},"error":"WhatsApp is disconnected"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.escalated":{"post":{"summary":"conversation.escalated","description":"The AI handed the conversation to a human.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.escalated"}},"example":{"id":"…","type":"conversation.escalated","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"escalation":{"id":"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b","tag":"HUMAN","summary":"Customer asks for a discount on a bulk order.","order_note":null,"created_at":"2026-10-01T09:20:00.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.resolved":{"post":{"summary":"conversation.resolved","description":"A team member resolved an escalation.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.resolved"}},"example":{"id":"…","type":"conversation.resolved","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"escalation":{"id":"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b","tag":"HUMAN","summary":"Customer asks for a discount on a bulk order.","order_note":null,"created_at":"2026-10-01T09:20:00.000Z","resolved_at":"2026-10-01T10:00:00.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.bot_paused":{"post":{"summary":"conversation.bot_paused","description":"The AI was paused for this conversation (human takeover).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.bot_paused"}},"example":{"id":"…","type":"conversation.bot_paused","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":true,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"actor":"agent"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.bot_resumed":{"post":{"summary":"conversation.bot_resumed","description":"The AI was switched back on for this conversation.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.bot_resumed"}},"example":{"id":"…","type":"conversation.bot_resumed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"actor":"agent"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.opened":{"post":{"summary":"conversation.opened","description":"A closed or snoozed conversation was reopened by a team member.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.opened"}},"example":{"id":"…","type":"conversation.opened","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","assignee_user_id":null,"team_id":null}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.sla_first_response":{"post":{"summary":"conversation.sla_first_response","description":"A team member first replied after the bot handed over (business minutes; breached = after the target).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.sla_first_response"}},"example":{"id":"…","type":"conversation.sla_first_response","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","assignee_user_id":null},"sla":{"cycle_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","started_at":"2026-10-01T09:00:00.000Z","first_response_due_at":"2026-10-01T09:15:00.000Z","first_response_at":"2026-10-01T09:11:00.000Z","first_response_minutes":11,"breached":false}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.sla_resolved":{"post":{"summary":"conversation.sla_resolved","description":"A handed-over conversation was closed or handed back to the bot.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.sla_resolved"}},"example":{"id":"…","type":"conversation.sla_resolved","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","assignee_user_id":null},"sla":{"cycle_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","started_at":"2026-10-01T09:00:00.000Z","resolved_at":"2026-10-01T10:30:00.000Z","resolution_minutes":90,"reason":"closed","breached":false}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.sla_breached":{"post":{"summary":"conversation.sla_breached","description":"A first-response or resolution target was missed.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.sla_breached"}},"example":{"id":"…","type":"conversation.sla_breached","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","assignee_user_id":null},"sla":{"cycle_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","kind":"first_response","first_response_due_at":"2026-10-01T09:15:00.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.closed":{"post":{"summary":"conversation.closed","description":"A conversation was closed by a team member or auto-closed.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.closed"}},"example":{"id":"…","type":"conversation.closed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","closed_at":"2026-10-01T11:00:00.000Z","closed_by":"5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716","close_category":"Resolved","assignee_user_id":"5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716","team_id":null}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.summary_updated":{"post":{"summary":"conversation.summary_updated","description":"The AI rewrote its running summary of the conversation.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.summary_updated"}},"example":{"id":"…","type":"conversation.summary_updated","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"summary":"Asked about Thursday availability; booked a consultation for 11:00."}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"conversation.assigned":{"post":{"summary":"conversation.assigned","description":"A conversation was assigned (or unassigned) to a team member or team.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"conversation.assigned"}},"example":{"id":"…","type":"conversation.assigned","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversation":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","assignee_user_id":"5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716","team_id":null,"assigned_at":"2026-10-01T09:20:00.000Z"},"previous_assignee_user_id":null}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.merged":{"post":{"summary":"contact.merged","description":"Contacts were merged into one (the others now point to it).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.merged"}},"example":{"id":"…","type":"contact.merged","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11"},"merged_contact_ids":["0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"]}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"contact.unmerged":{"post":{"summary":"contact.unmerged","description":"A merge was undone: the contact is separate again, with the channels it had.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"contact.unmerged"}},"example":{"id":"…","type":"contact.unmerged","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11"},"unmerged_contact_id":"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"appointment.booked":{"post":{"summary":"appointment.booked","description":"An appointment was booked.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"appointment.booked"}},"example":{"id":"…","type":"appointment.booked","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"appointment":{"id":"f1e2d3c4-b5a6-4978-8a6b-5c4d3e2f1a0b","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","service":"Consultation","start_at":"2026-10-02T11:00:00.000Z","end_at":"2026-10-02T11:30:00.000Z","status":"booked","source":"bot","external":null,"notes":null,"created_at":"2026-10-01T09:15:10.000Z","updated_at":"2026-10-01T09:15:10.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"appointment.rescheduled":{"post":{"summary":"appointment.rescheduled","description":"An appointment moved to a new time.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"appointment.rescheduled"}},"example":{"id":"…","type":"appointment.rescheduled","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"appointment":{"id":"f1e2d3c4-b5a6-4978-8a6b-5c4d3e2f1a0b","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","service":"Consultation","start_at":"2026-10-02T11:00:00.000Z","end_at":"2026-10-02T11:30:00.000Z","status":"booked","source":"bot","external":null,"notes":null,"created_at":"2026-10-01T09:15:10.000Z","updated_at":"2026-10-01T09:15:10.000Z"},"previous_start_at":"2026-10-02T09:00:00.000Z"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"appointment.cancelled":{"post":{"summary":"appointment.cancelled","description":"An appointment was cancelled.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"appointment.cancelled"}},"example":{"id":"…","type":"appointment.cancelled","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"appointment":{"id":"f1e2d3c4-b5a6-4978-8a6b-5c4d3e2f1a0b","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","service":"Consultation","start_at":"2026-10-02T11:00:00.000Z","end_at":"2026-10-02T11:30:00.000Z","status":"cancelled","source":"bot","external":null,"notes":null,"created_at":"2026-10-01T09:15:10.000Z","updated_at":"2026-10-01T09:15:10.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"appointment.completed":{"post":{"summary":"appointment.completed","description":"The customer showed up to the appointment.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"appointment.completed"}},"example":{"id":"…","type":"appointment.completed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"appointment":{"id":"f1e2d3c4-b5a6-4978-8a6b-5c4d3e2f1a0b","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","service":"Consultation","start_at":"2026-10-02T11:00:00.000Z","end_at":"2026-10-02T11:30:00.000Z","status":"completed","source":"bot","external":null,"notes":null,"created_at":"2026-10-01T09:15:10.000Z","updated_at":"2026-10-01T09:15:10.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"appointment.no_show":{"post":{"summary":"appointment.no_show","description":"The customer did not show up.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"appointment.no_show"}},"example":{"id":"…","type":"appointment.no_show","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"appointment":{"id":"f1e2d3c4-b5a6-4978-8a6b-5c4d3e2f1a0b","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","service":"Consultation","start_at":"2026-10-02T11:00:00.000Z","end_at":"2026-10-02T11:30:00.000Z","status":"no_show","source":"bot","external":null,"notes":null,"created_at":"2026-10-01T09:15:10.000Z","updated_at":"2026-10-01T09:15:10.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"order.created":{"post":{"summary":"order.created","description":"An order was created (payment link sent, cash on delivery, Shopify or logged by hand).\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.created"}},"example":{"id":"…","type":"order.created","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"order":{"id":"0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","status":"pending","amount":"450.00","currency":"AED","items":[{"name":"Starter kit","qty":1,"price":450}],"provider":"strabl","discount_code":null,"address":"Dubai Marina","paid_at":null,"created_at":"2026-10-01T09:40:00.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"order.paid":{"post":{"summary":"order.paid","description":"An order was paid.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.paid"}},"example":{"id":"…","type":"order.paid","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"order":{"id":"0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","status":"paid","amount":"450.00","currency":"AED","items":[{"name":"Starter kit","qty":1,"price":450}],"provider":"strabl","discount_code":null,"address":"Dubai Marina","paid_at":"2026-10-01T10:02:00.000Z","created_at":"2026-10-01T09:40:00.000Z"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"order.cancelled":{"post":{"summary":"order.cancelled","description":"An order was cancelled, failed or replaced by a newer one.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.cancelled"}},"example":{"id":"…","type":"order.cancelled","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"order":{"id":"0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a","contact_id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","status":"cancelled","amount":"450.00","currency":"AED","items":[{"name":"Starter kit","qty":1,"price":450}],"provider":"strabl","discount_code":null,"address":"Dubai Marina","paid_at":null,"created_at":"2026-10-01T09:40:00.000Z"},"reason":"superseded"}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"ad_conversion.sent":{"post":{"summary":"ad_conversion.sent","description":"A conversion (qualified lead, checkout, purchase…) was reported to Meta for ad optimisation. `kind` is OrcaFlo's name for it, `event_name` what Meta received.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"ad_conversion.sent"}},"example":{"id":"…","type":"ad_conversion.sent","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"contact":{"id":"6b0f7c2e-4f1a-4c1e-9a54-2f6f0b3c9d11","phone":"+971501234567","name":"Sara Ahmed","email":null,"lifecycle":"Interested","temperature":"warm","tags":["vip"],"custom_fields":{},"address":null,"notes":null,"source":"whatsapp_inbound","bot_paused":false,"followups_paused":false,"channels":[{"type":"whatsapp","id":"+971501234567"}],"last_message_at":"2026-10-01T09:14:03.120Z","created_at":"2026-09-30T18:02:44.000Z","updated_at":"2026-10-01T09:14:03.120Z"},"conversion":{"kind":"Purchase","event_name":"Purchase","event_id":"purchase:5f4e3d2c","value":450,"currency":"AED","destination":"meta"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"broadcast.completed":{"post":{"summary":"broadcast.completed","description":"A broadcast finished sending.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"broadcast.completed"}},"example":{"id":"…","type":"broadcast.completed","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"broadcast":{"id":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","name":"October offer","sent_count":120,"failed_count":2}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}},"incoming_webhook.received":{"post":{"summary":"incoming_webhook.received","description":"One of your incoming webhook URLs received a request.\n\nSigned with `OrcaFlo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"incoming_webhook.received"}},"example":{"id":"…","type":"incoming_webhook.received","api_version":"2026-10-01","created_at":"…","workspace_id":"…","origin":"bot","data":{"hook_id":"7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d","payload":{"any":"json"}}}}]}}}},"responses":{"200":{"description":"Any 2xx acknowledges; 410 unsubscribes"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"ofk_live_…","description":"Scopes: contacts:read, contacts:write, conversations:read, conversations:write, messages:read, messages:send, workflows:read, workflows:run, broadcasts:read, broadcasts:write, appointments:read, appointments:write, orders:read, products:read, products:write, webhooks:manage, channels:manage, channels:inbound, workflows:write, assistant:write, kb:write, settings:write"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}}}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"phone":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"lifecycle":{"type":["string","null"]},"temperature":{"enum":["hot","warm","cold",null]},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object"},"address":{"type":["string","null"]},"notes":{"type":["string","null"]},"source":{"type":["string","null"]},"bot_paused":{"type":"boolean"},"followups_paused":{"type":"boolean"},"channels":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}}}},"last_message_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"crm_ids":{"type":"object","description":"Linked CRM records, e.g. { \"hubspot\": \"1234\" }. API responses only, not in event payloads.","additionalProperties":{"type":"string"}}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"contact_id":{"type":"string"},"conversation_id":{"type":"string"},"channel":{"type":"string"},"direction":{"enum":["inbound","outbound"]},"sender":{"enum":["contact","bot","agent","api","followup","broadcast","system"]},"type":{"const":"text"},"text":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"contact_id":{"type":"string"},"channel":{"type":"string"},"bot_paused":{"type":"boolean"},"open_escalation":{"type":["object","null"]},"last_message":{"$ref":"#/components/schemas/Message"},"last_inbound_at":{"type":["string","null"]},"unreplied":{"type":"boolean"},"summary":{"type":["string","null"]},"assignee_user_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"status":{"enum":["open","closed","snoozed"]},"contact":{"$ref":"#/components/schemas/Contact"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string"},"contact_id":{"type":["string","null"]},"service":{"type":["string","null"]},"start_at":{"type":"string"},"end_at":{"type":["string","null"]},"status":{"enum":["booked","confirmed","cancelled","completed","no_show"]},"source":{"type":"string"},"service_id":{"type":["string","null"]},"staff_id":{"type":["string","null"]},"external":{"type":["object","null"],"description":"Booked in Calendly or Cal.com","properties":{"provider":{"enum":["calendly","calcom"]},"id":{"type":["string","null"]}}},"notes":{"type":["string","null"]}}},"Workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["draft","published","paused"]},"trigger":{"type":["string","null"]},"can_start_from_api":{"type":"boolean"},"updated_at":{"type":"string"}}},"WorkflowRun":{"type":"object","properties":{"id":{"type":"string"},"workflow_id":{"type":"string"},"contact_id":{"type":"string"},"status":{"enum":["running","waiting","completed","failed","cancelled"]},"started_at":{"type":"string"},"finished_at":{"type":["string","null"]},"error":{"type":["string","null"]}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"contact_id":{"type":["string","null"]},"status":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"items":{"type":"array"},"provider":{"type":"string"},"paid_at":{"type":["string","null"]},"created_at":{"type":"string"}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["contact.created","contact.updated","contact.deleted","contact.tag_added","contact.tag_removed","contact.lifecycle_updated","contact.temperature_updated","message.received","message.sent","message.failed","conversation.escalated","conversation.resolved","conversation.bot_paused","conversation.bot_resumed","conversation.opened","conversation.sla_first_response","conversation.sla_resolved","conversation.sla_breached","conversation.closed","conversation.summary_updated","conversation.assigned","contact.merged","contact.unmerged","appointment.booked","appointment.rescheduled","appointment.cancelled","appointment.completed","appointment.no_show","order.created","order.paid","order.cancelled","ad_conversion.sent","broadcast.completed","incoming_webhook.received"]},"api_version":{"const":"2026-10-01"},"created_at":{"type":"string","format":"date-time"},"workspace_id":{"type":"string"},"origin":{"type":"string"},"data":{"type":"object"}}}}}}