{"openapi":"3.1.0","info":{"title":"Womnibot API","version":"1.0.0","description":"Programmatic access to your Womnibot workspace: contacts, conversations, WhatsApp messages, templates, broadcasts and webhooks."},"servers":[{"url":"https://womnibot.com/api/v1"}],"tags":[{"name":"Account","description":"About the API key in use"},{"name":"Numbers","description":"Your connected WhatsApp business numbers"},{"name":"Contacts","description":"People you talk to on WhatsApp"},{"name":"Conversations","description":"One conversation per contact, with its messages"},{"name":"Messages","description":"Send WhatsApp messages"},{"name":"Templates","description":"Meta-approved message templates"},{"name":"Broadcasts","description":"Bulk template sends and their statistics"},{"name":"Webhooks","description":"Receive signed events at your own URL"},{"name":"Flows","description":"Chatbot flow drafts (a person publishes them) and on-demand triggers"},{"name":"Website chat","description":"Chat widgets for your website, visitors and their identity"},{"name":"AI agents","description":"Let an AI assistant connect with a person's approval (see /llms.txt)"}],"x-scopes":{"contacts:read":"Read contacts","contacts:write":"Create and update contacts","conversations:read":"Read conversations and their messages","conversations:write":"Resolve, reopen, assign and transfer conversations","messages:send":"Send WhatsApp messages (text inside the 24h window, templates any time)","templates:read":"Read message templates","broadcasts:read":"Read broadcasts and their statistics","broadcasts:write":"Create and send broadcasts (reserved: no v1 endpoints yet)","webhooks:manage":"Create, list and delete webhook endpoints","numbers:manage":"Connect and disconnect WhatsApp numbers","flows:write":"List chatbot flows and create or edit drafts (a person publishes them)","webchat:manage":"Create and configure website chat widgets and read website visitors","flows:trigger":"Start published chatbot flows in a conversation"},"x-events":{"contact.created":"A contact was created (first inbound message, API or dashboard)","conversation.opened":"A new conversation started","message.received":"A customer sent a message","message.sent":"A message was sent to a customer (dashboard or API)","message.delivery_updated":"A sent message changed status: sent, delivered, read or failed","survey.responded":"A customer answered a survey (including the post-chat rating)","conversation.resolved":"A conversation was resolved","webchat.visitor_identified":"A website chat visitor shared their details (pre-chat form or identify)","webchat.event":"Your website sent a custom event from the chat widget: Womnibot('track', …)"},"paths":{"/me":{"get":{"tags":["Account"],"summary":"Get the current API key","operationId":"getMe","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":null,"security":[{"bearerAuth":[]}],"description":"Works with any valid key."}},"/numbers":{"get":{"tags":["Numbers"],"summary":"List your WhatsApp numbers","operationId":"listNumbers","description":"Use a number's `id` as `from_number_id` when starting a conversation. The first-connected number is the default.\n\nRequires the `conversations:read` scope.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Number"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"conversations:read","security":[{"bearerAuth":[]}]},"post":{"tags":["Numbers"],"summary":"Connect a WhatsApp number","operationId":"connectNumber","description":"Connects (or reconnects) a WhatsApp Cloud API number. The details are checked with Meta before anything is stored; the token is stored encrypted. See /llms.txt for how to get the values from Meta.\n\nRequires the `numbers:manage` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number_id","waba_id","access_token"],"properties":{"phone_number_id":{"type":"string","examples":["104512345678901"]},"waba_id":{"type":"string","examples":["209876543210987"]},"access_token":{"type":"string","description":"Permanent system user token with whatsapp_business_messaging and whatsapp_business_management"}}}}}},"responses":{"200":{"description":"Reconnected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Number"}}}},"201":{"description":"Connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Number"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (conflict, channel_not_connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"WhatsApp rejected the message (provider_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"numbers:manage","security":[{"bearerAuth":[]}]}},"/numbers/{id}":{"delete":{"tags":["Numbers"],"summary":"Disconnect a WhatsApp number","operationId":"disconnectNumber","description":"Conversations are kept. Nothing changes at Meta.\n\nRequires the `numbers:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Number ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"number"},"id":{"type":"string"},"deleted":{"const":true}}}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"numbers:manage","security":[{"bearerAuth":[]}]}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","operationId":"listContacts","description":"Newest first.\n\nRequires the `contacts:read` scope.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page"},{"name":"tag","in":"query","schema":{"type":"string"},"description":"Only contacts with this tag"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by name or phone number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"contacts:read","security":[{"bearerAuth":[]}]},"post":{"tags":["Contacts"],"summary":"Create a contact","operationId":"createContact","description":"Set `opted_in: true` only when you have the person's consent to receive WhatsApp messages from you.\n\nRequires the `contacts:write` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (conflict, channel_not_connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Rule violation (window_closed, not_opted_in, idempotency_conflict)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"contacts:write","security":[{"bearerAuth":[]}]}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","operationId":"getContact","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"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"contacts:read","security":[{"bearerAuth":[]}],"description":"Requires the `contacts:read` scope."},"patch":{"tags":["Contacts"],"summary":"Update a contact","operationId":"updateContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Contact ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"contacts:write","security":[{"bearerAuth":[]}],"description":"Requires the `contacts:write` scope."}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","operationId":"listConversations","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page"},{"name":"status","in":"query","schema":{"enum":["open","resolved"]}},{"name":"contact_id","in":"query","schema":{"type":"string"}},{"name":"unassigned","in":"query","schema":{"type":"boolean"},"description":"Only conversations with no assignee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"description":"Requires the `conversations:read` scope."}},"/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","operationId":"getConversation","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"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"conversations:read","security":[{"bearerAuth":[]}],"description":"Requires the `conversations:read` scope."},"patch":{"tags":["Conversations"],"summary":"Resolve, reopen, assign or transfer","operationId":"updateConversation","description":"Resolving a website chat sends the post-chat rating when the widget has it on. Emits `conversation.resolved`.\n\nRequires the `conversations:write` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["open","resolved"]},"assignee_id":{"type":["string","null"]},"team_id":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"conversations:write","security":[{"bearerAuth":[]}]}},"/conversations/{id}/messages":{"get":{"tags":["Conversations"],"summary":"List messages in a conversation","operationId":"listMessages","description":"Newest first. Default page size 50.\n\nRequires the `conversations:read` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Conversation ID"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"conversations:read","security":[{"bearerAuth":[]}]}},"/messages":{"post":{"tags":["Messages"],"summary":"Send a message","operationId":"sendMessage","description":"Send to an existing conversation (`conversation_id`) or to an existing contact's phone number (`to`; the conversation is created if needed). Create new contacts first with `POST /contacts`.\n\n**Text** can only be sent within 24 hours of the customer's last message (WhatsApp's customer-service window); otherwise you get `window_closed`. **Templates** can be sent any time, but only to contacts with `opted_in: true`.\n\nRequires the `messages:send` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageSend"}}}},"responses":{"201":{"description":"Accepted by WhatsApp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (conflict, channel_not_connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Rule violation (window_closed, not_opted_in, idempotency_conflict)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"WhatsApp rejected the message (provider_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"messages:send","security":[{"bearerAuth":[]}]}},"/templates":{"get":{"tags":["Templates"],"summary":"List message templates","operationId":"listTemplates","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page"},{"name":"status","in":"query","schema":{"enum":["approved","pending","rejected","paused","disabled"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"templates:read","security":[{"bearerAuth":[]}],"description":"Requires the `templates:read` scope."}},"/templates/sync":{"post":{"tags":["Templates"],"summary":"Sync templates from Meta","operationId":"syncTemplates","description":"Refreshes templates for every connected WhatsApp Business Account. Also runs automatically every 15 minutes.\n\nRequires the `templates:read` scope.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"template_sync"},"synced":{"type":"integer"},"accounts":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"templates:read","security":[{"bearerAuth":[]}]}},"/flows":{"get":{"tags":["Flows"],"summary":"List chatbot flows","operationId":"listFlows","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Flow"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"flows:write","security":[{"bearerAuth":[]}],"description":"Requires the `flows:write` scope."},"post":{"tags":["Flows"],"summary":"Create a chatbot flow draft","operationId":"createFlow","description":"Creates a draft. It never runs until a person reviews and publishes it in the dashboard at `review_url`; the API cannot publish.\n\nRequires the `flows:write` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80},"definition":{"$ref":"#/components/schemas/FlowDefinition"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"flows:write","security":[{"bearerAuth":[]}]}},"/flows/{id}":{"get":{"tags":["Flows"],"summary":"Get a chatbot flow","operationId":"getFlow","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"flows:write","security":[{"bearerAuth":[]}],"description":"Requires the `flows:write` scope."},"patch":{"tags":["Flows"],"summary":"Update a flow's draft","operationId":"updateFlow","description":"Replaces the draft and/or renames the flow. A published version keeps running unchanged until a person publishes again.\n\nRequires the `flows:write` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"definition":{"$ref":"#/components/schemas/FlowDefinition"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"flows:write","security":[{"bearerAuth":[]}]}},"/flows/{id}/trigger":{"post":{"tags":["Flows"],"summary":"Start a flow in a conversation","operationId":"triggerFlow","description":"Starts a published, active flow now, whatever its trigger rules. 409 if another flow is running in the conversation.\n\nRequires the `flows:trigger` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Flow ID"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"flow_run"},"id":{"type":"string"},"status":{"const":"running"}}}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (conflict, channel_not_connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"flows:trigger","security":[{"bearerAuth":[]}]}},"/webchat/widgets":{"get":{"tags":["Website chat"],"summary":"List chat widgets","operationId":"listWidgets","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Widget"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webchat:manage` scope."},"post":{"tags":["Website chat"],"summary":"Create a chat widget","operationId":"createWidget","description":"Returns `embed_code`: paste it before `</body>` on the website.\n\nRequires the `webchat:manage` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}]}},"/webchat/widgets/{id}":{"get":{"tags":["Website chat"],"summary":"Get a chat widget","operationId":"getWidget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Widget ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webchat:manage` scope."},"patch":{"tags":["Website chat"],"summary":"Update a chat widget","operationId":"updateWidget","description":"Settings are merged with the current ones.\n\nRequires the `webchat:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Widget ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}]},"delete":{"tags":["Website chat"],"summary":"Delete a chat widget","operationId":"deleteWidget","description":"Conversations stay in the inbox.\n\nRequires the `webchat:manage` scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Widget ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"const":true}}}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}]}},"/webchat/visitors":{"get":{"tags":["Website chat"],"summary":"List website visitors","operationId":"listVisitors","parameters":[{"name":"online","in":"query","schema":{"type":"boolean"},"description":"Only visitors on the website right now"},{"name":"widget_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Visitor"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webchat:manage` scope."}},"/webchat/visitors/{id}":{"get":{"tags":["Website chat"],"summary":"Get a website visitor","operationId":"getVisitor","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Visitor ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Visitor"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webchat:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webchat:manage` scope."}},"/agent-sessions":{"post":{"tags":["AI agents"],"summary":"Start an AI agent session","operationId":"createAgentSession","security":[],"description":"No key needed. Returns an `approval_url` for your person, who signs up or signs in and approves the requested scopes. Then poll `/agent-sessions/token`. MCP clients can use OAuth at /mcp instead.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","examples":["Claude Code"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Default: the agent set"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"agent_session"},"user_code":{"type":"string","examples":["KQ7M-4TXP"]},"approval_url":{"type":"string"},"session_token":{"type":"string","examples":["wmb_sess_…"]},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"},"poll_interval_seconds":{"type":"integer"}}}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent-sessions/token":{"post":{"tags":["AI agents"],"summary":"Collect the API key after approval","operationId":"pollAgentSession","security":[],"description":"Poll every 5 seconds. `status` is pending, approved (with `api_key`, returned exactly once), denied, expired or claimed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_token"],"properties":{"session_token":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"enum":["pending","approved"]},"api_key":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"403":{"description":"Denied"},"404":{"description":"Unknown session"},"410":{"description":"Expired, or the key was already collected"}}}},"/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"List broadcasts","operationId":"listBroadcasts","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Broadcast"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"broadcasts:read","security":[{"bearerAuth":[]}],"description":"Requires the `broadcasts:read` scope."}},"/webhook-endpoints":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","operationId":"listWebhookEndpoints","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"next_cursor":{"type":["string","null"]}},"required":["object","data","next_cursor"]}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webhooks:manage` scope."},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","operationId":"createWebhookEndpoint","description":"The response includes the endpoint's signing `secret`. It is shown only once. The URL must be public HTTPS.\n\nRequires the `webhooks:manage` scope.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Optional. Retrying with the same key returns the original result instead of repeating the action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","examples":["whsec_…"]}}}]}}}},"400":{"description":"Invalid request (validation_failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (conflict, channel_not_connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}]}},"/webhook-endpoints/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","operationId":"deleteWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"webhook_endpoint"},"id":{"type":"string"},"deleted":{"const":true}}}}}},"401":{"description":"Missing, invalid or revoked API key (unauthorized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (insufficient_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"description":"Requires the `webhooks:manage` scope."}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Dashboard → Developers, e.g. `wmb_live_…`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["validation_failed"]},"message":{"type":"string"},"correlation_id":{"type":"string","description":"Quote this when contacting support"},"details":{}},"required":["code","message","correlation_id"]}}},"ApiKey":{"type":"object","properties":{"object":{"const":"api_key"},"id":{"type":"string"},"name":{"type":"string"},"key_prefix":{"type":"string"},"scopes":{"type":"array","items":{"enum":["contacts:read","contacts:write","conversations:read","conversations:write","messages:send","templates:read","broadcasts:read","broadcasts:write","webhooks:manage","numbers:manage","flows:write","webchat:manage","flows:trigger"]}},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"}}},"Number":{"type":"object","properties":{"object":{"const":"number"},"id":{"type":"string"},"phone":{"type":"string","examples":["+1 555-010-0199"]},"verified_name":{"type":["string","null"]},"phone_number_id":{"type":"string","description":"Meta's phone number ID"},"waba_id":{"type":"string","description":"WhatsApp Business Account ID"},"quality_rating":{"enum":["green","yellow","red","unknown",null]},"messaging_limit_tier":{"type":["string","null"]},"default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Widget":{"type":"object","properties":{"object":{"const":"webchat_widget"},"id":{"type":"string"},"name":{"type":"string"},"public_key":{"type":"string","examples":["wgt_AbC123…"]},"enabled":{"type":"boolean"},"allowed_domains":{"type":"array","items":{"type":"string"}},"default_team_id":{"type":["string","null"]},"whatsapp_number_id":{"type":["string","null"]},"settings":{"type":"object"},"embed_code":{"type":"string"},"install":{"type":"object","properties":{"last_seen_at":{"type":["string","null"]},"last_seen_on":{"type":["string","null"]}}}}},"WidgetInput":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"allowed_domains":{"type":"array","items":{"type":"string"},"examples":[["example.com","*.example.com"]]},"default_team_id":{"type":["string","null"]},"whatsapp_number_id":{"type":["string","null"]},"settings":{"type":"object","properties":{"color":{"type":"string","examples":["#059669"]},"position":{"enum":["right","left"]},"title":{"type":"string"},"subtitle":{"type":"string"},"welcome_message":{"type":"string"},"launcher_label":{"type":"string"},"reply_time":{"enum":["minutes","hour","day"]},"offline_message":{"type":"string"},"pre_chat":{"type":"object","properties":{"name":{"enum":["off","optional","required"]},"email":{"enum":["off","optional","required"]},"phone":{"enum":["off","optional","required"]},"intro":{"type":"string"}}},"starters":{"type":"array","items":{"type":"string"},"maxItems":4},"csat":{"type":"object","properties":{"enabled":{"type":"boolean"},"question":{"type":"string"}}},"attachments":{"type":"boolean"},"emoji":{"type":"boolean"},"sound":{"type":"boolean"},"whatsapp_button":{"type":"boolean"}}}}},"Visitor":{"type":"object","properties":{"object":{"const":"webchat_visitor"},"id":{"type":"string"},"widget_id":{"type":"string"},"contact_id":{"type":["string","null"]},"conversation_id":{"type":["string","null"]},"online":{"type":"boolean"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_id":{"type":["string","null"]},"verified":{"type":"boolean","description":"external_id was signed with the widget's identity secret"},"attributes":{"type":"object"},"page":{"type":"object","properties":{"url":{"type":["string","null"]},"title":{"type":["string","null"]},"referrer":{"type":["string","null"]}}},"country":{"type":["string","null"]},"last_seen_at":{"type":"string","format":"date-time"}}},"Flow":{"type":"object","properties":{"object":{"const":"flow"},"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["draft","active","paused"]},"draft":{"$ref":"#/components/schemas/FlowDefinition"},"problems":{"type":"array","items":{"type":"string"},"description":"What still blocks publishing"},"actions_needed":{"type":"array","items":{"type":"string"}},"review_url":{"type":"string","description":"Where a person reviews and publishes it"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"FlowDefinition":{"type":"object","description":"See /llms.txt (Chatbot flows) for step types and an example.","properties":{"trigger":{"type":"object","properties":{"match":{"enum":["any","keywords"]},"keywords":{"type":"array","items":{"type":"string"}},"only_unassigned":{"type":"boolean","default":true},"only_new_conversation":{"type":"boolean","default":false}}},"start":{"type":["string","null"],"description":"First step id (default: the first step)"},"steps":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string"},"type":{"enum":["send","ask","condition","assign","tag","delay","note","handoff","close"]}}}}}},"Contact":{"type":"object","properties":{"object":{"const":"contact"},"id":{"type":"string"},"wa_id":{"type":"string","description":"WhatsApp ID: phone number without +","examples":["972501234567"]},"phone":{"type":"string","examples":["+972501234567"]},"name":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"opted_in":{"type":"boolean"},"opted_in_at":{"type":["string","null"],"format":"date-time"},"source":{"type":["string","null"]},"last_seen_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ContactCreate":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"International format with +","examples":["+972501234567"]},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"maxItems":50},"opted_in":{"type":"boolean","default":false}}},"ContactUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"opted_in":{"type":"boolean"}}},"Conversation":{"type":"object","properties":{"object":{"const":"conversation"},"id":{"type":"string"},"contact_id":{"type":"string"},"number_id":{"type":["string","null"],"description":"The business number this conversation is on (one conversation per contact per number)"},"team_id":{"type":["string","null"]},"status":{"enum":["open","resolved"]},"assignee_id":{"type":["string","null"]},"unread_count":{"type":"integer"},"last_message_at":{"type":"string","format":"date-time"},"last_inbound_at":{"type":["string","null"],"format":"date-time"},"reply_window_ends_at":{"type":["string","null"],"format":"date-time","description":"Free-form text is allowed until this time; null means the window is closed (send a template)."},"created_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"object":{"const":"message"},"id":{"type":"string"},"conversation_id":{"type":"string"},"direction":{"enum":["inbound","outbound"]},"sender":{"enum":["customer","agent","bot"]},"type":{"type":"string","examples":["text","template","image"]},"text":{"type":["string","null"]},"status":{"enum":["pending","sent","delivered","read","failed",null]},"error":{"type":["string","null"]},"whatsapp_message_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"MessageSend":{"oneOf":[{"title":"Text","type":"object","required":["type","text"],"properties":{"conversation_id":{"type":"string"},"to":{"type":"string","examples":["+972501234567"]},"webchat_visitor_id":{"type":"string","description":"Website chat: message this visitor (starts their conversation if needed)"},"from_number_id":{"type":"string","description":"With `to`: which of your numbers to send from"},"type":{"const":"text"},"text":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":4096}}}}},{"title":"Template","type":"object","required":["type","template"],"properties":{"conversation_id":{"type":"string"},"to":{"type":"string","examples":["+972501234567"]},"webchat_visitor_id":{"type":"string","description":"Website chat: message this visitor (starts their conversation if needed)"},"from_number_id":{"type":"string","description":"With `to`: which of your numbers to send from"},"type":{"const":"template"},"template":{"type":"object","required":["name","language"],"properties":{"name":{"type":"string","examples":["order_shipped"]},"language":{"type":"string","examples":["en"]},"components":{"type":"array","description":"WhatsApp template components with parameters, passed through to Meta","items":{"type":"object"}}}}}},{"title":"Buttons","type":"object","required":["type","interactive"],"properties":{"conversation_id":{"type":"string"},"webchat_visitor_id":{"type":"string"},"to":{"type":"string"},"type":{"const":"interactive"},"interactive":{"type":"object","required":["body","buttons"],"properties":{"body":{"type":"string","maxLength":1024},"buttons":{"type":"array","maxItems":10,"items":{"oneOf":[{"type":"object","required":["type","id","title"],"properties":{"type":{"const":"reply"},"id":{"type":"string"},"title":{"type":"string","maxLength":40}}},{"type":"object","required":["type","title","url"],"properties":{"type":{"const":"url"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}]},"description":"WhatsApp: up to 3 reply buttons (≤20 characters). Website chat: reply and link buttons."}}}}},{"title":"Survey","type":"object","required":["type","survey"],"properties":{"conversation_id":{"type":"string"},"webchat_visitor_id":{"type":"string"},"type":{"const":"survey"},"survey":{"type":"object","required":["kind","question"],"properties":{"kind":{"enum":["rating","choice","text"]},"question":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"description":"choice: 2–10 options (WhatsApp: ≤3, ≤20 characters)"},"comment":{"type":"boolean","description":"Ask for an optional comment (website chat)"}}}},"description":"Answers arrive as a `survey.responded` webhook. WhatsApp supports choice surveys only."},{"title":"Media","type":"object","required":["type","media"],"properties":{"conversation_id":{"type":"string"},"webchat_visitor_id":{"type":"string"},"type":{"const":"media"},"media":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public https URL; downloaded by Womnibot"},"caption":{"type":"string"},"filename":{"type":"string"}}}}}],"description":"Provide exactly one of `conversation_id`, `to` or `webchat_visitor_id`. Website chat has no 24-hour window and no templates."},"Template":{"type":"object","properties":{"object":{"const":"template"},"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"enum":["marketing","utility","authentication"]},"status":{"enum":["approved","pending","rejected","paused","disabled"]},"components":{"type":"array","items":{"type":"object"}},"updated_at":{"type":"string","format":"date-time"}}},"Broadcast":{"type":"object","properties":{"object":{"const":"broadcast"},"id":{"type":"string"},"name":{"type":"string"},"template_id":{"type":["string","null"]},"status":{"enum":["draft","scheduled","sending","sent","failed"]},"scheduled_at":{"type":["string","null"],"format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"},"stats":{"type":"object","properties":{"recipients":{"type":"integer"},"delivered":{"type":"integer"},"read":{"type":"integer"},"replied":{"type":"integer"}}},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","properties":{"object":{"const":"webhook_endpoint"},"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpointCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","examples":["https://example.com/webhooks/womnibot"]},"events":{"type":"array","items":{"enum":["*","contact.created","conversation.opened","message.received","message.sent","message.delivery_updated","survey.responded","conversation.resolved","webchat.visitor_identified","webchat.event"]},"minItems":1}}},"WebhookEvent":{"type":"object","description":"Body of every webhook delivery.","properties":{"id":{"type":"string","description":"Unique event ID: deduplicate on this (delivery is at-least-once)","examples":["evt_3f2a…"]},"type":{"enum":["contact.created","conversation.opened","message.received","message.sent","message.delivery_updated","survey.responded","conversation.resolved","webchat.visitor_identified","webchat.event"]},"schema_version":{"type":"string","examples":["2026-09-28"]},"created_at":{"type":"string","format":"date-time"},"workspace_id":{"type":"string"},"data":{"type":"object"}}}}}}