{"openapi":"3.0.3","info":{"title":"Inboxy.chat API","description":"Omnichannel customer communication platform API","version":"1.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"JWT token or API token (inboxy_...)"}},"schemas":{}},"paths":{"/api/v1/contacts/":{"get":{"summary":"List contacts","tags":["Contacts"],"description":"Requires contacts:read permission.","parameters":[{"schema":{"type":"string","example":"ahmed"},"in":"query","name":"search","required":false,"description":"Name, phone or email."},{"schema":{"type":"string","example":"tag_1,tag_2"},"in":"query","name":"tagIds","required":false,"description":"Comma-separated tag ids."},{"schema":{"type":"boolean","example":true},"in":"query","name":"hasPhone","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"hasEmail","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"hasOrders","required":false},{"schema":{"type":"string","example":"WHATSAPP"},"in":"query","name":"channelType","required":false,"description":"Channel the contact came from."},{"schema":{"type":"string","example":"MANUAL,SHOPIFY"},"in":"query","name":"source","required":false,"description":"Comma-separated sources (MANUAL, WHATSAPP, SHOPIFY, …)."},{"schema":{"type":"string","example":"ACTIVE"},"in":"query","name":"status","required":false,"description":"Comma-separated: ACTIVE, INACTIVE, ARCHIVED."},{"schema":{"type":"string","example":"HOT_LEAD"},"in":"query","name":"label","required":false,"description":"Comma-separated: HOT_LEAD, WARM_LEAD, COLD_LEAD, FOLLOW_UP, VIP, CHURNED, DO_NOT_CONTACT."},{"schema":{"type":"string","example":"CUSTOMER"},"in":"query","name":"lifecycleStage","required":false,"description":"Comma-separated: LEAD, SUBSCRIBER, OPPORTUNITY, CUSTOMER, REPEAT_CUSTOMER, EVANGELIST."},{"schema":{"type":"string"},"in":"query","name":"assignedAgentId","required":false},{"schema":{"type":"number","example":100},"in":"query","name":"minTotalSpent","required":false},{"schema":{"type":"number","example":5000},"in":"query","name":"maxTotalSpent","required":false},{"schema":{"type":"string"},"in":"query","name":"lastInteractionAfter","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"lastInteractionBefore","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"createdAfter","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"createdBefore","required":false,"description":"ISO date-time."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Page size."},{"schema":{"type":"string","enum":["name","createdAt","updatedAt"],"example":"createdAt"},"in":"query","name":"sortBy","required":false},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc"},"in":"query","name":"sortOrder","required":false,"description":"Sort direction."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Contact display name.","example":"Ahmed Al-Otaibi"},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"phone":{"type":"string","description":"Phone number, digits only (no leading +).","example":"966500000000"},"email":{"type":"string","description":"Email address.","example":"ahmed@example.com"},"avatar":{"type":"string","description":"Avatar image URL."},"externalId":{"type":"string","description":"ID of this contact in an external system."},"customFields":{"type":"object","description":"Arbitrary key/value custom fields."},"tagIds":{"type":"array","items":{"type":"string"},"description":"Tag IDs to attach to the contact."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/search":{"get":{"summary":"Search contacts","tags":["Contacts"],"description":"Requires contacts:read permission.","parameters":[{"schema":{"type":"string","example":"Sara"},"in":"query","name":"q","required":true,"description":"Name, phone or email to search for."},{"schema":{"type":"integer","example":10},"in":"query","name":"limit","required":false,"description":"Max results (default 10)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/find-or-create":{"post":{"summary":"Find a contact or create it","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number to search for, or create if no contact matches.","example":"966500000000"},"name":{"type":"string","description":"Name to use if a new contact is created. Defaults to the phone number.","example":"Ahmed Al-Otaibi"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/custom-field-keys":{"get":{"summary":"List custom field keys","tags":["Contacts"],"description":"Requires contacts:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}":{"get":{"summary":"Get a contact","tags":["Contacts"],"description":"Requires contacts:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Contact display name.","example":"Ahmed Al-Otaibi"},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"phone":{"type":"string","description":"Phone number, digits only (no leading +).","example":"966500000000"},"email":{"type":"string","description":"Email address.","example":"ahmed@example.com"},"avatar":{"type":"string","description":"Avatar image URL."},"externalId":{"type":"string","description":"ID of this contact in an external system."},"customFields":{"type":"object","description":"Arbitrary key/value custom fields."},"tagIds":{"type":"array","items":{"type":"string"},"description":"Tag IDs to attach to the contact."},"label":{"type":"string","enum":["HOT_LEAD","WARM_LEAD","COLD_LEAD","FOLLOW_UP","VIP","CHURNED","DO_NOT_CONTACT"],"description":"CDP label, or null to clear."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","ARCHIVED"],"description":"Contact status."},"lifecycleStage":{"type":"string","enum":["LEAD","SUBSCRIBER","OPPORTUNITY","CUSTOMER","REPEAT_CUSTOMER","EVANGELIST"],"description":"CDP lifecycle stage."},"assignedAgentId":{"type":"string","description":"User ID of the assigned agent, or null to unassign."},"notes":{"type":"string","description":"Free-text notes on the contact."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/tags/{tagId}":{"post":{"summary":"Add a tag to a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove a tag from a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/tags/all":{"get":{"summary":"List tags","tags":["Contacts"],"description":"Requires contacts:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/tags":{"post":{"summary":"Create a tag","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100,"description":"Tag name, max 100 characters. Letters, numbers, spaces and - _ . , & ( ) # only.","example":"VIP"},"color":{"type":"string","description":"Hex color for the tag.","example":"#3bc1a8"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/tags/{tagId}":{"put":{"summary":"Update a tag","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"description":"Tag name."},"color":{"type":"string","description":"Hex color for the tag."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a tag","tags":["Contacts"],"description":"Requires contacts:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/status":{"patch":{"summary":"Set contact status","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ACTIVE","INACTIVE","ARCHIVED"],"description":"New contact status.","example":"ACTIVE"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/stage":{"patch":{"summary":"Set contact lifecycle stage","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["lifecycleStage"],"properties":{"lifecycleStage":{"type":"string","enum":["LEAD","SUBSCRIBER","OPPORTUNITY","CUSTOMER","REPEAT_CUSTOMER","EVANGELIST"],"description":"New lifecycle stage.","example":"CUSTOMER"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/assign":{"patch":{"summary":"Assign a contact to an agent","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","description":"User ID to assign the contact to, or null to unassign."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/note":{"post":{"summary":"Add a note to a contact","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","description":"Note text to append to the contact."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/{id}/timeline":{"get":{"summary":"Get a contact timeline","tags":["Contacts"],"description":"Requires contacts:read permission.","parameters":[{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"query","name":"types","required":false,"description":"Comma-separated activity types, e.g. MESSAGE_SENT,TAG_ADDED."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/contacts/bulk/tags":{"post":{"summary":"Tag many contacts","tags":["Contacts"],"description":"Requires contacts:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contactIds","tagIds","action"],"properties":{"contactIds":{"type":"array","items":{"type":"string"},"description":"Contact IDs to update."},"tagIds":{"type":"array","items":{"type":"string"},"description":"Tag IDs to add or remove."},"action":{"type":"string","enum":["add","remove"],"description":"Whether to add or remove the tags.","example":"add"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/catalog-card":{"post":{"summary":"Send an Inboxy product or service card","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["conversationId","itemType","itemId","language"],"properties":{"conversationId":{"type":"string","description":"WhatsApp conversation to send into."},"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string","description":"Product or service id."},"language":{"type":"string","enum":["ar","en"]}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/media/upload":{"post":{"summary":"Upload media to WhatsApp and get a media id for sends","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mediaType"],"properties":{"mediaType":{"type":"string","enum":["image","video","audio","document"]},"mediaUrl":{"type":"string"},"base64":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/media/upload-for-template":{"post":{"summary":"Upload a template header file and get its media handle","tags":["Templates"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["mediaType"],"properties":{"mediaType":{"type":"string","enum":["image","video","document"],"example":"image"},"mediaUrl":{"type":"string","description":"Public URL to fetch. Send this or base64.","example":"https://cdn.example.com/banner.jpg"},"base64":{"type":"string","description":"File content, base64-encoded."},"filename":{"type":"string","example":"banner.jpg"},"mimeType":{"type":"string","example":"image/jpeg"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/text":{"post":{"summary":"Send a WhatsApp text message","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/template":{"post":{"summary":"Send an approved WhatsApp template","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","templateName","languageCode"],"properties":{"to":{"type":"string"},"templateName":{"type":"string"},"languageCode":{"type":"string"},"components":{"type":"array"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/buttons":{"post":{"summary":"Send a WhatsApp reply-buttons message","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body","buttons"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"buttons":{"type":"array","items":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string"},"title":{"type":"string"}}}},"header":{"type":"string"},"headerImage":{"type":"string","maxLength":2048},"footer":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/list":{"post":{"summary":"Send a WhatsApp list message","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body","buttonText","sections"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"buttonText":{"type":"string"},"sections":{"type":"array"},"header":{"type":"string"},"footer":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/cta-url":{"post":{"summary":"Send a WhatsApp call-to-action URL button","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body","displayText","url"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"displayText":{"type":"string"},"url":{"type":"string"},"header":{"type":"string"},"headerImage":{"type":"string","maxLength":2048},"footer":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/location-request":{"post":{"summary":"Ask the customer to share their location","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/catalog":{"post":{"summary":"Send the WhatsApp catalog","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string"},"body":{"type":"string"},"footer":{"type":"string"},"thumbnailProductRetailerId":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/product":{"post":{"summary":"Send one catalog product","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","catalogId","productRetailerId"],"properties":{"to":{"type":"string"},"catalogId":{"type":"string"},"productRetailerId":{"type":"string"},"body":{"type":"string"},"footer":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/product-list":{"post":{"summary":"Send a multi-product message","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","header","body","catalogId","sections"],"properties":{"to":{"type":"string"},"header":{"type":"string"},"body":{"type":"string"},"catalogId":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["title","productRetailerIds"],"properties":{"title":{"type":"string"},"productRetailerIds":{"type":"array","items":{"type":"string"}}}}},"footer":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/media":{"post":{"summary":"Send WhatsApp media (image, video, audio, document)","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","mediaType","mediaUrl"],"properties":{"to":{"type":"string"},"mediaType":{"type":"string","enum":["image","video","audio","document"]},"mediaUrl":{"type":"string"},"caption":{"type":"string"},"filename":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/location":{"post":{"summary":"Send a location pin","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","latitude","longitude"],"properties":{"to":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"name":{"type":"string"},"address":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/contacts":{"post":{"summary":"Send contact cards","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string"},"contacts":{"type":"array"},"contact":{"type":"object"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/contact":{"post":{"summary":"Send one contact card","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string"},"contacts":{"type":"array"},"contact":{"type":"object"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/messages/{messageId}/read":{"post":{"summary":"Mark an inbound WhatsApp message as read","tags":["Messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"messageId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates":{"get":{"summary":"List WhatsApp templates","tags":["Templates"],"description":"Requires templates:read permission.","parameters":[{"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"],"example":"APPROVED"},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a WhatsApp template and submit it to Meta for review","tags":["Templates"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","category","language","bodyText"],"properties":{"name":{"type":"string","description":"Lowercase letters, digits and underscores. Unique per language.","example":"order_shipped"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"language":{"type":"string","description":"Meta language code.","example":"ar"},"templateType":{"type":"string","enum":["STANDARD","CAROUSEL","LIMITED_TIME_OFFER"],"example":"STANDARD"},"headerType":{"type":"string","enum":["NONE","TEXT","IMAGE","VIDEO","DOCUMENT"],"example":"TEXT"},"headerText":{"type":"string","description":"TEXT headers: up to 60 characters, at most one {{1}}.","example":"Your order is on its way"},"headerExample":{"type":"string","description":"TEXT headers: sample for {{1}}. IMAGE/VIDEO/DOCUMENT headers: the media handle from POST /api/v1/whatsapp/media/upload-for-template."},"headerMediaUrl":{"type":"string","description":"Media headers: the public URL of the same file, stored so every send attaches it automatically."},"bodyText":{"type":"string","description":"Up to 1,024 characters. Variables are {{1}}, {{2}}, … in order.","example":"مرحباً {{1}}، طلبك رقم {{2}} في الطريق إليك."},"bodyExamples":{"type":"array","items":{"type":"string"},"description":"One sample value per body variable, in order. Meta reviews the template with these.","example":["سارة","10234"]},"footerText":{"type":"string","description":"Up to 60 characters, no variables.","example":"Inboxy Store"},"buttons":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","OTP","FLOW"]},"text":{"type":"string","description":"Button label (max 25 characters).","example":"Track order"},"url":{"type":"string","description":"URL buttons: the link. May end in {{1}} for a dynamic suffix.","example":"https://shop.example.com/orders/{{1}}"},"urlExample":{"type":"string","description":"URL buttons with {{1}}: a sample full URL for review."},"phoneNumber":{"type":"string","description":"PHONE_NUMBER buttons: E.164 number.","example":"+966500000000"},"couponCode":{"type":"string","description":"COPY_CODE buttons: the coupon to copy."},"otpType":{"type":"string","enum":["COPY_CODE","ONE_TAP"],"description":"OTP buttons (AUTHENTICATION templates)."},"flowId":{"type":"string","description":"FLOW buttons: the WhatsApp Flow id."},"flowAction":{"type":"string","enum":["navigate","data_exchange"]}}},"description":"Up to 10 buttons."},"carouselCards":{"type":"array","description":"CAROUSEL templates: 2–10 cards, each with a media header, body and buttons.","items":{"type":"object","required":["bodyText","buttons"],"properties":{"headerMediaHandle":{"type":"string","description":"Handle from upload-for-template."},"headerMediaUrl":{"type":"string"},"headerFormat":{"type":"string","enum":["IMAGE","VIDEO"]},"bodyText":{"type":"string"},"bodyExamples":{"type":"array","items":{"type":"string"}},"buttons":{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","OTP","FLOW"]},"text":{"type":"string","description":"Button label (max 25 characters).","example":"Track order"},"url":{"type":"string","description":"URL buttons: the link. May end in {{1}} for a dynamic suffix.","example":"https://shop.example.com/orders/{{1}}"},"urlExample":{"type":"string","description":"URL buttons with {{1}}: a sample full URL for review."},"phoneNumber":{"type":"string","description":"PHONE_NUMBER buttons: E.164 number.","example":"+966500000000"},"couponCode":{"type":"string","description":"COPY_CODE buttons: the coupon to copy."},"otpType":{"type":"string","enum":["COPY_CODE","ONE_TAP"],"description":"OTP buttons (AUTHENTICATION templates)."},"flowId":{"type":"string","description":"FLOW buttons: the WhatsApp Flow id."},"flowAction":{"type":"string","enum":["navigate","data_exchange"]}}}}}}},"ltoText":{"type":"string","description":"LIMITED_TIME_OFFER: the offer headline."},"ltoExpiration":{"type":"string","format":"date-time","description":"LIMITED_TIME_OFFER: when the offer ends."},"ltoCouponCode":{"type":"string","description":"LIMITED_TIME_OFFER: coupon shown on a copy-code button."},"authSecurityDisclaimer":{"type":"boolean","description":"AUTHENTICATION: add \"Do not share this code\" (default true)."},"authExpirationMinutes":{"type":"number","description":"AUTHENTICATION: code lifetime shown to the customer."},"variableMapping":{"type":"object","description":"Required when bodyText has variables: one entry per variable number, saying where the value comes from at send time. Types: `static` (value used as-is), `contact_field` (firstName, lastName, name, email, phone), `custom_field` (a contact custom-field key), `order_field` (last.order.total, last.order.product, last.order.status, last.order.date, last.order.shipping_address, last.order.tracking_number), `web_event_field` (a path in the triggering web event).","example":{"1":{"type":"contact_field","value":"firstName"},"2":{"type":"order_field","value":"last.order.tracking_number"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/{templateId}":{"get":{"summary":"Get a WhatsApp template","tags":["Templates"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"templateId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/{templateId}/media":{"patch":{"summary":"Attach the media every send of this template uses","tags":["Templates"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"headerMediaId":{"type":"string","description":"Media id (from POST /api/v1/whatsapp/media/upload) to attach as the header on every send."},"carouselCards":{"type":"array","items":{"type":"object","required":["index","mediaId"],"properties":{"index":{"type":"number"},"mediaId":{"type":"string"}}}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"templateId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/sync":{"post":{"summary":"Sync templates and their approval status from Meta","tags":["Templates"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/{templateName}":{"delete":{"summary":"Delete a WhatsApp template (all languages) from Meta and Inboxy","tags":["Templates"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"templateName","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/{templateName}/usage":{"get":{"summary":"Delivery ledger for a template","tags":["Templates"],"description":"Requires templates:read permission.","parameters":[{"schema":{"type":"string","example":"ar"},"in":"query","name":"language","required":false,"description":"One language variant of the template."},{"schema":{"type":"string"},"in":"path","name":"templateName","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/templates/{templateName}/mapping":{"patch":{"summary":"Change where template variables get their values","tags":["Templates"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variableMapping"],"properties":{"variableMapping":{"type":"object","description":"Same shape as variableMapping on create. Stored in Inboxy only; Meta is not called.","example":{"1":{"type":"contact_field","value":"firstName"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"templateName","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/stats":{"get":{"summary":"WhatsApp message and conversation totals","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/summary":{"get":{"summary":"WhatsApp analytics summary","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/messages":{"get":{"summary":"Message volume","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/messages/trends":{"get":{"summary":"Message trends","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/response-times":{"get":{"summary":"Response times","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/templates":{"get":{"summary":"Template performance","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."},{"schema":{"type":"integer","example":10},"in":"query","name":"limit","required":false,"description":"Max templates (default 10)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/conversations":{"get":{"summary":"Conversation metrics","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/agents":{"get":{"summary":"Agent performance","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."},{"schema":{"type":"integer","example":10},"in":"query","name":"limit","required":false,"description":"Max agents (default 10)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/analytics/channels":{"get":{"summary":"Channel breakdown","tags":["WhatsApp analytics"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-01"},"in":"query","name":"startDate","required":false,"description":"ISO date; use with endDate for an explicit range."},{"schema":{"type":"string","example":"2026-09-16"},"in":"query","name":"endDate","required":false,"description":"ISO date; use with startDate."},{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Trailing N-day range, ignored when startDate and endDate are given. No range = all time."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns":{"get":{"summary":"List WhatsApp campaigns","tags":["Campaigns"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","enum":["DRAFT","SCHEDULED","RUNNING","PAUSED","COMPLETED","CANCELLED","FAILED"]},"in":"query","name":"status","required":false,"description":"Must be one of the listed values."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Campaign name."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Max rows (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","templateId","audience"],"properties":{"name":{"type":"string","example":"Ramadan offer"},"templateId":{"type":"string","description":"An APPROVED template id (GET /api/v1/whatsapp/templates)."},"audience":{"type":"object","required":["type"],"description":"Who receives the campaign. `ALL`: every opted-in contact. `TAGS`: contacts with any of `tagIds`. `CONTACTS`: exactly `contactIds` (max 5,000). `IMPORT_BATCH`: the `batchId` returned by import-audience.","properties":{"type":{"type":"string","enum":["ALL","TAGS","CONTACTS","IMPORT_BATCH"],"example":"TAGS"},"tagIds":{"type":"array","items":{"type":"string"}},"contactIds":{"type":"array","items":{"type":"string"}},"batchId":{"type":"string"}}},"templateComponents":{"type":"array","items":{"type":"object"},"description":"Meta template components; omit to use the template’s saved variable mapping."},"scheduledAt":{"type":"string","format":"date-time","description":"Omit to create a draft; run it with POST /campaigns/:id/run."},"messagesPerSecond":{"type":"number","description":"1–20.","example":10},"messagesPerDay":{"type":"number","description":"Daily cap; the send spreads across days."},"aiEnabled":{"type":"boolean","description":"Let the AI agent answer replies to this campaign."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}":{"get":{"summary":"Get a campaign","tags":["Campaigns"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a draft or scheduled campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"DRAFT or SCHEDULED campaigns only.","properties":{"name":{"type":"string"},"templateId":{"type":"string"},"audience":{"type":"object","required":["type"],"description":"Who receives the campaign. `ALL`: every opted-in contact. `TAGS`: contacts with any of `tagIds`. `CONTACTS`: exactly `contactIds` (max 5,000). `IMPORT_BATCH`: the `batchId` returned by import-audience.","properties":{"type":{"type":"string","enum":["ALL","TAGS","CONTACTS","IMPORT_BATCH"],"example":"TAGS"},"tagIds":{"type":"array","items":{"type":"string"}},"contactIds":{"type":"array","items":{"type":"string"}},"batchId":{"type":"string"}}},"templateComponents":{"type":"array","items":{"type":"object"}},"scheduledAt":{"type":["string","null"],"format":"date-time"},"autoRetry":{"type":"boolean"},"maxRetries":{"type":"number"}}}}},"description":"DRAFT or SCHEDULED campaigns only."},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/run":{"post":{"summary":"Start sending a campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/cancel":{"post":{"summary":"Cancel a campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/pause":{"post":{"summary":"Pause a running campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/resume":{"post":{"summary":"Resume a paused campaign","tags":["Campaigns"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/recipients":{"get":{"summary":"List campaign recipients","tags":["Campaigns"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","enum":["PENDING","CLAIMED","SKIPPED","SENT","DELIVERED","READ","FAILED","REPLIED"]},"in":"query","name":"status","required":false,"description":"Must be one of the listed values."},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Max rows (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/details":{"get":{"summary":"Get campaign details and counts","tags":["Campaigns"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/preview":{"post":{"summary":"Preview audience size and cost without creating","tags":["Campaigns"],"description":"Requires campaigns:read permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["templateId","audience"],"properties":{"templateId":{"type":"string"},"audience":{"type":"object","required":["type"],"description":"Who receives the campaign. `ALL`: every opted-in contact. `TAGS`: contacts with any of `tagIds`. `CONTACTS`: exactly `contactIds` (max 5,000). `IMPORT_BATCH`: the `batchId` returned by import-audience.","properties":{"type":{"type":"string","enum":["ALL","TAGS","CONTACTS","IMPORT_BATCH"],"example":"TAGS"},"tagIds":{"type":"array","items":{"type":"string"}},"contactIds":{"type":"array","items":{"type":"string"}},"batchId":{"type":"string"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/import-audience":{"post":{"summary":"Import an audience (matches or creates contacts)","tags":["Campaigns"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","example":"Sara"},"phone":{"type":"string","example":"966500000000"},"email":{"type":"string"},"tags":{"type":"string","description":"Comma-separated tag names."}}}},"createMissing":{"type":"boolean","description":"Create contacts that do not exist yet (default true)."},"defaultCountryCode":{"type":"string","example":"966"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/retry":{"post":{"summary":"Retry failed recipients","tags":["Campaigns"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipientIds":{"type":"array","items":{"type":"string"}},"failureCategories":{"type":"array","items":{"type":"string"}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/analytics":{"get":{"summary":"Get campaign link clicks","tags":["Campaigns"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/whatsapp/campaigns/{id}/timeseries":{"get":{"summary":"Get deliveries over time","tags":["Campaigns"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/send":{"post":{"summary":"Send an Instagram DM","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","content"],"properties":{"to":{"type":"string"},"content":{"type":"string"},"conversationId":{"type":"string"},"mediaType":{"type":"string","enum":["image","video","audio","file"]},"mediaUrl":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/send/quick-replies":{"post":{"summary":"Send Instagram quick replies","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","text","quickReplies"],"properties":{"to":{"type":"string"},"text":{"type":"string"},"quickReplies":{"type":"array","items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string"},"payload":{"type":"string"}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/send/carousel":{"post":{"summary":"Send an Instagram carousel","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","elements"],"properties":{"to":{"type":"string"},"elements":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"image_url":{"type":"string"},"default_action":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"}}},"buttons":{"type":"array"}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/send/buttons":{"post":{"summary":"Send an Instagram DM with buttons","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","text","buttons"],"properties":{"to":{"type":"string"},"text":{"type":"string"},"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"payload":{"type":"string"}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/send/media-template":{"post":{"summary":"Send an Instagram media template","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["to","mediaType","mediaUrl"],"properties":{"to":{"type":"string"},"mediaType":{"type":"string","enum":["image","video"]},"mediaUrl":{"type":"string"},"buttons":{"type":"array"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/conversations/{conversationId}/window":{"get":{"summary":"Check the Instagram messaging window","tags":["Instagram"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/stats":{"get":{"summary":"Instagram message totals","tags":["Instagram"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","enum":["today","7days","month"],"example":"month"},"in":"query","name":"period","required":false,"description":"Reporting window (default month)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/interactive-messages":{"get":{"summary":"List Instagram interactive messages","tags":["Instagram"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save an Instagram interactive message","tags":["Instagram"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","enum":["buttons","quick_replies"]},"config":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/interactive-messages/{id}":{"get":{"summary":"Get an Instagram interactive message","tags":["Instagram"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an Instagram interactive message","tags":["Instagram"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","enum":["buttons","quick_replies"]},"config":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an Instagram interactive message","tags":["Instagram"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/rate-limit":{"get":{"summary":"Remaining Instagram send quota","tags":["Instagram"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/templates":{"get":{"summary":"List saved Instagram templates","tags":["Instagram"],"description":"Requires templates:read permission.","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save an Instagram template","tags":["Instagram"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","cards"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"cards":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":80},"subtitle":{"type":"string","maxLength":80},"imageUrl":{"type":"string"},"defaultActionUrl":{"type":"string"},"buttons":{"type":"array","maxItems":3,"items":{"type":"object","required":["type","title"],"properties":{"type":{"type":"string","enum":["web_url","postback"]},"title":{"type":"string","maxLength":20},"url":{"type":"string"},"payload":{"type":"string"}}}}}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/templates/{id}":{"get":{"summary":"Get a saved Instagram template","tags":["Instagram"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a saved Instagram template","tags":["Instagram"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"isActive":{"type":"boolean"},"cards":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":80},"subtitle":{"type":"string","maxLength":80},"imageUrl":{"type":"string"},"defaultActionUrl":{"type":"string"},"buttons":{"type":"array","maxItems":3,"items":{"type":"object","required":["type","title"],"properties":{"type":{"type":"string","enum":["web_url","postback"]},"title":{"type":"string","maxLength":20},"url":{"type":"string"},"payload":{"type":"string"}}}}}}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a saved Instagram template","tags":["Instagram"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/templates/{id}/detail":{"get":{"summary":"Get template detail and usage","tags":["Instagram"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/templates/{id}/send":{"post":{"summary":"Send a saved Instagram template","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId"],"properties":{"recipientId":{"type":"string","minLength":1},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/quick-replies":{"get":{"summary":"List Instagram quick replies","tags":["Instagram"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an Instagram quick reply","tags":["Instagram"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","message","quickReplies"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"message":{"type":"string","minLength":1,"maxLength":1000},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","minLength":1,"maxLength":20},"payload":{"type":"string","minLength":1,"maxLength":1000},"imageUrl":{"type":"string"}}}},"category":{"type":"string","maxLength":50}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/quick-replies/categories":{"get":{"summary":"List quick reply categories","tags":["Instagram"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/quick-replies/{id}":{"get":{"summary":"Get an Instagram quick reply","tags":["Instagram"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an Instagram quick reply","tags":["Instagram"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"message":{"type":"string","minLength":1,"maxLength":1000},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["title","payload"],"properties":{"title":{"type":"string","minLength":1,"maxLength":20},"payload":{"type":"string","minLength":1,"maxLength":1000},"imageUrl":{"type":"string"}}}},"category":{"type":"string","maxLength":50},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an Instagram quick reply","tags":["Instagram"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/ice-breakers":{"get":{"summary":"List Instagram ice breakers","tags":["Instagram"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Replace Instagram ice breakers","tags":["Instagram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["iceBreakers"],"properties":{"iceBreakers":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["question","payload"],"properties":{"question":{"type":"string","minLength":1,"maxLength":200},"payload":{"type":"string","minLength":1,"maxLength":1000}}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove all ice breakers","tags":["Instagram"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/ice-breakers/add":{"post":{"summary":"Add an ice breaker","tags":["Instagram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["question","payload"],"properties":{"question":{"type":"string","minLength":1,"maxLength":200},"payload":{"type":"string","minLength":1,"maxLength":1000}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/ice-breakers/{index}":{"put":{"summary":"Update an ice breaker","tags":["Instagram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["question","payload"],"properties":{"question":{"type":"string","minLength":1,"maxLength":200},"payload":{"type":"string","minLength":1,"maxLength":1000}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"index","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an ice breaker","tags":["Instagram"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"index","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/ice-breakers/reorder":{"post":{"summary":"Reorder ice breakers","tags":["Instagram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["newOrder"],"properties":{"newOrder":{"type":"array","items":{"type":"integer","minimum":0}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/story-mentions/config":{"get":{"summary":"Story mention auto-reply settings","tags":["Instagram"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Change story mention auto-reply settings","tags":["Instagram"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"autoReplyEnabled":{"type":"boolean"},"autoReplyMessage":{"type":"string","maxLength":1000},"autoReplyDelay":{"type":"integer","minimum":0,"maximum":60},"trackMentions":{"type":"boolean"},"notifyOnMention":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/story-mentions/stats":{"get":{"summary":"Story mention stats","tags":["Instagram"],"description":"Requires analytics:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/story-mentions/responses":{"post":{"summary":"Add a story mention reply","tags":["Instagram"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["condition","message"],"properties":{"condition":{"type":"string","enum":["follower","non_follower","verified","any"]},"message":{"type":"string","minLength":1,"maxLength":1000},"isActive":{"type":"boolean"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/story-mentions/responses/{id}":{"put":{"summary":"Update a story mention reply","tags":["Instagram"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"condition":{"type":"string","enum":["follower","non_follower","verified","any"]},"message":{"type":"string","minLength":1,"maxLength":1000},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a story mention reply","tags":["Instagram"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/":{"get":{"summary":"List Instagram campaigns","tags":["Instagram"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","enum":["DRAFT","SCHEDULED","RUNNING","PAUSED","COMPLETED","CANCELLED","FAILED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","messageType"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"messageType":{"type":"string","enum":["TEXT","TEMPLATE","IMAGE"]},"messageText":{"type":"string"},"messageContent":{"type":"string"},"templateId":{"type":"string"},"imageUrl":{"type":"string"},"messageConfig":{"type":"object"},"scheduledAt":{"type":"string","format":"date-time"},"messagesPerSecond":{"type":"number","minimum":1,"maximum":20},"recipientContactIds":{"type":"array","items":{"type":"string"}},"recipientIds":{"type":"array","items":{"type":"string"}},"recipientIGSIDs":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"lifecycleStage":{"type":"string"},"source":{"type":"string"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}":{"get":{"summary":"Get an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"messageType":{"type":"string","enum":["TEXT","TEMPLATE","IMAGE"]},"messageText":{"type":"string"},"messageContent":{"type":"string"},"templateId":{"type":"string"},"imageUrl":{"type":"string"},"messageConfig":{"type":"object"},"scheduledAt":{"type":"string","format":"date-time"},"messagesPerSecond":{"type":"number","minimum":1,"maximum":20}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/run":{"post":{"summary":"Start an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/cancel":{"post":{"summary":"Cancel an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/pause":{"post":{"summary":"Pause an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/resume":{"post":{"summary":"Resume an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/stats":{"get":{"summary":"Campaign delivery stats","tags":["Instagram"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/recipients":{"post":{"summary":"Add campaign recipients","tags":["Instagram"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string"}},"igsids":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"lifecycleStage":{"type":"string"},"source":{"type":"string"}}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List campaign recipients","tags":["Instagram"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/campaigns/{id}/duplicate":{"post":{"summary":"Duplicate an Instagram campaign","tags":["Instagram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/marketing/send":{"post":{"summary":"Send an Instagram marketing message to opted-in users","tags":["Instagram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","tag"],"properties":{"recipientId":{"type":"string"},"tag":{"type":"string"},"text":{"type":"string"},"attachment":{"type":"object","properties":{"type":{"type":"string"},"payload":{"type":"object"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/comment-automations/":{"get":{"summary":"List comment-to-DM automations","tags":["Instagram"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Rows per page, max 50 (default 20)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Auto-reply to comments on a post (public reply and/or DM)","tags":["Instagram"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channelId","mediaId"],"properties":{"channelId":{"type":"string","description":"The Instagram or Messenger channel id (GET /api/v1/me/channels)."},"mediaId":{"type":"string","description":"Post id from GET …/comment-automations/posts."},"postCaption":{"type":"string"},"postThumbnail":{"type":"string"},"postPermalink":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Reply only to comments containing one of these words; empty = every comment.","example":["price","السعر"]},"publicReplies":{"type":"array","items":{"type":"string"},"description":"Public replies under the comment; one is picked at random.","example":["Sent you a DM 📩"]},"dmMessage":{"type":"string","description":"Plain private reply (use dmConfig for rich DMs)."},"dmConfig":{"type":"object","description":"Private reply. `{type:\"text\", text}`, `{type:\"image\", imageUrl, text?}`, `{type:\"card\", title, subtitle?, imageUrl?, buttons?:[{title,url}] (max 3)}`, `{type:\"buttons\", text, buttons:[{title,url}] (1–3)}`, `{type:\"quick_replies\", text, quickReplies:[string] (1–13)}`.","example":{"type":"buttons","text":"Here is the price list","buttons":[{"title":"Open","url":"https://example.com/prices"}]}},"hideComment":{"type":"boolean","description":"Hide the original comment after replying."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/comment-automations/posts":{"get":{"summary":"List your Instagram posts","tags":["Instagram"],"description":"Requires channels:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"after","required":false,"description":"Pagination cursor from the previous page of posts."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/comment-automations/posts/{mediaId}/comments":{"get":{"summary":"List comments on an Instagram post","tags":["Instagram"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"mediaId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/comment-automations/{id}":{"get":{"summary":"Get a comment-to-DM automation","tags":["Instagram"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a comment-to-DM automation","tags":["Instagram"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channelId","mediaId"],"properties":{"channelId":{"type":"string","description":"The Instagram or Messenger channel id (GET /api/v1/me/channels)."},"mediaId":{"type":"string","description":"Post id from GET …/comment-automations/posts."},"postCaption":{"type":"string"},"postThumbnail":{"type":"string"},"postPermalink":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Reply only to comments containing one of these words; empty = every comment.","example":["price","السعر"]},"publicReplies":{"type":"array","items":{"type":"string"},"description":"Public replies under the comment; one is picked at random.","example":["Sent you a DM 📩"]},"dmMessage":{"type":"string","description":"Plain private reply (use dmConfig for rich DMs)."},"dmConfig":{"type":"object","description":"Private reply. `{type:\"text\", text}`, `{type:\"image\", imageUrl, text?}`, `{type:\"card\", title, subtitle?, imageUrl?, buttons?:[{title,url}] (max 3)}`, `{type:\"buttons\", text, buttons:[{title,url}] (1–3)}`, `{type:\"quick_replies\", text, quickReplies:[string] (1–13)}`.","example":{"type":"buttons","text":"Here is the price list","buttons":[{"title":"Open","url":"https://example.com/prices"}]}},"hideComment":{"type":"boolean","description":"Hide the original comment after replying."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a comment-to-DM automation","tags":["Instagram"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/comment-automations/{id}/toggle":{"patch":{"summary":"Turn a comment-to-DM automation on or off","tags":["Instagram"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send":{"post":{"summary":"Send a Messenger message","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","text"],"properties":{"recipientId":{"type":"string"},"text":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/tag":{"post":{"summary":"Send outside the 24-hour window with a message tag","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","text","tag","conversationId"],"additionalProperties":false,"properties":{"recipientId":{"type":"string","minLength":1,"maxLength":255},"text":{"type":"string","minLength":1,"maxLength":2000},"tag":{"type":"string","enum":["HUMAN_AGENT"]},"conversationId":{"type":"string","minLength":1,"maxLength":255}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/quick-replies":{"post":{"summary":"Send Messenger quick replies","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","text","quickReplies"],"properties":{"recipientId":{"type":"string"},"text":{"type":"string"},"quickReplies":{"type":"array"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/buttons":{"post":{"summary":"Send a Messenger button template","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","text","buttons"],"properties":{"recipientId":{"type":"string"},"text":{"type":"string"},"buttons":{"type":"array"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/media":{"post":{"summary":"Send Messenger media","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","mediaType","mediaUrl"],"properties":{"recipientId":{"type":"string"},"mediaType":{"type":"string","enum":["image","video","audio","file"]},"mediaUrl":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/carousel":{"post":{"summary":"Send a Messenger carousel","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","elements"],"properties":{"recipientId":{"type":"string"},"elements":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"image_url":{"type":"string"},"default_action":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"}}},"buttons":{"type":"array"}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/media-template":{"post":{"summary":"Send a Messenger media template","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","mediaType","mediaUrl"],"properties":{"recipientId":{"type":"string"},"mediaType":{"type":"string","enum":["image","video"]},"mediaUrl":{"type":"string"},"buttons":{"type":"array"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/send/receipt":{"post":{"summary":"Send a Messenger order receipt","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId","recipientName","orderNumber","currency","paymentMethod","summary","elements"],"properties":{"recipientId":{"type":"string"},"recipientName":{"type":"string"},"orderNumber":{"type":"string"},"currency":{"type":"string"},"paymentMethod":{"type":"string"},"orderUrl":{"type":"string"},"timestamp":{"type":"string"},"summary":{"type":"object","required":["total_cost"],"properties":{"subtotal":{"type":"number"},"shipping_cost":{"type":"number"},"total_tax":{"type":"number"},"total_cost":{"type":"number"}}},"elements":{"type":"array","items":{"type":"object","required":["title","price"],"properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"currency":{"type":"string"},"image_url":{"type":"string"}}}},"address":{"type":"object","properties":{"street_1":{"type":"string"},"street_2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/window/{conversationId}":{"get":{"summary":"Check the Messenger messaging window","tags":["Messenger"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/stats":{"get":{"summary":"Messenger message totals","tags":["Messenger"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","enum":["today","7days","month"],"example":"month"},"in":"query","name":"period","required":false,"description":"Reporting window (default month)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/analytics/summary":{"get":{"summary":"Messenger analytics summary","tags":["Messenger"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"integer","example":30},"in":"query","name":"days","required":false,"description":"Days to analyze, 1–365 (default 30)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/rate-limit":{"get":{"summary":"Remaining Messenger send quota","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/interactive-messages":{"get":{"summary":"List Messenger interactive messages","tags":["Messenger"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save a Messenger interactive message","tags":["Messenger"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","enum":["buttons","quick_replies"]},"config":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/interactive-messages/{id}":{"get":{"summary":"Get a Messenger interactive message","tags":["Messenger"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a Messenger interactive message","tags":["Messenger"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","enum":["buttons","quick_replies"]},"config":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a Messenger interactive message","tags":["Messenger"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/templates/":{"get":{"summary":"List saved Messenger templates","tags":["Messenger"],"description":"Requires templates:read permission.","parameters":[{"schema":{"type":"string","enum":["BUTTON","GENERIC","RECEIPT","MEDIA"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save a Messenger template","tags":["Messenger"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"type":{"type":"string","enum":["BUTTON","GENERIC","RECEIPT","MEDIA"]},"config":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/templates/{id}":{"get":{"summary":"Get a saved Messenger template","tags":["Messenger"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a saved Messenger template","tags":["Messenger"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"type":{"type":"string","enum":["BUTTON","GENERIC","RECEIPT","MEDIA"]},"config":{"type":"object"},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a saved Messenger template","tags":["Messenger"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/templates/{id}/send":{"post":{"summary":"Send a saved Messenger template","tags":["Messenger"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["recipientId"],"properties":{"recipientId":{"type":"string"},"variables":{"type":"object"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/templates/{id}/detail":{"get":{"summary":"Get template detail and usage","tags":["Messenger"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/templates/{id}/duplicate":{"post":{"summary":"Duplicate a Messenger template","tags":["Messenger"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/quick-replies/":{"get":{"summary":"List Messenger quick replies","tags":["Messenger"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"string"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a Messenger quick reply","tags":["Messenger"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","quickReplies"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["content_type"],"properties":{"content_type":{"type":"string","enum":["text","user_phone_number","user_email"]},"title":{"type":"string","maxLength":20},"payload":{"type":"string","maxLength":1000},"image_url":{"type":"string"}}}},"category":{"type":"string","maxLength":50}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/quick-replies/categories":{"get":{"summary":"List quick reply categories","tags":["Messenger"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/quick-replies/{id}":{"get":{"summary":"Get a Messenger quick reply","tags":["Messenger"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a Messenger quick reply","tags":["Messenger"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"quickReplies":{"type":"array","minItems":1,"maxItems":13,"items":{"type":"object","required":["content_type"],"properties":{"content_type":{"type":"string","enum":["text","user_phone_number","user_email"]},"title":{"type":"string","maxLength":20},"payload":{"type":"string","maxLength":1000},"image_url":{"type":"string"}}}},"category":{"type":"string","maxLength":50},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a Messenger quick reply","tags":["Messenger"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/quick-replies/{id}/duplicate":{"post":{"summary":"Duplicate a Messenger quick reply","tags":["Messenger"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/profile/":{"get":{"summary":"Messenger profile (greeting, menu, ice breakers)","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/profile/persistent-menu":{"get":{"summary":"Persistent menu","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Set the persistent menu","tags":["Messenger"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"},"composer_input_disabled":{"type":"boolean"},"call_to_actions":{"type":"array","maxItems":3,"items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["postback","web_url","nested"]},"title":{"type":"string","maxLength":30},"payload":{"type":"string","maxLength":1000},"url":{"type":"string"},"webview_height_ratio":{"type":"string","enum":["compact","tall","full"]},"call_to_actions":{"type":"array"}}}}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove the persistent menu","tags":["Messenger"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/profile/greeting":{"get":{"summary":"Greeting text","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Set the greeting text","tags":["Messenger"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"getStartedPayload":{"type":"string","maxLength":1000},"greetings":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string"},"text":{"type":"string","maxLength":160}}}}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove the greeting text","tags":["Messenger"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/profile/get-started":{"get":{"summary":"Get Started button","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Set the Get Started button","tags":["Messenger"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","maxLength":1000}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove the Get Started button","tags":["Messenger"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/profile/ice-breakers":{"get":{"summary":"Ice breakers","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Set ice breakers","tags":["Messenger"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ice_breakers":{"type":"array","maxItems":4,"items":{"type":"object","properties":{"id":{"type":"string"},"question":{"type":"string","maxLength":80},"payload":{"type":"string","maxLength":1000}}}}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove ice breakers","tags":["Messenger"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/":{"get":{"summary":"List Messenger campaigns","tags":["Messenger"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","enum":["DRAFT","SCHEDULED","RUNNING","PAUSED","COMPLETED","CANCELLED","FAILED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","messageType"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"messageType":{"type":"string","enum":["TEXT","TEMPLATE","QUICK_REPLIES"]},"messageText":{"type":"string"},"templateId":{"type":"string"},"quickReplySetId":{"type":"string"},"messageConfig":{"type":"object"},"scheduledAt":{"type":"string","format":"date-time"},"messagesPerSecond":{"type":"number","minimum":1,"maximum":20},"recipientContactIds":{"type":"array","items":{"type":"string"}},"recipientPSIDs":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"lifecycleStage":{"type":"string"},"source":{"type":"string"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}":{"get":{"summary":"Get a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"messageType":{"type":"string","enum":["TEXT","TEMPLATE","QUICK_REPLIES"]},"messageText":{"type":"string"},"templateId":{"type":"string"},"quickReplySetId":{"type":"string"},"messageConfig":{"type":"object"},"scheduledAt":{"type":"string","format":"date-time"},"messagesPerSecond":{"type":"number","minimum":1,"maximum":20},"messageTag":{"type":"null","enum":[null]}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/run":{"post":{"summary":"Start a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/cancel":{"post":{"summary":"Cancel a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/pause":{"post":{"summary":"Pause a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/resume":{"post":{"summary":"Resume a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/stats":{"get":{"summary":"Campaign delivery stats","tags":["Messenger"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/recipients":{"get":{"summary":"List campaign recipients","tags":["Messenger"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","example":"SENT"},"in":"query","name":"status","required":false,"description":"Delivery status, e.g. SENT."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Max rows (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add campaign recipients","tags":["Messenger"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string"}},"psids":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"lifecycleStage":{"type":"string"},"source":{"type":"string"}}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/campaigns/{id}/duplicate":{"post":{"summary":"Duplicate a Messenger campaign","tags":["Messenger"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/comment-automations/":{"get":{"summary":"List comment-to-DM automations","tags":["Messenger"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Rows per page, max 50 (default 20)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Auto-reply to comments on a Page post (public reply and/or DM)","tags":["Messenger"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channelId","mediaId"],"properties":{"channelId":{"type":"string","description":"The Instagram or Messenger channel id (GET /api/v1/me/channels)."},"mediaId":{"type":"string","description":"Post id from GET …/comment-automations/posts."},"postCaption":{"type":"string"},"postThumbnail":{"type":"string"},"postPermalink":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Reply only to comments containing one of these words; empty = every comment.","example":["price","السعر"]},"publicReplies":{"type":"array","items":{"type":"string"},"description":"Public replies under the comment; one is picked at random.","example":["Sent you a DM 📩"]},"dmMessage":{"type":"string","description":"Plain private reply (use dmConfig for rich DMs)."},"dmConfig":{"type":"object","description":"Private reply. `{type:\"text\", text}`, `{type:\"image\", imageUrl, text?}`, `{type:\"card\", title, subtitle?, imageUrl?, buttons?:[{title,url}] (max 3)}`, `{type:\"buttons\", text, buttons:[{title,url}] (1–3)}`, `{type:\"quick_replies\", text, quickReplies:[string] (1–13)}`.","example":{"type":"buttons","text":"Here is the price list","buttons":[{"title":"Open","url":"https://example.com/prices"}]}},"hideComment":{"type":"boolean","description":"Hide the original comment after replying."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/comment-automations/posts":{"get":{"summary":"List your Facebook Page posts","tags":["Messenger"],"description":"Requires channels:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"after","required":false,"description":"Pagination cursor from the previous page of posts."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/comment-automations/posts/{mediaId}/comments":{"get":{"summary":"List comments on a Page post","tags":["Messenger"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"mediaId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/comment-automations/{id}":{"get":{"summary":"Get a comment-to-DM automation","tags":["Messenger"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a comment-to-DM automation","tags":["Messenger"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channelId","mediaId"],"properties":{"channelId":{"type":"string","description":"The Instagram or Messenger channel id (GET /api/v1/me/channels)."},"mediaId":{"type":"string","description":"Post id from GET …/comment-automations/posts."},"postCaption":{"type":"string"},"postThumbnail":{"type":"string"},"postPermalink":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"},"description":"Reply only to comments containing one of these words; empty = every comment.","example":["price","السعر"]},"publicReplies":{"type":"array","items":{"type":"string"},"description":"Public replies under the comment; one is picked at random.","example":["Sent you a DM 📩"]},"dmMessage":{"type":"string","description":"Plain private reply (use dmConfig for rich DMs)."},"dmConfig":{"type":"object","description":"Private reply. `{type:\"text\", text}`, `{type:\"image\", imageUrl, text?}`, `{type:\"card\", title, subtitle?, imageUrl?, buttons?:[{title,url}] (max 3)}`, `{type:\"buttons\", text, buttons:[{title,url}] (1–3)}`, `{type:\"quick_replies\", text, quickReplies:[string] (1–13)}`.","example":{"type":"buttons","text":"Here is the price list","buttons":[{"title":"Open","url":"https://example.com/prices"}]}},"hideComment":{"type":"boolean","description":"Hide the original comment after replying."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a comment-to-DM automation","tags":["Messenger"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/comment-automations/{id}/toggle":{"patch":{"summary":"Turn a comment-to-DM automation on or off","tags":["Messenger"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send":{"post":{"summary":"Send a Telegram message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId"],"properties":{"chatId":{"type":["string","number"]},"content":{"type":"string"},"conversationId":{"type":"string"},"mediaType":{"type":"string","enum":["photo","video","document","audio","voice"]},"mediaUrl":{"type":"string"},"caption":{"type":"string"},"parseMode":{"type":"string","enum":["HTML","Markdown","MarkdownV2"]}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/inline-keyboard":{"post":{"summary":"Send a message with inline buttons","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","text"],"properties":{"chatId":{"type":["string","number"]},"text":{"type":"string"},"buttons":{"type":"array","items":{"type":"array","items":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"url":{"type":"string"},"callback_data":{"type":"string"}}}}},"inlineKeyboard":{"type":"array","items":{"type":"array","items":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"url":{"type":"string"},"callback_data":{"type":"string"}}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/reply-keyboard":{"post":{"summary":"Send a message with a reply keyboard","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","text","keyboard"],"properties":{"chatId":{"type":["string","number"]},"text":{"type":"string"},"keyboard":{"type":"array","items":{"type":"array","items":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"request_contact":{"type":"boolean"},"request_location":{"type":"boolean"}}}}},"conversationId":{"type":"string"},"resize_keyboard":{"type":"boolean"},"one_time_keyboard":{"type":"boolean"},"input_field_placeholder":{"type":"string"},"is_persistent":{"type":"boolean"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/remove-keyboard":{"post":{"summary":"Remove the reply keyboard","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","text"],"properties":{"chatId":{"type":["string","number"]},"text":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/sticker":{"post":{"summary":"Send a sticker","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","sticker"],"properties":{"chatId":{"type":["string","number"]},"sticker":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/location":{"post":{"summary":"Send a location","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","latitude","longitude"],"properties":{"chatId":{"type":["string","number"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/contact":{"post":{"summary":"Send a contact","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","phoneNumber","firstName"],"properties":{"chatId":{"type":["string","number"]},"phoneNumber":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/poll":{"post":{"summary":"Send a poll","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","question","options"],"properties":{"chatId":{"type":["string","number"]},"question":{"type":"string"},"options":{"type":"array","minItems":2,"maxItems":10,"items":{"oneOf":[{"type":"string"},{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}]}},"conversationId":{"type":"string"},"is_anonymous":{"type":"boolean"},"isAnonymous":{"type":"boolean"},"type":{"type":"string","enum":["regular","quiz"]},"allows_multiple_answers":{"type":"boolean"},"allowsMultipleAnswers":{"type":"boolean"},"correct_option_id":{"type":"number"},"correctOptionId":{"type":"number"},"explanation":{"type":"string"},"open_period":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/venue":{"post":{"summary":"Send a venue","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","latitude","longitude","title","address"],"properties":{"chatId":{"type":["string","number"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"title":{"type":"string"},"address":{"type":"string"},"foursquareId":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/dice":{"post":{"summary":"Send an animated dice","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId"],"properties":{"chatId":{"type":["string","number"]},"emoji":{"type":"string","enum":["🎲","🎯","🏀","⚽","🎳","🎰"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/animation":{"post":{"summary":"Send a GIF / animation","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","animation"],"properties":{"chatId":{"type":["string","number"]},"animation":{"type":"string"},"caption":{"type":"string"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/video-note":{"post":{"summary":"Send a round video note","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","videoNote"],"properties":{"chatId":{"type":["string","number"]},"videoNote":{"type":"string"},"duration":{"type":"number"},"length":{"type":"number"},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/invoice":{"post":{"summary":"Send an invoice","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","title","description","payload","currency","prices"],"properties":{"chatId":{"type":["string","number"]},"title":{"type":"string","maxLength":32},"description":{"type":"string","maxLength":255},"payload":{"type":"string"},"currency":{"type":"string","default":"XTR"},"prices":{"type":"array","minItems":1,"items":{"type":"object","required":["label","amount"],"properties":{"label":{"type":"string"},"amount":{"type":"number"}}}},"providerToken":{"type":"string"},"startParameter":{"type":"string"},"photoUrl":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/create-invoice-link":{"post":{"summary":"Create a payment link","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title","description","payload","currency","prices"],"properties":{"title":{"type":"string","maxLength":32},"description":{"type":"string","maxLength":255},"payload":{"type":"string"},"currency":{"type":"string","default":"XTR"},"prices":{"type":"array","minItems":1,"items":{"type":"object","required":["label","amount"],"properties":{"label":{"type":"string"},"amount":{"type":"number"}}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/forward":{"post":{"summary":"Forward a message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","fromChatId","messageId"],"properties":{"chatId":{"type":["string","number"]},"fromChatId":{"type":["string","number"]},"messageId":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/copy":{"post":{"summary":"Copy a message to another chat","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","fromChatId","messageId"],"properties":{"chatId":{"type":["string","number"]},"fromChatId":{"type":["string","number"]},"messageId":{"type":"number"},"caption":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/message":{"put":{"summary":"Edit a sent message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","messageId","text"],"properties":{"chatId":{"type":["string","number"]},"messageId":{"type":"number"},"text":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","messageId"],"properties":{"chatId":{"type":["string","number"]},"messageId":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/send/media-group":{"post":{"summary":"Send an album","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","media"],"properties":{"chatId":{"type":["string","number"]},"media":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"object","required":["type","media"],"properties":{"type":{"type":"string","enum":["photo","video","document","audio"]},"media":{"type":"string"},"caption":{"type":"string"}}}},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/chat/{chatId}":{"get":{"summary":"Get chat info","tags":["Telegram"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"chatId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/chat/{chatId}/member-count":{"get":{"summary":"Get group member count","tags":["Telegram"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"chatId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/chat/ban":{"post":{"summary":"Ban a user from a group","tags":["Telegram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","userId"],"properties":{"chatId":{"type":["string","number"]},"userId":{"type":"number"},"untilDate":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/chat/unban":{"post":{"summary":"Unban a user","tags":["Telegram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","userId"],"properties":{"chatId":{"type":["string","number"]},"userId":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/message/pin":{"post":{"summary":"Pin a message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId","messageId"],"properties":{"chatId":{"type":["string","number"]},"messageId":{"type":"number"},"disableNotification":{"type":"boolean"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/message/unpin":{"post":{"summary":"Unpin a message","tags":["Telegram"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId"],"properties":{"chatId":{"type":["string","number"]},"messageId":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/chat/invite-link":{"post":{"summary":"Create a group invite link","tags":["Telegram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatId"],"properties":{"chatId":{"type":["string","number"]},"name":{"type":"string"},"expireDate":{"type":"number"},"memberLimit":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/bot/profile":{"get":{"summary":"Bot name, description and about text","tags":["Telegram"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Change the bot name, description and about text","tags":["Telegram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"shortDescription":{"type":"string"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/commands":{"get":{"summary":"List bot commands","tags":["Telegram"],"description":"Requires channels:read permission.","parameters":[{"schema":{"type":"string","example":"en"},"in":"query","name":"languageCode","required":false,"description":"Command set for this language (omit for the default)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Set bot commands","tags":["Telegram"],"description":"Requires channels:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["commands"],"properties":{"commands":{"type":"array","maxItems":100,"items":{"type":"object","required":["command","description"],"properties":{"command":{"type":"string"},"description":{"type":"string"}}}},"languageCode":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove bot commands","tags":["Telegram"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/stats":{"get":{"summary":"Telegram message totals","tags":["Telegram"],"description":"Requires analytics:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns":{"get":{"summary":"List Telegram campaigns","tags":["Telegram"],"description":"Requires campaigns:read permission.","parameters":[{"schema":{"type":"string","enum":["all","DRAFT","SCHEDULED","RUNNING","PAUSED","COMPLETED","CANCELLED","FAILED"]},"in":"query","name":"status","required":false,"description":"\"all\" or omitted returns every status."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"New arrivals"},"messageType":{"type":"string","description":"TEXT by default.","example":"TEXT"},"messageContent":{"type":"string","description":"Message text (when not using a template)."},"templateId":{"type":"string","description":"A Telegram template id instead of messageContent."},"recipientIds":{"type":"array","items":{"type":"string"},"description":"Contact ids; contacts without a Telegram chat are skipped."},"scheduledAt":{"type":"string","format":"date-time"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns/{id}":{"get":{"summary":"Get a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns/{id}/send":{"post":{"summary":"Start a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns/{id}/cancel":{"post":{"summary":"Cancel a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns/{id}/pause":{"post":{"summary":"Pause a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/campaigns/{id}/resume":{"post":{"summary":"Resume a Telegram campaign","tags":["Telegram"],"description":"Requires campaigns:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/templates/":{"get":{"summary":"List Telegram templates","tags":["Telegram"],"description":"Requires templates:read permission.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"isActive","required":false},{"schema":{"type":"string","enum":["TEXT","MEDIA","BUTTONS","POLL","RICH"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name or content."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"pageSize","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save a Telegram template","tags":["Telegram"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","content"],"properties":{"name":{"type":"string","example":"Welcome"},"type":{"type":"string","enum":["TEXT","MEDIA","BUTTONS","POLL","RICH"],"example":"TEXT"},"content":{"type":"string","example":"Welcome to our store 👋"},"config":{"type":"object","description":"Type-specific settings (media, inline buttons, poll options)."},"description":{"type":["string","null"]},"clientId":{"type":["string","null"],"description":"Your idempotency id: sending the same clientId again returns the existing template."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/templates/{id}":{"get":{"summary":"Get a Telegram template","tags":["Telegram"],"description":"Requires templates:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a Telegram template","tags":["Telegram"],"description":"Requires templates:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","content"],"properties":{"name":{"type":"string","example":"Welcome"},"type":{"type":"string","enum":["TEXT","MEDIA","BUTTONS","POLL","RICH"],"example":"TEXT"},"content":{"type":"string","example":"Welcome to our store 👋"},"config":{"type":"object","description":"Type-specific settings (media, inline buttons, poll options)."},"description":{"type":["string","null"]},"clientId":{"type":["string","null"],"description":"Your idempotency id: sending the same clientId again returns the existing template."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a Telegram template","tags":["Telegram"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/templates/{id}/duplicate":{"post":{"summary":"Duplicate a Telegram template","tags":["Telegram"],"description":"Requires templates:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/templates/{id}/use":{"post":{"summary":"Record a Telegram template use","tags":["Telegram"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/channels":{"get":{"summary":"List channels available for agent assignment","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/presets/personalities":{"get":{"summary":"List agent personality presets","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/presets/agent-types":{"get":{"summary":"List agent type presets","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents":{"get":{"summary":"List AI agents","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"boolean","example":false},"in":"query","name":"includeInactive","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Default 50."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an AI agent","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","mission"],"properties":{"name":{"type":"string","description":"Agent name (max 50 chars).","example":"Layla"},"mission":{"type":"string","description":"Agent mission statement (max 500 chars).","example":"Answer product questions and qualify leads."},"avatar":{"type":"string","description":"Avatar image URL, or null."},"gender":{"type":"string","enum":["MALE","FEMALE","NEUTRAL"],"description":"Or null."},"personalityType":{"type":"string","description":"Personality preset key, or null."},"personality":{"type":"string","description":"Free-text personality description, or null."},"agentType":{"type":"string","enum":["GENERAL","SALES","SUPPORT","REAL_ESTATE","HEALTHCARE","EDUCATION","ECOMMERCE","HOSPITALITY","CUSTOM"],"description":"Or null."},"instructions":{"type":"string","description":"Extra instructions (max 2000 chars), or null."},"primaryLanguage":{"type":"string","description":"Primary reply language, or null.","example":"ar"},"responseStyle":{"type":"string","enum":["CONCISE","BALANCED","DETAILED","FRIENDLY","FORMAL"],"description":"Or null."},"maxTokens":{"type":"number","description":"100-4000, or null."},"temperature":{"type":"number","description":"0-2, or null."},"isDefault":{"type":"boolean","description":"Or null."},"assignedChannels":{"type":"array","items":{"type":"string"},"description":"Channel IDs this agent handles, or null."},"transferStrategy":{"type":"string","enum":["LEAST_BUSY","ROUND_ROBIN","RANDOM","SPECIFIC_AGENT"],"description":"Or null."},"transferAgentId":{"type":"string","description":"Target user ID for handoff, or null."},"sendProductImages":{"type":"boolean","description":"Or null."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/stats":{"get":{"summary":"Get AI agent stats","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/insights/schedule":{"get":{"summary":"Get the conversation insights schedule","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Set the conversation insights schedule","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["enabled","cadence","timezone"],"properties":{"enabled":{"type":"boolean","description":"Whether scheduled insight reports are on."},"cadence":{"type":"string","enum":["DAILY","CUSTOM_DAYS","WEEKLY","MONTHLY"],"example":"WEEKLY"},"intervalDays":{"type":"number","description":"1-31, used when cadence is CUSTOM_DAYS. Defaults to 2."},"dayOfWeek":{"type":"number","description":"0-6, used when cadence is WEEKLY. Defaults to 1."},"dayOfMonth":{"type":"number","description":"1-28, used when cadence is MONTHLY. Defaults to 1."},"scheduleHour":{"type":"number","description":"0-23, hour of day to run. Defaults to 4."},"timezone":{"type":"string","description":"IANA timezone identifier.","example":"Asia/Riyadh"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/insights/reports":{"get":{"summary":"List conversation insight reports","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Default 20."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/insights/reports/{reportId}":{"get":{"summary":"Get a conversation insight report","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"reportId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/insights/run":{"post":{"summary":"Queue a manual conversation insight report","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lookbackDays":{"type":"number","description":"1-365. Defaults to 7.","example":7},"mode":{"type":"string","enum":["QUICK_SAMPLE","FULL_COVERAGE"],"description":"Defaults to QUICK_SAMPLE."}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/historical-learning":{"get":{"summary":"List historical learning profiles","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/historical-learning":{"put":{"summary":"Enable or disable historical learning for an agent","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Enable or disable historical learning for this agent."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/historical-learning/run":{"post":{"summary":"Run historical learning analysis for an agent","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lookbackDays":{"type":"number","description":"1-365. Defaults to 365.","example":90}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}":{"get":{"summary":"Get an AI agent","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an AI agent","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Agent name (max 50 chars)."},"mission":{"type":"string","description":"Agent mission statement (max 500 chars)."},"avatar":{"type":"string","description":"Avatar image URL, or null."},"gender":{"type":"string","enum":["MALE","FEMALE","NEUTRAL"],"description":"Or null."},"personalityType":{"type":"string","description":"Personality preset key, or null."},"personality":{"type":"string","description":"Free-text personality description, or null."},"agentType":{"type":"string","enum":["GENERAL","SALES","SUPPORT","REAL_ESTATE","HEALTHCARE","EDUCATION","ECOMMERCE","HOSPITALITY","CUSTOM"],"description":"Or null."},"instructions":{"type":"string","description":"Extra instructions (max 2000 chars), or null."},"primaryLanguage":{"type":"string","description":"Primary reply language, or null.","example":"ar"},"responseStyle":{"type":"string","enum":["CONCISE","BALANCED","DETAILED","FRIENDLY","FORMAL"],"description":"Or null."},"maxTokens":{"type":"number","description":"100-4000, or null."},"temperature":{"type":"number","description":"0-2, or null."},"isDefault":{"type":"boolean","description":"Or null."},"assignedChannels":{"type":"array","items":{"type":"string"},"description":"Channel IDs this agent handles, or null."},"transferStrategy":{"type":"string","enum":["LEAST_BUSY","ROUND_ROBIN","RANDOM","SPECIFIC_AGENT"],"description":"Or null."},"transferAgentId":{"type":"string","description":"Target user ID for handoff, or null."},"sendProductImages":{"type":"boolean","description":"Or null."},"isActive":{"type":"boolean","description":"Whether the agent is active, or null."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an AI agent","tags":["AI Agents"],"description":"Requires ai:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/knowledge":{"get":{"summary":"List agent knowledge entries","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean","example":false},"in":"query","name":"includeInactive","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Default 50."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/knowledge/categories":{"get":{"summary":"List agent knowledge categories","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/knowledge/{knowledgeId}":{"get":{"summary":"Get an agent knowledge entry","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"knowledgeId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an agent knowledge entry","tags":["AI Agents"],"description":"Requires ai:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"knowledgeId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/upload/info":{"get":{"summary":"Get supported knowledge upload file types","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/logs":{"get":{"summary":"List agent event logs","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"agentId","required":false},{"schema":{"type":"string","enum":["MESSAGE_RECEIVED","MESSAGE_SENT","KNOWLEDGE_SEARCH","KNOWLEDGE_HIT","KNOWLEDGE_MISS","FUNCTION_CALLED","FUNCTION_SUCCESS","FUNCTION_FAILED","TASK_CREATED","LEAD_ASSIGNED","APPOINTMENT_BOOKED","ORDER_CREATED","TICKET_CREATED","HANDOFF_REQUESTED","HANDOFF_COMPLETED","ERROR_OCCURRED","RATE_LIMITED","QUOTA_EXCEEDED"]},"in":"query","name":"eventType","required":false,"description":"Must be one of the listed values."},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false,"description":"ISO date."},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false,"description":"ISO date."},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Default 50."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/logs/stats":{"get":{"summary":"Get agent log stats","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"agentId","required":false,"description":"One agent instead of all."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/functions/builtin":{"get":{"summary":"List built-in agent functions","tags":["AI Agents"],"description":"Requires ai:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/functions":{"get":{"summary":"List agent functions","tags":["AI Agents"],"description":"Requires ai:read permission.","parameters":[{"schema":{"type":"boolean","example":false},"in":"query","name":"includeDisabled","required":false},{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an agent function","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","displayName","description","parameters"],"properties":{"name":{"type":"string","description":"Lowercase with underscores (max 50 chars).","example":"check_order_status"},"displayName":{"type":"string","description":"Human-readable name (max 100 chars).","example":"Check order status"},"description":{"type":"string","description":"What the function does (max 500 chars); shown to the model as the function description."},"parameters":{"type":"object","description":"JSON Schema object describing the function parameters."},"executorType":{"type":"string","enum":["INTERNAL","WEBHOOK","AUTOMATION"],"description":"Defaults to INTERNAL."},"executorConfig":{"type":"object","description":"Executor-specific config (e.g. webhook URL)."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/functions/{functionId}":{"put":{"summary":"Update an agent function","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Lowercase with underscores (max 50 chars).","example":"check_order_status"},"displayName":{"type":"string","description":"Human-readable name (max 100 chars).","example":"Check order status"},"description":{"type":"string","description":"What the function does (max 500 chars); shown to the model as the function description."},"parameters":{"type":"object","description":"JSON Schema object describing the function parameters."},"executorType":{"type":"string","enum":["INTERNAL","WEBHOOK","AUTOMATION"],"description":"Defaults to INTERNAL."},"executorConfig":{"type":"object","description":"Executor-specific config (e.g. webhook URL)."},"isEnabled":{"type":"boolean","description":"Whether the function is enabled."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"functionId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an agent function","tags":["AI Agents"],"description":"Requires ai:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"functionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/{agentId}/functions/{functionId}/toggle":{"patch":{"summary":"Enable or disable an agent function","tags":["AI Agents"],"description":"Requires ai:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["isEnabled"],"properties":{"isEnabled":{"type":"boolean","description":"Enable or disable the function.","example":true}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"functionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ai-agents/functions/sync":{"post":{"summary":"Sync built-in functions to all agents","tags":["AI Agents"],"description":"Requires ai:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/csat/config":{"get":{"summary":"Get the CSAT survey config","tags":["CSAT"],"description":"Requires analytics:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/csat/analytics":{"get":{"summary":"Get CSAT analytics for a period","tags":["CSAT"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","enum":["7d","30d","90d"],"example":"30d"},"in":"query","name":"period","required":false,"description":"Reporting window (default 30d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/team":{"get":{"summary":"List team members","tags":["Team"],"description":"Requires team:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name or email."},{"schema":{"type":"string","enum":["COMPANY_ADMIN","MANAGER","AGENT","VIEWER"]},"in":"query","name":"role","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"isActive","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Page size (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/team/{userId}":{"get":{"summary":"Get a team member","tags":["Team"],"description":"Requires team:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"userId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/team/stats":{"get":{"summary":"Get team headcount and role breakdown","tags":["Team"],"description":"Requires team:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/company":{"get":{"summary":"Get company profile and settings","tags":["Team"],"description":"Requires team:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations":{"get":{"summary":"List inbox conversations","tags":["Conversations"],"description":"Requires conversations:read permission.","parameters":[{"schema":{"type":"string","example":"OPEN"},"in":"query","name":"status","required":false,"description":"Conversation status, e.g. OPEN or CLOSED."},{"schema":{"type":"string","example":"WHATSAPP"},"in":"query","name":"channelType","required":false,"description":"Channel type, e.g. WHATSAPP or INSTAGRAM."},{"schema":{"type":"string"},"in":"query","name":"assignedToId","required":false,"description":"Only conversations assigned to this user."},{"schema":{"type":"boolean","example":true},"in":"query","name":"unassigned","required":false,"description":"Only unassigned conversations (overrides assignedToId)."},{"schema":{"type":"boolean","example":true},"in":"query","name":"unread","required":false,"description":"Only conversations with unread messages."},{"schema":{"type":"boolean","example":true},"in":"query","name":"aiEnabled","required":false,"description":"Filter by whether the AI agent is on."},{"schema":{"type":"string","example":"ahmed"},"in":"query","name":"search","required":false,"description":"Contact name or phone."},{"schema":{"type":"string","example":"tag_1,tag_2"},"in":"query","name":"tagIds","required":false,"description":"Comma-separated contact tag ids."},{"schema":{"type":"string","example":"2026-09-01T00:00:00Z"},"in":"query","name":"dateFrom","required":false,"description":"ISO date; last message on or after."},{"schema":{"type":"string","example":"2026-09-16T00:00:00Z"},"in":"query","name":"dateTo","required":false,"description":"ISO date; last message on or before."},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Max rows, up to 1000 (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}":{"get":{"summary":"Get a conversation","tags":["Conversations"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/messages":{"get":{"summary":"List messages in a conversation","tags":["Conversations"],"description":"Requires messages:read permission.","parameters":[{"schema":{"type":"integer","example":100},"in":"query","name":"limit","required":false,"description":"Max messages, up to 200 (default 100)."},{"schema":{"type":"string"},"in":"query","name":"before","required":false,"description":"ISO date cursor: messages older than this (scroll back)."},{"schema":{"type":"string"},"in":"query","name":"after","required":false,"description":"ISO date cursor: messages newer than this. Wins over before."},{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Reply in a conversation on any channel","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Message text. Required when type is \"text\"; optional caption for media types.","example":"مرحباً، كيف يمكنني مساعدتك؟"},"type":{"type":"string","enum":["text","image","video","audio","document"],"description":"Message type. Defaults to \"text\".","example":"text"},"fileData":{"type":"string","description":"Base64-encoded file content. Required when type is image, video, audio or document."},"fileName":{"type":"string","description":"Original file name for media messages.","example":"invoice.pdf"},"mimeType":{"type":"string","description":"MIME type of the media file.","example":"image/jpeg"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/window":{"get":{"summary":"Check the 24-hour messaging window","tags":["Conversations"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/assign":{"patch":{"summary":"Assign a conversation to an agent","tags":["Conversations"],"description":"Requires conversations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedToId":{"type":"string","description":"User ID to assign the conversation to, or null to unassign. Must belong to the same company.","example":"usr_2n4k1x9p0q"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/status":{"patch":{"summary":"Change conversation status","tags":["Conversations"],"description":"Requires conversations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","pending","resolved","closed"],"description":"New conversation status.","example":"resolved"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/labels":{"patch":{"summary":"Set conversation labels","tags":["Conversations"],"description":"Requires conversations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"},"description":"Full list of labels to set on the conversation (replaces existing labels).","example":["vip","needs-followup"]}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/inbox/conversations/{conversationId}/notes/list":{"get":{"summary":"List internal notes","tags":["Conversations"],"description":"Requires conversations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add an internal note","tags":["Conversations"],"description":"Requires conversations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Internal note text, visible only to your team.","example":"Customer asked about bulk pricing — follow up Thursday."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/":{"get":{"summary":"List workflows","tags":["Automations"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","TELEGRAM","WEB","SMS","TIKTOK"]},"in":"query","name":"channelType","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name or description."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"1–100 (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a workflow","tags":["Automations"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Cart recovery on WhatsApp"},"description":{"type":"string"},"channelType":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","TELEGRAM","WEB","SMS","TIKTOK"],"example":"WHATSAPP"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/import":{"post":{"summary":"Import a workflow document","tags":["Automations"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["formatVersion","triggerType","nodes","edges"],"properties":{"formatVersion":{"type":"string","description":"The formatVersion from GET …/:workflowId/export."},"name":{"type":"string"},"description":{"type":"string"},"channelType":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","TELEGRAM","WEB","SMS","TIKTOK"]},"triggerType":{"type":"string","description":"The event that starts the workflow — any webhook platform event name, e.g. \"whatsapp.message.received\", \"ecommerce.cart.abandoned\", \"web_event.received\".","example":"ecommerce.cart.abandoned"},"triggerConfig":{"type":"object","description":"Trigger filters (channel, keywords, event fields)."},"nodes":{"type":"array","items":{"type":"object"},"description":"Each node: `{ id, type, position?, label?, config?, version? }`. `type` is a registered node type (e.g. \"whatsapp.send.text\", \"time.delay\", \"ticket.create\"); `config` is validated per type on publish. Max 500. Easiest start: export a workflow built in the dashboard (GET …/:workflowId/export) and edit it."},"edges":{"type":"array","items":{"type":"object"},"description":"Each edge: `{ id, source, target, sourceHandle? }` referencing node ids. Max 1000."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}":{"get":{"summary":"Get a workflow","tags":["Automations"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a workflow","tags":["Automations"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/graph":{"get":{"summary":"Get a workflow with its nodes and edges","tags":["Automations"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/export":{"get":{"summary":"Export a workflow as a portable document","tags":["Automations"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/status":{"patch":{"summary":"Turn a workflow on, pause or archive it","tags":["Automations"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"],"description":"ACTIVE runs the published version; PAUSED stops new runs.","example":"ACTIVE"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/publish":{"post":{"summary":"Validate and publish a workflow graph","tags":["Automations"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["triggerType","nodes","edges"],"properties":{"triggerType":{"type":"string","description":"The event that starts the workflow — any webhook platform event name, e.g. \"whatsapp.message.received\", \"ecommerce.cart.abandoned\", \"web_event.received\".","example":"ecommerce.cart.abandoned"},"triggerConfig":{"type":"object","description":"Trigger filters (channel, keywords, event fields)."},"nodes":{"type":"array","items":{"type":"object"},"description":"Each node: `{ id, type, position?, label?, config?, version? }`. `type` is a registered node type (e.g. \"whatsapp.send.text\", \"time.delay\", \"ticket.create\"); `config` is validated per type on publish. Max 500. Easiest start: export a workflow built in the dashboard (GET …/:workflowId/export) and edit it."},"edges":{"type":"array","items":{"type":"object"},"description":"Each edge: `{ id, source, target, sourceHandle? }` referencing node ids. Max 1000."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/runs":{"get":{"summary":"List runs (execution history)","tags":["Automations"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"string","enum":["PENDING","RUNNING","WAITING","SUCCEEDED","FAILED","CANCELLED"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"1–100 (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/runs/{runId}":{"get":{"summary":"Get one run with its steps","tags":["Automations"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true},{"schema":{"type":"string"},"in":"path","name":"runId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/stats":{"get":{"summary":"Run statistics for a workflow","tags":["Automations"],"description":"Requires analytics:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/sample-events":{"get":{"summary":"Recent real events this workflow’s trigger would receive","tags":["Automations"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Event type to sample (default: the workflow's trigger), e.g. whatsapp.message.received."},{"schema":{"type":"integer","example":5},"in":"query","name":"limit","required":false,"description":"1–10 (default 5)."},{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/test-run":{"post":{"summary":"Dry-run a workflow on a sample event (nothing is sent)","tags":["Automations"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","description":"Defaults to the most recent conversation."},"sampleMessage":{"type":"string","description":"Text injected into the sample trigger event. Dry run: nothing is sent and no AI is billed.","example":"do you ship to Jeddah?"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/automations-v2/{workflowId}/test-arm":{"post":{"summary":"Capture the next real trigger event as a sample (60 seconds)","tags":["Automations"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"workflowId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/send-saved":{"post":{"summary":"Send a saved interactive message into a conversation","tags":["Messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["conversationId","messageId","channel"],"properties":{"conversationId":{"type":"string"},"messageId":{"type":"string","description":"Id of a saved interactive message (GET /api/v1/interactive-messages)."},"channel":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","WEB"],"example":"WHATSAPP"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/":{"get":{"summary":"List saved interactive messages","tags":["Interactive messages"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string","enum":["BUTTONS","LIST","LOCATION","CONTACT","CTA_URL","LOCATION_REQUEST"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Defaults to active only."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name, description or tags."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Save an interactive message","tags":["Interactive messages"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","type","config"],"properties":{"name":{"type":"string","example":"Main menu"},"description":{"type":"string"},"type":{"type":"string","enum":["BUTTONS","LIST","LOCATION","CONTACT","CTA_URL","LOCATION_REQUEST"]},"config":{"type":"object","description":"BUTTONS: `{body, header?, headerImage?, footer?, buttons:[{id,title}]}` (max 3). LIST: `{body, buttonText, sections:[{title, rows:[{id,title,description?}]}]}`. LOCATION: `{latitude, longitude, name?, address?}`. CONTACT: WhatsApp contact card. CTA_URL: `{body, buttonText, url}`. LOCATION_REQUEST: `{body}`.","example":{"body":"How can we help?","buttons":[{"id":"orders","title":"My orders"},{"id":"agent","title":"Talk to us"}]}},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/stats":{"get":{"summary":"Saved interactive message stats","tags":["Interactive messages"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/categories":{"get":{"summary":"List library categories","tags":["Interactive messages"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/{id}":{"get":{"summary":"Get a saved interactive message","tags":["Interactive messages"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a saved interactive message","tags":["Interactive messages"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a saved interactive message","tags":["Interactive messages"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/interactive-messages/{id}/duplicate":{"post":{"summary":"Duplicate a saved interactive message","tags":["Interactive messages"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Main menu (copy)"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/quick-replies/":{"get":{"summary":"List quick replies","tags":["Quick Replies"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Filter by active state."},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a quick reply","tags":["Quick Replies"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["shortcut","label","text"],"properties":{"shortcut":{"type":"string","description":"Slash-command shortcut, unique per company.","example":"/refund"},"label":{"type":"string","description":"Display label.","example":"Refund policy"},"text":{"type":"string","description":"Reply text to insert."},"category":{"type":"string","description":"Category to group under."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/quick-replies/categories":{"get":{"summary":"List quick reply categories","tags":["Quick Replies"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/quick-replies/{id}":{"get":{"summary":"Get a quick reply","tags":["Quick Replies"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a quick reply","tags":["Quick Replies"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"shortcut":{"type":"string","description":"Slash-command shortcut."},"label":{"type":"string","description":"Display label."},"text":{"type":"string","description":"Reply text."},"category":{"type":"string","description":"Category to group under."},"isActive":{"type":"boolean","description":"Whether the quick reply is active."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a quick reply","tags":["Quick Replies"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/quick-replies/{id}/use":{"post":{"summary":"Record quick reply usage","tags":["Quick Replies"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-contacts/":{"get":{"summary":"List saved contacts","tags":["Saved Contacts"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Filter by active state."},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a saved contact","tags":["Saved Contacts"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","formattedName"],"properties":{"name":{"type":"string","description":"Contact display name.","example":"Ahmed Al-Otaibi"},"formattedName":{"type":"string","description":"Formatted display name used in the vCard.","example":"Ahmed Al-Otaibi - Sales"},"phones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME","CELL","MAIN"]},"phone":{"type":"string","example":"966500000000"}}}},"emails":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"email":{"type":"string"}}}},"organization":{"type":"string","description":"Company/organization name."},"title":{"type":"string","description":"Job title."},"addresses":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}}}},"urls":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"url":{"type":"string"}}}},"category":{"type":"string","description":"Category to group under."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-contacts/categories":{"get":{"summary":"List saved contact categories","tags":["Saved Contacts"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-contacts/{id}":{"get":{"summary":"Get a saved contact","tags":["Saved Contacts"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a saved contact","tags":["Saved Contacts"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Contact display name."},"formattedName":{"type":"string","description":"Formatted display name used in the vCard."},"phones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME","CELL","MAIN"]},"phone":{"type":"string","example":"966500000000"}}}},"emails":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"email":{"type":"string"}}}},"organization":{"type":"string","description":"Company/organization name."},"title":{"type":"string","description":"Job title."},"addresses":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}}}},"urls":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WORK","HOME"]},"url":{"type":"string"}}}},"category":{"type":"string","description":"Category to group under."},"isActive":{"type":"boolean","description":"Whether the saved contact is active."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a saved contact","tags":["Saved Contacts"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-contacts/{id}/whatsapp":{"get":{"summary":"Get a saved contact in WhatsApp vCard format","tags":["Saved Contacts"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-contacts/{id}/use":{"post":{"summary":"Record saved contact usage","tags":["Saved Contacts"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-locations/":{"get":{"summary":"List saved locations","tags":["Saved Locations"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Filter by active state."},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a saved location","tags":["Saved Locations"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","latitude","longitude"],"properties":{"name":{"type":"string","description":"Location name.","example":"Main Warehouse"},"address":{"type":"string","description":"Street address."},"latitude":{"type":"number","example":24.7136},"longitude":{"type":"number","example":46.6753},"category":{"type":"string","description":"Category to group under."},"isActive":{"type":"boolean","description":"Defaults to true."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-locations/categories":{"get":{"summary":"List saved location categories","tags":["Saved Locations"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-locations/{id}":{"get":{"summary":"Get a saved location","tags":["Saved Locations"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a saved location","tags":["Saved Locations"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Location name."},"address":{"type":"string","description":"Street address."},"latitude":{"type":"number"},"longitude":{"type":"number"},"category":{"type":"string","description":"Category to group under."},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a saved location","tags":["Saved Locations"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-locations/{id}/whatsapp":{"get":{"summary":"Get a saved location in WhatsApp location format","tags":["Saved Locations"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/saved-locations/{id}/use":{"post":{"summary":"Record saved location usage","tags":["Saved Locations"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/sync":{"post":{"summary":"Sync from WooCommerce (?full=true for a full reconcile)","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/sync/customers":{"post":{"summary":"Sync WooCommerce customers","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/sync/orders":{"post":{"summary":"Sync WooCommerce orders","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/sync/products":{"post":{"summary":"Sync WooCommerce products","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/abandoned-carts":{"get":{"summary":"WooCommerce abandoned carts","tags":["Stores"],"description":"Requires ecommerce:read permission.","parameters":[{"schema":{"type":"string","enum":["ABANDONED","RECOVERED","EXPIRED"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"per_page","required":false,"description":"Up to 100 (default 20)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/abandoned-carts/stats":{"get":{"summary":"WooCommerce cart recovery stats","tags":["Stores"],"description":"Requires ecommerce:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/woocommerce/abandoned-carts/{id}/recover":{"patch":{"summary":"Mark a WooCommerce cart recovered","tags":["Stores"],"description":"Requires ecommerce:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"number","description":"The order that recovered the cart, if known."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shopify/config":{"get":{"summary":"Shopify connection status (no secrets)","tags":["Stores"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shopify/sync":{"post":{"summary":"Sync everything from Shopify","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shopify/sync/customers":{"post":{"summary":"Sync Shopify customers","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shopify/sync/orders":{"post":{"summary":"Sync Shopify orders","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shopify/sync/products":{"post":{"summary":"Sync Shopify products","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/salla/config":{"get":{"summary":"Salla connection status (no secrets)","tags":["Stores"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/salla/abandoned-carts":{"get":{"summary":"Salla abandoned carts","tags":["Stores"],"description":"Requires ecommerce:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Up to 100 (default 20)."},{"schema":{"type":"string","example":"ABANDONED"},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/salla/abandoned-carts/stats":{"get":{"summary":"Salla cart recovery stats","tags":["Stores"],"description":"Requires ecommerce:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/salla/abandoned-carts/{id}/recover":{"patch":{"summary":"Mark a Salla cart recovered","tags":["Stores"],"description":"Requires ecommerce:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"number","description":"The order that recovered the cart, if known."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/salla/sync":{"post":{"summary":"Sync from Salla","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/zid/config":{"get":{"summary":"Zid connection status (no secrets)","tags":["Stores"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/zid/sync":{"post":{"summary":"Sync orders from Zid","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/zid/abandoned-carts":{"get":{"summary":"Zid abandoned carts","tags":["Stores"],"description":"Requires ecommerce:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Up to 100 (default 20)."},{"schema":{"type":"string","enum":["ABANDONED","RECOVERED","COMPLETED"]},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/easy-orders/config":{"get":{"summary":"EasyOrders connection status (no secrets)","tags":["Stores"],"description":"Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/easy-orders/sync":{"post":{"summary":"Sync from EasyOrders","tags":["Stores"],"description":"Requires channels:write permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/events":{"get":{"summary":"List webhook event types","tags":["Webhooks"],"description":"Requires webhooks:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/":{"post":{"summary":"Register a webhook","tags":["Webhooks"],"description":"Requires webhooks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","description":"Webhook name.","example":"Order sync"},"url":{"type":"string","description":"HTTPS endpoint to receive events. Must be a public, non-private-network URL.","example":"https://example.com/webhooks/inboxy"},"events":{"type":"array","items":{"type":"string"},"description":"Events to receive: exact names from GET /api/v1/webhooks/events, \"*\" for everything, or a prefix wildcard such as \"whatsapp.*\", \"ecommerce.order.*\" or \"ticket.*\".","example":["message.received","ecommerce.order.*","ticket.created"]},"maxRetries":{"type":"number","description":"Max delivery retry attempts."},"fieldExclusions":{"type":"array","items":{"type":"string"},"description":"Dot-separated payload paths to omit from delivered payloads (max 20)."},"consecutiveFailureThreshold":{"type":"number","description":"Consecutive failures (5-1000) before the webhook auto-pauses."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List webhooks","tags":["Webhooks"],"description":"Requires webhooks:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}":{"get":{"summary":"Get a webhook","tags":["Webhooks"],"description":"Requires webhooks:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a webhook","tags":["Webhooks"],"description":"Requires webhooks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Webhook name."},"url":{"type":"string","description":"HTTPS endpoint to receive events."},"events":{"type":"array","items":{"type":"string"},"description":"Events to receive: exact names from GET /api/v1/webhooks/events, \"*\" for everything, or a prefix wildcard such as \"whatsapp.*\", \"ecommerce.order.*\" or \"ticket.*\".","example":["message.received","ecommerce.order.*","ticket.created"]},"status":{"type":"string","enum":["ACTIVE","PAUSED","FAILED"],"description":"Webhook status."},"maxRetries":{"type":"number","description":"Max delivery retry attempts."},"fieldExclusions":{"type":"array","items":{"type":"string"},"description":"Dot-separated payload paths to omit from delivered payloads (max 20)."},"consecutiveFailureThreshold":{"type":"number","description":"Consecutive failures (5-1000) before the webhook auto-pauses."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a webhook","tags":["Webhooks"],"description":"Requires webhooks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}/test":{"post":{"summary":"Send a test delivery","tags":["Webhooks"],"description":"Requires webhooks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}/logs":{"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"description":"Requires webhooks:read permission.","parameters":[{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Max deliveries (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}/secret":{"get":{"summary":"Reveal the signing secret (to verify X-Inboxy-Signature)","tags":["Webhooks"],"description":"Requires webhooks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}/regenerate-secret":{"post":{"summary":"Rotate the signing secret","tags":["Webhooks"],"description":"Requires webhooks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhooks/{webhookId}/replay":{"post":{"summary":"Redeliver the failed deliveries of the last 7 days","tags":["Webhooks"],"description":"Requires webhooks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"webhookId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/":{"get":{"summary":"List orders","tags":["Orders"],"description":"Requires orders:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"contactId","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Comma-separated: PENDING, CONFIRMED, PROCESSING, COMPLETED, CANCELLED, REFUNDED."},{"schema":{"type":"string"},"in":"query","name":"paymentStatus","required":false,"description":"Comma-separated: UNPAID, PARTIALLY_PAID, PAID, REFUNDED."},{"schema":{"type":"string"},"in":"query","name":"fulfillmentStatus","required":false,"description":"Comma-separated: UNFULFILLED, PARTIALLY_FULFILLED, SHIPPED, DELIVERED, FULFILLED, RETURNED."},{"schema":{"type":"string"},"in":"query","name":"externalSource","required":false,"description":"Comma-separated: WHATSAPP_COMMERCE, WOOCOMMERCE, SHOPIFY, SALLA, ZID, EASY_ORDERS, MANUAL, AI_AGENT, WEB_EVENT."},{"schema":{"type":"number"},"in":"query","name":"minTotal","required":false},{"schema":{"type":"number"},"in":"query","name":"maxTotal","required":false},{"schema":{"type":"string"},"in":"query","name":"dateAfter","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"dateBefore","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Order number or customer."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["orderDate","total","createdAt"]},"in":"query","name":"sortBy","required":false},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc"},"in":"query","name":"sortOrder","required":false,"description":"Sort direction."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create an order","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["contactId","orderNumber","externalSource","subtotal","total"],"properties":{"contactId":{"type":"string","description":"Contact this order belongs to."},"externalId":{"type":"string","description":"ID of this order in the external source system."},"externalSource":{"type":"string","enum":["WHATSAPP_COMMERCE","WOOCOMMERCE","SHOPIFY","SALLA","ZID","EASY_ORDERS","MANUAL","AI_AGENT","WEB_EVENT"],"description":"Where the order came from.","example":"MANUAL"},"orderNumber":{"type":"string","description":"Human-readable order number.","example":"ORD-1042"},"status":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","COMPLETED","CANCELLED","REFUNDED"],"description":"Order status. Defaults to PENDING."},"subtotal":{"type":"number","description":"Subtotal before tax/shipping/discount.","example":199},"tax":{"type":"number","description":"Tax amount."},"shipping":{"type":"number","description":"Shipping cost."},"discount":{"type":"number","description":"Discount amount."},"total":{"type":"number","description":"Order total.","example":199},"currency":{"type":"string","description":"ISO currency code.","example":"SAR"},"paymentMethod":{"type":"string","description":"Payment method used.","example":"cod"},"paymentStatus":{"type":"string","enum":["UNPAID","PARTIALLY_PAID","PAID","REFUNDED"],"description":"Payment status. Defaults to UNPAID."},"fulfillmentStatus":{"type":"string","enum":["UNFULFILLED","PARTIALLY_FULFILLED","SHIPPED","DELIVERED","FULFILLED","RETURNED"],"description":"Fulfillment status. Defaults to UNFULFILLED."},"billingAddress":{"type":"object","description":"Billing address fields."},"shippingAddress":{"type":"object","description":"Shipping address fields."},"customerNote":{"type":"string","description":"Note from the customer."},"internalNote":{"type":"string","description":"Internal-only note."},"orderDate":{"type":"string","description":"Order date, ISO 8601. Defaults to now."},"metadata":{"type":"object","description":"Arbitrary key/value metadata."},"items":{"type":"array","description":"Line items: { name, quantity, unitPrice, totalPrice, sku?, productId?, imageUrl?, variant? }."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/stats":{"get":{"summary":"Order statistics","tags":["Orders"],"description":"Requires orders:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}":{"get":{"summary":"Get an order","tags":["Orders"],"description":"Requires orders:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an order","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","COMPLETED","CANCELLED","REFUNDED"],"description":"Order status."},"paymentStatus":{"type":"string","enum":["UNPAID","PARTIALLY_PAID","PAID","REFUNDED"],"description":"Payment status."},"paymentMethod":{"type":"string","description":"Payment method used."},"fulfillmentStatus":{"type":"string","enum":["UNFULFILLED","PARTIALLY_FULFILLED","SHIPPED","DELIVERED","FULFILLED","RETURNED"],"description":"Fulfillment status."},"shippingAddress":{"type":"object","description":"Shipping address fields."},"billingAddress":{"type":"object","description":"Billing address fields."},"customerNote":{"type":"string","description":"Note from the customer."},"internalNote":{"type":"string","description":"Internal-only note."},"metadata":{"type":"object","description":"Arbitrary key/value metadata."},"confirmationStatus":{"type":"string","enum":["UNCONFIRMED","PENDING_CONFIRMATION","CONFIRMED","FAILED","CANCELLED_BY_CUSTOMER"],"description":"Order confirmation status."},"confirmationChannel":{"type":"string","description":"Channel the confirmation was collected on."},"trackingNumber":{"type":"string","description":"Shipment tracking number."},"trackingCarrier":{"type":"string","description":"Shipment carrier name."},"trackingUrl":{"type":"string","description":"Shipment tracking URL."},"cancellationReason":{"type":"string","description":"Reason for cancellation."},"refundReason":{"type":"string","description":"Reason for refund."},"refundAmount":{"type":"number","description":"Amount refunded."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an order","tags":["Orders"],"description":"Requires orders:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/status":{"patch":{"summary":"Change order status","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","COMPLETED","CANCELLED","REFUNDED"],"description":"New order status.","example":"CONFIRMED"},"cancellationReason":{"type":"string","description":"Reason for cancellation, stored when status is CANCELLED."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/payment":{"patch":{"summary":"Change payment status","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paymentStatus":{"type":"string","enum":["UNPAID","PARTIALLY_PAID","PAID","REFUNDED"],"description":"New payment status. Setting PAID auto-captures the token owner as paidByUserId.","example":"PAID"},"paymentMethod":{"type":"string","description":"Payment method used.","example":"card"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/fulfillment":{"patch":{"summary":"Change fulfillment status","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["fulfillmentStatus"],"properties":{"fulfillmentStatus":{"type":"string","enum":["UNFULFILLED","PARTIALLY_FULFILLED","SHIPPED","DELIVERED","FULFILLED","RETURNED"],"description":"New fulfillment status.","example":"SHIPPED"},"trackingNumber":{"type":"string","description":"Shipment tracking number."},"trackingCarrier":{"type":"string","description":"Shipment carrier name.","example":"Aramex"},"trackingUrl":{"type":"string","description":"Shipment tracking URL."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/confirmation":{"patch":{"summary":"Set the order confirmation status","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["confirmationStatus"],"properties":{"confirmationStatus":{"type":"string","enum":["UNCONFIRMED","PENDING_CONFIRMATION","CONFIRMED","FAILED","CANCELLED_BY_CUSTOMER"],"example":"CONFIRMED"},"confirmationChannel":{"type":"string","example":"whatsapp"},"confirmationMessageId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/push-to-platform":{"post":{"summary":"Push an Inboxy-created order to the connected store (Shopify, Salla, WooCommerce)","tags":["Orders"],"description":"Requires orders:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/messages":{"get":{"summary":"Messages linked to an order","tags":["Orders"],"description":"Requires orders:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Link a message to an order","tags":["Orders"],"description":"Requires orders:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["messageId","type"],"properties":{"messageId":{"type":"string"},"type":{"type":"string","enum":["CONFIRMATION","STATUS_UPDATE","PAYMENT_REMINDER","SHIPPING_UPDATE","CUSTOM"],"example":"SHIPPING_UPDATE"},"metadata":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/confirmation-thread":{"get":{"summary":"The WhatsApp confirmation exchange for an order","tags":["Orders"],"description":"Requires orders:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ecommerce/overview":{"get":{"summary":"Store KPIs: orders, revenue, store connectivity","tags":["Stores"],"description":"Requires ecommerce:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ecommerce/customers/":{"get":{"summary":"List store customers across platforms","tags":["Stores"],"description":"Requires ecommerce:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":25},"in":"query","name":"pageSize","required":false,"description":"Up to 100 (default 25)."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name, email or phone."},{"schema":{"type":"string"},"in":"query","name":"platform","required":false,"description":"Comma-separated: SHOPIFY, SALLA, WOOCOMMERCE, ZID, EASYORDERS."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ecommerce/customers/{id}":{"get":{"summary":"Get a store customer with orders","tags":["Stores"],"description":"Requires ecommerce:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/":{"get":{"summary":"List catalog cards (products and services ready to send)","tags":["Products and services"],"description":"Requires products:read permission.","parameters":[{"schema":{"type":"string","enum":["product","service"]},"in":"query","name":"itemType","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (24 cards per page)."},{"schema":{"type":"string","enum":["ar","en"]},"in":"query","name":"language","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/status":{"get":{"summary":"Store sync state and card readiness","tags":["Products and services"],"description":"Requires products:read permission.","parameters":[{"schema":{"type":"string","enum":["product","service"]},"in":"query","name":"itemType","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/sync":{"post":{"summary":"Sync the catalog from a connected store","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["shopify","salla","zid","woocommerce","easy-orders"],"example":"shopify"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/{itemType}/{itemId}":{"get":{"summary":"Preview one catalog card","tags":["Products and services"],"description":"Requires products:read permission.","parameters":[{"schema":{"type":"string","enum":["ar","en"]},"in":"query","name":"language","required":false},{"schema":{"type":"string"},"in":"path","name":"itemType","required":true},{"schema":{"type":"string"},"in":"path","name":"itemId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/send/whatsapp":{"post":{"summary":"Send a catalog card on WhatsApp","tags":["Products and services"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["itemType","itemId","language","conversationId"],"properties":{"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string"},"language":{"type":"string","enum":["ar","en"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/send/messenger":{"post":{"summary":"Send a catalog card on Messenger","tags":["Products and services"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["itemType","itemId","language","conversationId"],"properties":{"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string"},"language":{"type":"string","enum":["ar","en"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/send/instagram":{"post":{"summary":"Send a catalog card on Instagram","tags":["Products and services"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["itemType","itemId","language","conversationId"],"properties":{"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string"},"language":{"type":"string","enum":["ar","en"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/send/web":{"post":{"summary":"Send a catalog card in the website chat","tags":["Products and services"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["itemType","itemId","language","conversationId"],"properties":{"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string"},"language":{"type":"string","enum":["ar","en"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/catalog-cards/send/telegram":{"post":{"summary":"Send a catalog card on Telegram","tags":["Products and services"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["itemType","itemId","language","conversationId"],"properties":{"itemType":{"type":"string","enum":["product","service"]},"itemId":{"type":"string"},"language":{"type":"string","enum":["ar","en"]},"conversationId":{"type":"string"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/stats":{"get":{"summary":"Product statistics","tags":["Products and services"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/merge":{"post":{"summary":"Merge a duplicate product into another","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["keepId","deleteId"],"properties":{"keepId":{"type":"string","description":"Product to keep."},"deleteId":{"type":"string","description":"Duplicate to delete; its references move to keepId."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/import-from-url/save":{"post":{"summary":"Save extracted products","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Wireless charger"},"description":{"type":"string"},"price":{"type":"number","example":129.99},"currency":{"type":"string","example":"SAR"},"imageUrl":{"type":"string"}}}},"defaultCurrency":{"type":"string","example":"SAR"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/categories":{"get":{"summary":"List product categories","tags":["Products"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a product category","tags":["Products"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Category name.","example":"Electronics"},"description":{"type":"string","description":"Category description."},"sortOrder":{"type":"number","description":"Sort order among categories."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/categories/{id}":{"put":{"summary":"Update a product category","tags":["Products and services"],"description":"Requires products:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a product category","tags":["Products and services"],"description":"Requires products:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/":{"get":{"summary":"List products","tags":["Products and services"],"description":"Requires products:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name or SKU."},{"schema":{"type":"string"},"in":"query","name":"categoryId","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Filter by active state."},{"schema":{"type":"string","example":"SHOPIFY"},"in":"query","name":"externalSource","required":false},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","example":"createdAt"},"in":"query","name":"sortBy","required":false},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc"},"in":"query","name":"sortOrder","required":false,"description":"Sort direction."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a product","tags":["Products"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string","description":"Product name.","example":"Wireless Charger"},"price":{"type":"number","description":"Price in the product currency.","example":129.99},"description":{"type":"string","description":"Product description."},"sku":{"type":"string","description":"Stock keeping unit. Must be unique per company."},"currency":{"type":"string","description":"ISO currency code.","example":"SAR"},"images":{"type":"array","items":{"type":"string"},"description":"Image URLs."},"isActive":{"type":"boolean","description":"Whether the product is active/visible. Defaults to true."},"stockQuantity":{"type":"number","description":"Stock on hand, or null for unlimited/untracked."},"categoryId":{"type":"string","description":"Existing category ID."},"newCategoryName":{"type":"string","description":"Create a new category with this name instead of using categoryId."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/{id}":{"get":{"summary":"Get a product","tags":["Products and services"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a product","tags":["Products"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Product name.","example":"Wireless Charger"},"price":{"type":"number","description":"Price in the product currency.","example":129.99},"description":{"type":"string","description":"Product description."},"sku":{"type":"string","description":"Stock keeping unit. Must be unique per company."},"currency":{"type":"string","description":"ISO currency code.","example":"SAR"},"images":{"type":"array","items":{"type":"string"},"description":"Image URLs."},"isActive":{"type":"boolean","description":"Whether the product is active/visible. Defaults to true."},"stockQuantity":{"type":"number","description":"Stock on hand, or null for unlimited/untracked."},"categoryId":{"type":"string","description":"Existing category ID."},"newCategoryName":{"type":"string","description":"Create a new category with this name instead of using categoryId."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a product","tags":["Products"],"description":"Requires products:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/services/stats":{"get":{"summary":"Service statistics","tags":["Products and services"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/services/categories":{"get":{"summary":"List service categories","tags":["Products and services"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a service category","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"sortOrder":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/services/categories/{id}":{"put":{"summary":"Update a service category","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"sortOrder":{"type":"number"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a service category","tags":["Products and services"],"description":"Requires products:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/services/":{"get":{"summary":"List services","tags":["Products and services"],"description":"Requires products:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"categoryId","required":false},{"schema":{"type":"boolean","example":true},"in":"query","name":"isActive","required":false,"description":"Filter by active state."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","example":"createdAt"},"in":"query","name":"sortBy","required":false},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc"},"in":"query","name":"sortOrder","required":false,"description":"Sort direction."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a service","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string","example":"Home cleaning (2h)"},"price":{"type":"number","example":199},"description":{"type":"string"},"currency":{"type":"string","example":"SAR"},"images":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"duration":{"type":["number","null"],"description":"Minutes."},"categoryId":{"type":"string"},"newCategoryName":{"type":"string","description":"Create a category with this name instead of categoryId."},"metadata":{"type":"object"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/services/{id}":{"get":{"summary":"Get a service","tags":["Products and services"],"description":"Requires products:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a service","tags":["Products and services"],"description":"Requires products:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Home cleaning (2h)"},"price":{"type":"number","example":199},"description":{"type":"string"},"currency":{"type":"string","example":"SAR"},"images":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"duration":{"type":["number","null"],"description":"Minutes."},"categoryId":{"type":"string"},"newCategoryName":{"type":"string","description":"Create a category with this name instead of categoryId."},"metadata":{"type":"object"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a service","tags":["Products and services"],"description":"Requires products:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/":{"post":{"summary":"Create an integration your website posts events to","tags":["Web events"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","authType"],"properties":{"name":{"type":"string","example":"Landing page form"},"description":{"type":"string"},"authType":{"type":"string","enum":["HMAC_SHA256","API_KEY"],"description":"How your site authenticates when it posts events to POST /api/webhook/web-events/:integrationId — an `X-Webhook-Signature` HMAC-SHA256 of the raw body, or the secret in `X-Api-Key`. The secret is shown in the dashboard."},"autoCreateContact":{"type":"boolean","description":"Create a contact when an event matches none."},"contactMapping":{"type":"object","description":"`{ phoneField, emailField, nameField?, autoCreate, enrichFields?, displayColumns? }` — which JSON fields identify the contact.","example":{"phoneField":"customer.phone","emailField":"customer.email","nameField":"customer.name","autoCreate":true}},"isEnabled":{"type":"boolean","description":"Update only."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List web event integrations","tags":["Web events"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}":{"get":{"summary":"Get a web event integration","tags":["Web events"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update an integration","tags":["Web events"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","authType"],"properties":{"name":{"type":"string","example":"Landing page form"},"description":{"type":"string"},"authType":{"type":"string","enum":["HMAC_SHA256","API_KEY"],"description":"How your site authenticates when it posts events to POST /api/webhook/web-events/:integrationId — an `X-Webhook-Signature` HMAC-SHA256 of the raw body, or the secret in `X-Api-Key`. The secret is shown in the dashboard."},"autoCreateContact":{"type":"boolean","description":"Create a contact when an event matches none."},"contactMapping":{"type":"object","description":"`{ phoneField, emailField, nameField?, autoCreate, enrichFields?, displayColumns? }` — which JSON fields identify the contact.","example":{"phoneField":"customer.phone","emailField":"customer.email","nameField":"customer.name","autoCreate":true}},"isEnabled":{"type":"boolean","description":"Update only."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an integration","tags":["Web events"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/toggle":{"patch":{"summary":"Enable or disable an integration","tags":["Web events"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/event-types":{"post":{"summary":"Declare an event type","tags":["Web events"],"description":"Requires automations:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"signup_completed"},"description":{"type":"string"},"fieldSchema":{"type":"object","description":"Expected payload fields, for variable pickers."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/event-types/{typeId}":{"delete":{"summary":"Remove an event type","tags":["Web events"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"typeId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/logs":{"get":{"summary":"List received events","tags":["Web events"],"description":"Requires automations:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Up to 100 (default 50)."},{"schema":{"type":"string","enum":["RECEIVED","PROCESSING","COMPLETED","FAILED","SKIPPED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false,"description":"ISO date."},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false,"description":"ISO date."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/logs/{logId}":{"get":{"summary":"Get one received event","tags":["Web events"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"logId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/variables":{"get":{"summary":"Variables this integration exposes to automations and templates","tags":["Web events"],"description":"Requires automations:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/web-events/{id}/test":{"post":{"summary":"Send a test event through the integration","tags":["Web events"],"description":"Requires automations:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/stats":{"get":{"summary":"Get lead pipeline stats","tags":["Leads"],"description":"Requires leads:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/pipeline":{"get":{"summary":"Get the lead pipeline","tags":["Leads"],"description":"Requires leads:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string","example":"HOT_LEAD"},"in":"query","name":"label","required":false},{"schema":{"type":"string"},"in":"query","name":"assignedAgentId","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/list":{"get":{"summary":"List leads (paginated table view)","tags":["Leads"],"description":"Requires leads:read permission.","parameters":[{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Name, email, company or phone."},{"schema":{"type":"string"},"in":"query","name":"statusId","required":false,"description":"Lead status id (GET /leads/statuses)."},{"schema":{"type":"integer","example":2},"in":"query","name":"priority","required":false,"description":"0 low … 3 urgent."},{"schema":{"type":"string"},"in":"query","name":"assignedAgentId","required":false},{"schema":{"type":"string","example":"website"},"in":"query","name":"source","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/suggest":{"post":{"summary":"AI-suggest lead fields from a conversation","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation to analyze. One of conversationId or contactId is required."},"contactId":{"type":"string","description":"Contact whose latest conversation to analyze, if conversationId is omitted."}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/move":{"post":{"summary":"Move a lead to a stage","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stage"],"properties":{"stage":{"type":"string","enum":["NEW","CONTACTED","QUALIFIED","NEGOTIATION","WON","LOST"],"description":"Pipeline stage to move the lead to.","example":"QUALIFIED"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/win":{"post":{"summary":"Mark a lead won","tags":["Leads"],"description":"Requires leads:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/lose":{"post":{"summary":"Mark a lead lost","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Reason the lead was lost."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/assign":{"post":{"summary":"Assign a lead","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"User ID to assign the lead to, or null to unassign."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/statuses":{"get":{"summary":"List lead statuses","tags":["Leads"],"description":"Requires leads:read permission.","parameters":[{"schema":{"type":"boolean","example":false},"in":"query","name":"includeInactive","required":false,"description":"Include disabled statuses."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a lead status","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["label"],"properties":{"label":{"type":"string","description":"Status label (max 60 chars).","example":"Negotiating"},"labelAr":{"type":"string","description":"Arabic label (max 60 chars), or null."},"color":{"type":"string","description":"Hex color, e.g. #3bc1a8.","example":"#3bc1a8"},"bgColor":{"type":"string","description":"Hex background color, or null.","example":"#dbeafe"},"icon":{"type":"string","description":"Icon identifier, or null."},"isQualified":{"type":"boolean","description":"Whether this status counts as qualified."},"isFinal":{"type":"boolean","description":"Whether this status is a terminal pipeline stage."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/statuses/reorder":{"patch":{"summary":"Reorder lead statuses","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["orderedIds"],"properties":{"orderedIds":{"type":"array","items":{"type":"string"},"description":"Full ordered list of lead status IDs."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/statuses/{statusId}":{"patch":{"summary":"Update a lead status","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Status label (max 60 chars)."},"labelAr":{"type":"string","description":"Arabic label, or null."},"color":{"type":"string","description":"Hex color."},"bgColor":{"type":"string","description":"Hex background color, or null."},"icon":{"type":"string","description":"Icon identifier, or null."},"isQualified":{"type":"boolean"},"isFinal":{"type":"boolean"},"isActive":{"type":"boolean"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"statusId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a lead status","tags":["Leads"],"description":"Requires leads:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"statusId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/status":{"patch":{"summary":"Set lead status","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["statusId"],"properties":{"statusId":{"type":"string","description":"ID of one of the company's configured lead statuses (GET /leads/statuses)."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/rating":{"patch":{"summary":"Set lead star rating","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["rating"],"properties":{"rating":{"type":"number","description":"1-5, or null to clear.","example":5}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/priority":{"patch":{"summary":"Set lead priority","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["priority"],"properties":{"priority":{"type":"number","description":"0 (low) to 3 (urgent), or null to clear.","example":2}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/feedback":{"get":{"summary":"List the feedback thread on a lead","tags":["Leads"],"description":"Requires leads:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add a lead feedback entry","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"Feedback text (max 5000 chars).","example":"Very responsive, asked for a discount."},"rating":{"type":"number","description":"1-5, optional."},"type":{"type":"string","enum":["POSITIVE","NEUTRAL","NEGATIVE"],"description":"Defaults to NEUTRAL."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/follow-up":{"post":{"summary":"Schedule a lead follow-up task","tags":["Leads"],"description":"Requires leads:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title","dueDate"],"properties":{"title":{"type":"string","description":"Follow-up task title.","example":"Call back about pricing"},"dueDate":{"type":"string","description":"Due date, ISO 8601."},"description":{"type":"string","description":"Optional description."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}/follow-ups":{"get":{"summary":"List lead follow-up tasks","tags":["Leads"],"description":"Requires leads:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/leads/{id}":{"get":{"summary":"Get a lead","tags":["Leads"],"description":"Requires leads:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/top-performers":{"get":{"summary":"Top Instagram templates and replies","tags":["Instagram"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/instagram/volume-timeline":{"get":{"summary":"Instagram message volume over time","tags":["Instagram"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/top-performers":{"get":{"summary":"Top Messenger templates and replies","tags":["Messenger"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/messenger/volume-timeline":{"get":{"summary":"Messenger message volume over time","tags":["Messenger"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/top-performers":{"get":{"summary":"Top Telegram templates","tags":["Telegram"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/telegram/volume-timeline":{"get":{"summary":"Telegram message volume over time","tags":["Telegram"],"description":"Requires analytics:read permission.","parameters":[{"schema":{"type":"string","example":"7d"},"in":"query","name":"window","required":false,"description":"Lookback window as \"<n>d\", 1–90 days (default 7d)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/media/":{"get":{"summary":"List media library files","tags":["Media"],"description":"Requires library:read permission.","parameters":[{"schema":{"type":"string","enum":["IMAGE","VIDEO","DOCUMENT","AUDIO"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"File name."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["createdAt","name","size","usageCount"]},"in":"query","name":"sort","required":false},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc"},"in":"query","name":"order","required":false,"description":"Sort direction."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/media/stats":{"get":{"summary":"Get media library stats","tags":["Media"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/media/{id}":{"get":{"summary":"Get a media file","tags":["Media"],"description":"Requires library:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Rename a media file or set its AI-accessibility","tags":["Media"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name."},"aiAccessible":{"type":"boolean","description":"Whether the AI agent may reference this file."},"aiDescription":{"type":"string","description":"Description shown to the AI agent, or null to clear."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a media file","tags":["Media"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/media/bulk-delete":{"post":{"summary":"Bulk delete media files","tags":["Media"],"description":"Requires library:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"description":"Media IDs to delete."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/media/{id}/use":{"post":{"summary":"Record media file usage","tags":["Media"],"description":"Requires library:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/":{"get":{"summary":"List tasks","tags":["Tasks"],"description":"Requires tasks:read permission.","parameters":[{"schema":{"type":"string","enum":["TODO","IN_PROGRESS","COMPLETED","CANCELLED"],"example":"TODO"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["FOLLOW_UP","CALLBACK","SEND_INFO","ORDER_INQUIRY","SUPPORT","OTHER","SALES","ONBOARDING","FEEDBACK","REMINDER"],"example":"FOLLOW_UP"},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Page size (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"query","name":"assignedToId","required":false},{"schema":{"type":"string"},"in":"query","name":"contactId","required":false},{"schema":{"type":"string"},"in":"query","name":"conversationId","required":false},{"schema":{"type":"string","enum":["MANUAL","AI","AUTOMATION"]},"in":"query","name":"source","required":false},{"schema":{"type":"string"},"in":"query","name":"dueDateFrom","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"dueDateTo","required":false,"description":"ISO date-time."},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Title."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a task","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Task title.","example":"Follow up on invoice #4521"},"description":{"type":"string","description":"Task description."},"type":{"type":"string","enum":["FOLLOW_UP","CALLBACK","SEND_INFO","ORDER_INQUIRY","SUPPORT","OTHER","SALES","ONBOARDING","FEEDBACK","REMINDER"],"description":"Task type.","example":"FOLLOW_UP"},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"description":"Task priority. Defaults to NORMAL.","example":"NORMAL"},"contactId":{"type":"string","description":"Contact this task relates to, or null to clear."},"conversationId":{"type":"string","description":"Conversation this task originated from, or null to clear."},"assignedToId":{"type":"string","description":"User ID to assign the task to, or null to unassign."},"dueDate":{"type":"string","description":"Due date, ISO 8601, or null to clear."},"reminderAt":{"type":"string","description":"Reminder time, ISO 8601, or null to clear."},"recurrence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"],"description":"Recurrence rule, or null for a one-off task."},"source":{"type":"string","enum":["MANUAL","AI","AUTOMATION"],"description":"Where the task came from. Defaults to MANUAL."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/stats":{"get":{"summary":"Get task stats","tags":["Tasks"],"description":"Requires tasks:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/my":{"get":{"summary":"List tasks assigned to the token owner","tags":["Tasks"],"description":"Requires tasks:read permission.","parameters":[{"schema":{"type":"string","enum":["TODO","IN_PROGRESS","COMPLETED","CANCELLED"],"example":"TODO"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["FOLLOW_UP","CALLBACK","SEND_INFO","ORDER_INQUIRY","SUPPORT","OTHER","SALES","ONBOARDING","FEEDBACK","REMINDER"],"example":"FOLLOW_UP"},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Page size (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/contact/{contactId}":{"get":{"summary":"List tasks for a contact","tags":["Tasks"],"description":"Requires tasks:read permission.","parameters":[{"schema":{"type":"string","enum":["TODO","IN_PROGRESS","COMPLETED","CANCELLED"],"example":"TODO"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["FOLLOW_UP","CALLBACK","SEND_INFO","ORDER_INQUIRY","SUPPORT","OTHER","SALES","ONBOARDING","FEEDBACK","REMINDER"],"example":"FOLLOW_UP"},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"Page size (default 50)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"contactId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}":{"get":{"summary":"Get a task","tags":["Tasks"],"description":"Requires tasks:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a task","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Task title. Cannot be set to empty."},"description":{"type":"string","description":"Task description."},"type":{"type":"string","enum":["FOLLOW_UP","CALLBACK","SEND_INFO","ORDER_INQUIRY","SUPPORT","OTHER","SALES","ONBOARDING","FEEDBACK","REMINDER"],"description":"Task type.","example":"FOLLOW_UP"},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"description":"Task priority. Defaults to NORMAL.","example":"NORMAL"},"contactId":{"type":"string","description":"Contact this task relates to, or null to clear."},"conversationId":{"type":"string","description":"Conversation this task originated from, or null to clear."},"assignedToId":{"type":"string","description":"User ID to assign the task to, or null to unassign."},"dueDate":{"type":"string","description":"Due date, ISO 8601, or null to clear."},"reminderAt":{"type":"string","description":"Reminder time, ISO 8601, or null to clear."},"recurrence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"],"description":"Recurrence rule, or null for a one-off task."},"status":{"type":"string","enum":["TODO","IN_PROGRESS","COMPLETED","CANCELLED"],"description":"Task status.","example":"IN_PROGRESS"}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a task","tags":["Tasks"],"description":"Requires tasks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}/complete":{"post":{"summary":"Mark a task complete","tags":["Tasks"],"description":"Requires tasks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}/assign":{"post":{"summary":"Assign a task","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedToId":{"type":"string","description":"User ID to assign the task to, or null to unassign."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}/subtasks":{"get":{"summary":"List checklist items on a task","tags":["Tasks"],"description":"Requires tasks:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add a checklist item to a task","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Checklist item text.","example":"Confirm shipping address"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/subtasks/{subtaskId}":{"patch":{"summary":"Toggle a checklist item","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"boolean","description":"Whether the checklist item is done. Defaults to false.","example":true}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"subtaskId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a checklist item","tags":["Tasks"],"description":"Requires tasks:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"subtaskId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}/comments":{"get":{"summary":"List task comments","tags":["Tasks"],"description":"Requires tasks:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add a task comment","tags":["Tasks"],"description":"Requires tasks:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Comment text.","example":"Called the client, waiting on approval."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/":{"get":{"summary":"List tickets","tags":["Tickets"],"description":"Requires tickets:read permission.","parameters":[{"schema":{"type":"string","enum":["OPEN","IN_PROGRESS","CLOSED"],"example":"OPEN"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Page size (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Ticket type (GET /tickets/types)."},{"schema":{"type":"string"},"in":"query","name":"assignedToId","required":false},{"schema":{"type":"string"},"in":"query","name":"contactId","required":false},{"schema":{"type":"string","example":"refund"},"in":"query","name":"search","required":false,"description":"Subject."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["subject"],"properties":{"subject":{"type":"string","description":"Ticket subject.","example":"Order #1042 arrived damaged"},"description":{"type":"string","description":"Ticket description."},"type":{"type":"string","description":"Ticket type slug (see GET /tickets/types), e.g. \"order\".","example":"order"},"typeId":{"type":"string","description":"Ticket type ID (see GET /tickets/types)."},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"description":"Ticket priority. Defaults to NORMAL.","example":"NORMAL"},"contactId":{"type":"string","description":"Contact this ticket is about."},"assignedToId":{"type":"string","description":"User ID to assign the ticket to."},"conversationId":{"type":"string","description":"Conversation this ticket originated from."},"dueDate":{"type":"string","description":"Due date, ISO 8601."},"source":{"type":"string","description":"Where the ticket came from."},"tags":{"type":"array","items":{"type":"string"},"description":"Free-text tags."},"phone":{"type":"string","description":"Contact phone number, used to find/create a contact when contactId is not supplied. One of contactId or phone is required.","example":"966500000000"}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/stats":{"get":{"summary":"Get ticket stats","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/my":{"get":{"summary":"List tickets assigned to the token owner","tags":["Tickets"],"description":"Requires tickets:read permission.","parameters":[{"schema":{"type":"string","enum":["OPEN","IN_PROGRESS","CLOSED"],"example":"OPEN"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Page size (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/contact/{contactId}":{"get":{"summary":"List tickets for a contact","tags":["Tickets"],"description":"Requires tickets:read permission.","parameters":[{"schema":{"type":"string","enum":["OPEN","IN_PROGRESS","CLOSED"],"example":"OPEN"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"example":"HIGH"},"in":"query","name":"priority","required":false},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Page size (default 20)."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."},{"schema":{"type":"string"},"in":"path","name":"contactId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/types":{"get":{"summary":"List ticket types","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a ticket type","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Ticket type name.","example":"Warranty claim"},"color":{"type":"string","description":"Display color."},"icon":{"type":"string","description":"Icon identifier."},"isActive":{"type":"boolean","description":"Defaults to true."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/types/{typeId}":{"put":{"summary":"Update a ticket type","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Ticket type name."},"color":{"type":"string","description":"Display color."},"icon":{"type":"string","description":"Icon identifier."},"isActive":{"type":"boolean"},"order":{"type":"number","description":"Sort order."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"typeId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a ticket type","tags":["Tickets"],"description":"Requires tickets:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"typeId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}":{"get":{"summary":"Get a ticket","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"Ticket subject.","example":"Order #1042 arrived damaged"},"description":{"type":"string","description":"Ticket description."},"type":{"type":"string","description":"Ticket type slug (see GET /tickets/types), e.g. \"order\".","example":"order"},"typeId":{"type":"string","description":"Ticket type ID (see GET /tickets/types)."},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"description":"Ticket priority. Defaults to NORMAL.","example":"NORMAL"},"contactId":{"type":"string","description":"Contact this ticket is about."},"assignedToId":{"type":"string","description":"User ID to assign the ticket to."},"conversationId":{"type":"string","description":"Conversation this ticket originated from."},"dueDate":{"type":"string","description":"Due date, ISO 8601."},"source":{"type":"string","description":"Where the ticket came from."},"tags":{"type":"array","items":{"type":"string"},"description":"Free-text tags."},"status":{"type":"string","enum":["OPEN","IN_PROGRESS","CLOSED"],"description":"Ticket status."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/status":{"patch":{"summary":"Change ticket status","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["OPEN","IN_PROGRESS","CLOSED"],"description":"New ticket status.","example":"IN_PROGRESS"}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/assign":{"post":{"summary":"Assign a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedToId":{"type":"string","description":"User ID to assign the ticket to, or null to unassign."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/close":{"post":{"summary":"Close a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/comments":{"get":{"summary":"List ticket comments","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Comment on a ticket","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Comment text."},"isInternal":{"type":"boolean","description":"Internal-only comment, hidden from the customer. Defaults to false.","example":true}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/attachments":{"get":{"summary":"List ticket attachments","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Add a ticket attachment (URL reference, not an upload)","tags":["Tickets"],"description":"Requires tickets:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url","name"],"properties":{"url":{"type":"string","description":"File URL, already uploaded elsewhere (e.g. the media library).","example":"https://cdn.inboxy.chat/files/invoice.pdf"},"name":{"type":"string","description":"Original file name.","example":"invoice.pdf"},"mimeType":{"type":"string","description":"MIME type.","example":"application/pdf"},"size":{"type":"number","description":"File size in bytes."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/attachments/{attachmentId}":{"delete":{"summary":"Delete a ticket attachment","tags":["Tickets"],"description":"Requires tickets:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"attachmentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tickets/{id}/activity":{"get":{"summary":"Get the ticket audit trail","tags":["Tickets"],"description":"Requires tickets:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/":{"post":{"summary":"Create a meeting","tags":["Meetings"],"description":"Requires meetings:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["reason","type","startTime","startTimeLocal","timezone","durationMinutes"],"properties":{"reason":{"type":"string","description":"Meeting reason/title.","example":"Product demo"},"type":{"type":"string","enum":["ONLINE","OFFLINE"],"description":"Meeting type.","example":"ONLINE"},"startTime":{"type":"string","description":"Start time, ISO 8601 UTC.","example":"2026-09-20T10:00:00.000Z"},"startTimeLocal":{"type":"string","description":"Start time as picked locally (no TZ offset), ISO 8601.","example":"2026-09-20T13:00:00"},"timezone":{"type":"string","description":"IANA timezone identifier.","example":"Asia/Riyadh"},"durationMinutes":{"type":"number","description":"Duration in minutes.","example":30},"contactId":{"type":"string","description":"Associated contact."},"link":{"type":"string","description":"Meeting link, for ONLINE meetings."},"location":{"type":"string","description":"Physical location, for OFFLINE meetings."},"notes":{"type":"string","description":"Free-text notes."},"attendees":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["TEAM","EXTERNAL"],"description":"TEAM attendees require userId; EXTERNAL attendees need at least one of name/email/phone."},"userId":{"type":"string","description":"Required for TEAM attendees."},"name":{"type":"string","description":"For EXTERNAL attendees."},"email":{"type":"string","description":"For EXTERNAL attendees."},"phone":{"type":"string","description":"For EXTERNAL attendees.","example":"966500000000"}}},"description":"Team members and/or external attendees."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/week":{"get":{"summary":"List meetings in a calendar week","tags":["Meetings"],"description":"Requires meetings:read permission.","parameters":[{"schema":{"type":"string","example":"2026-09-20"},"in":"query","name":"date","required":true,"description":"Any date in the week to return (ISO date)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/contact/{contactId}":{"get":{"summary":"List meetings for a contact","tags":["Meetings"],"description":"Requires meetings:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/{id}":{"get":{"summary":"Get a meeting","tags":["Meetings"],"description":"Requires meetings:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a meeting","tags":["Meetings"],"description":"Requires meetings:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Meeting reason/title."},"type":{"type":"string","enum":["ONLINE","OFFLINE"]},"startTime":{"type":"string","description":"ISO 8601 UTC."},"startTimeLocal":{"type":"string","description":"ISO 8601 local."},"timezone":{"type":"string","description":"IANA timezone identifier."},"durationMinutes":{"type":"number"},"contactId":{"type":"string","description":"Or null to clear."},"link":{"type":"string","description":"Or null to clear."},"location":{"type":"string","description":"Or null to clear."},"notes":{"type":"string","description":"Or null to clear."},"attendees":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["TEAM","EXTERNAL"],"description":"TEAM attendees require userId; EXTERNAL attendees need at least one of name/email/phone."},"userId":{"type":"string","description":"Required for TEAM attendees."},"name":{"type":"string","description":"For EXTERNAL attendees."},"email":{"type":"string","description":"For EXTERNAL attendees."},"phone":{"type":"string","description":"For EXTERNAL attendees.","example":"966500000000"}}}}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a meeting","tags":["Meetings"],"description":"Requires meetings:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/{id}/complete":{"post":{"summary":"Mark a meeting completed","tags":["Meetings"],"description":"Requires meetings:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/meetings/{id}/cancel":{"post":{"summary":"Mark a meeting cancelled","tags":["Meetings"],"description":"Requires meetings:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/public/contacts":{"get":{"summary":"List contacts","tags":["Contacts"],"description":"Get a paginated list of contacts. Requires contacts:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by name, phone, or email"},{"schema":{"type":"string"},"in":"query","name":"tagIds","required":false,"description":"Comma-separated tag IDs"},{"schema":{"type":"string"},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"createdAfter","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"createdBefore","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/contacts/{id}":{"get":{"summary":"Get contact by ID","tags":["Contacts"],"description":"Get a single contact with tags and conversation count. Requires contacts:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/conversations":{"get":{"summary":"List conversations","tags":["Conversations"],"description":"Get a paginated list of conversations with filters. Requires conversations:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filter by status (open, closed, pending)"},{"schema":{"type":"string"},"in":"query","name":"channelType","required":false,"description":"Filter by channel type (whatsapp, instagram, messenger, widget)"},{"schema":{"type":"string"},"in":"query","name":"assignedToId","required":false,"description":"Filter by assigned agent ID"},{"schema":{"type":"boolean"},"in":"query","name":"unread","required":false,"description":"Filter to only unread conversations"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by contact name or phone"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateFrom","required":false,"description":"Filter messages from this date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateTo","required":false,"description":"Filter messages to this date"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/conversations/{id}":{"get":{"summary":"Get conversation by ID","tags":["Conversations"],"description":"Get a single conversation with contact, channel, and assigned agent details. Requires conversations:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/conversations/{id}/messages":{"get":{"summary":"List messages in a conversation","tags":["Messages"],"description":"Get paginated messages for a conversation in chronological order. Requires messages:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"before","required":false,"description":"Fetch messages before this date (cursor pagination)"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/orders":{"get":{"summary":"List orders","tags":["Orders"],"description":"Get a paginated list of orders with filters. Requires orders:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filter by order status"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateAfter","required":false,"description":"Orders created after this date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"dateBefore","required":false,"description":"Orders created before this date"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by order number or customer name"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/orders/{id}":{"get":{"summary":"Get order by ID","tags":["Orders"],"description":"Get a single order with line items. Requires orders:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/leads":{"get":{"summary":"List leads","tags":["Leads"],"description":"Get a paginated list of leads (contacts in LEAD lifecycle stage). Requires leads:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"stage","required":false,"description":"Filter by pipeline stage (e.g., NEW, QUALIFIED, PROPOSAL)"},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by name, phone, or email"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/leads/{id}":{"get":{"summary":"Get lead by ID","tags":["Leads"],"description":"Get a single lead with assigned agent, follow-up tasks, and counts. Requires leads:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/tickets":{"get":{"summary":"List tickets","tags":["Tickets"],"description":"Get a paginated list of support tickets with filters. Requires tickets:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filter by ticket status (open, in_progress, resolved, closed)"},{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Filter by ticket type"},{"schema":{"type":"string"},"in":"query","name":"priority","required":false,"description":"Filter by priority (low, medium, high, urgent)"},{"schema":{"type":"string"},"in":"query","name":"assignedToId","required":false,"description":"Filter by assigned agent ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/tickets/{id}":{"get":{"summary":"Get ticket by ID","tags":["Tickets"],"description":"Get a single support ticket with comments. Requires tickets:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/products":{"get":{"summary":"List products","tags":["Products"],"description":"Get a paginated list of products from the catalog. Requires products:read permission.","parameters":[{"schema":{"type":"integer","default":1,"minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by product name or SKU"},{"schema":{"type":"string"},"in":"query","name":"categoryId","required":false,"description":"Filter by category ID"},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false,"description":"Filter by active status"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/products/{id}":{"get":{"summary":"Get product by ID","tags":["Products"],"description":"Get a single product with full details. Requires products:read permission.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/public/analytics/dashboard":{"get":{"summary":"Get dashboard analytics","tags":["Analytics"],"description":"Get aggregated dashboard statistics (conversations, messages, contacts, etc.). Requires analytics:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/knowledge-center/categories":{"get":{"summary":"List knowledge categories","tags":["Knowledge Center"],"description":"Requires knowledge:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a knowledge category","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Category name.","example":"Shipping and returns"},"description":{"type":"string","description":"Category description."},"icon":{"type":"string","description":"Icon identifier."},"color":{"type":"string","description":"Display color.","example":"#3bc1a8"},"parentId":{"type":"string","description":"Parent category ID, for nesting."},"sortOrder":{"type":"number","description":"Sort order among siblings."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/categories/{id}":{"put":{"summary":"Update a knowledge category","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Category name."},"description":{"type":"string","description":"Category description."},"icon":{"type":"string","description":"Icon identifier."},"color":{"type":"string","description":"Display color."},"parentId":{"type":"string","description":"Parent category ID, or null to un-nest."},"sortOrder":{"type":"number","description":"Sort order among siblings."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a knowledge category","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/categories/reorder":{"put":{"summary":"Reorder knowledge categories","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"array","description":"Full ordered list of category IDs with their new sort positions.","items":{"type":"object","properties":{"id":{"type":"string"},"sortOrder":{"type":"number"}}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/articles":{"get":{"summary":"List knowledge articles","tags":["Knowledge Center"],"description":"Requires knowledge:read permission.","parameters":[{"schema":{"type":"string"},"in":"query","name":"categoryId","required":false},{"schema":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"tag","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Title or content."},{"schema":{"type":"integer","example":1},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Page size (default 20)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string","description":"Article title.","example":"How to reset your password"},"content":{"type":"string","description":"Article body."},"categoryId":{"type":"string","description":"Category this article belongs to."},"excerpt":{"type":"string","description":"Short summary shown in listings."},"tags":{"type":"array","items":{"type":"string"},"description":"Free-text tags."},"status":{"type":"string","enum":["DRAFT","PUBLISHED"],"description":"Defaults to DRAFT."}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/articles/{id}":{"get":{"summary":"Get a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:read permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Article title."},"content":{"type":"string","description":"Article body."},"categoryId":{"type":"string","description":"Category, or null to clear."},"excerpt":{"type":"string","description":"Short summary shown in listings."},"tags":{"type":"array","items":{"type":"string"},"description":"Free-text tags."},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"],"description":"Article status."}}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/articles/{id}/publish":{"post":{"summary":"Publish a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/articles/{id}/archive":{"post":{"summary":"Archive a knowledge article","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/search":{"get":{"summary":"Search knowledge articles","tags":["Knowledge Center"],"description":"Requires knowledge:read permission.","parameters":[{"schema":{"type":"string","example":"refund"},"in":"query","name":"q","required":false,"description":"Search text; empty returns nothing."},{"schema":{"type":"integer","example":20},"in":"query","name":"limit","required":false,"description":"Max results (default 20)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/quick-search":{"get":{"summary":"Quick-search knowledge articles","tags":["Knowledge Center"],"description":"Requires knowledge:read permission.","parameters":[{"schema":{"type":"string","example":"refund"},"in":"query","name":"q","required":false,"description":"Search text; empty returns nothing."},{"schema":{"type":"integer","example":5},"in":"query","name":"limit","required":false,"description":"Max results (default 5)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/knowledge-center/articles/{id}/feedback":{"post":{"summary":"Submit article feedback","tags":["Knowledge Center"],"description":"Requires knowledge:write permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["isHelpful"],"properties":{"isHelpful":{"type":"boolean","description":"Whether the article was helpful.","example":true},"comment":{"type":"string","description":"Optional free-text comment."}}}}},"required":true},"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/me/channels":{"get":{"summary":"Connection status of every channel (WhatsApp, Instagram, Messenger, Telegram, website chat)","tags":["Channels"],"description":"Aggregate connection state for all channels (WhatsApp, Instagram, Messenger, Telegram, Widget). One request, parallel-fetched. Requires channels:read permission.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["whatsapp","instagram","messenger","telegram","widget"],"properties":{"whatsapp":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DISCONNECTED","CONNECTED","BROKEN"]},"displayName":{"type":"string"},"externalId":{"type":"string"},"avatarUrl":{"type":"string"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}},"additionalProperties":false},"instagram":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DISCONNECTED","CONNECTED","BROKEN"]},"displayName":{"type":"string"},"externalId":{"type":"string"},"avatarUrl":{"type":"string"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}},"additionalProperties":false},"messenger":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DISCONNECTED","CONNECTED","BROKEN"]},"displayName":{"type":"string"},"externalId":{"type":"string"},"avatarUrl":{"type":"string"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}},"additionalProperties":false},"telegram":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DISCONNECTED","CONNECTED","BROKEN"]},"displayName":{"type":"string"},"externalId":{"type":"string"},"avatarUrl":{"type":"string"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}},"additionalProperties":false},"widget":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["DISCONNECTED","CONNECTED","BROKEN"]},"displayName":{"type":"string"},"externalId":{"type":"string"},"avatarUrl":{"type":"string"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/api/v1/scheduled-messages/":{"get":{"summary":"List scheduled messages","tags":["Scheduled messages"],"description":"Requires messages:read permission.","parameters":[{"schema":{"type":"string","enum":["PENDING","SENT","FAILED","CANCELLED","PAUSED","DEAD_LETTER"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","TELEGRAM","WIDGET"]},"in":"query","name":"channel","required":false},{"schema":{"type":"integer","example":50},"in":"query","name":"limit","required":false,"description":"1–200 (default 50); out of range is a 400."},{"schema":{"type":"integer","example":0},"in":"query","name":"offset","required":false,"description":"Rows to skip (default 0)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Schedule a message","tags":["Scheduled messages"],"description":"Requires messages:send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["channel","recipientRef","scheduledFor","payload"],"properties":{"channel":{"type":"string","enum":["WHATSAPP","INSTAGRAM","MESSENGER","TELEGRAM","SMS"],"example":"WHATSAPP"},"recipientRef":{"type":"string","description":"Phone number (WhatsApp/SMS) or the channel’s recipient id.","example":"966500000000"},"scheduledFor":{"type":"string","format":"date-time","example":"2026-09-20T09:00:00Z"},"conversationId":{"type":"string"},"recurrence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"]},"payload":{"type":"object","description":"`{kind:\"text\", text}` or `{kind:\"template\", templateName, languageCode, bodyVariables?, components?}`. Outside the 24-hour window WhatsApp needs a template; the response says `window_requires_template`.","example":{"kind":"template","templateName":"order_shipped","languageCode":"ar","bodyVariables":{"1":"Sara"}}}}}}},"required":true},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/scheduled-messages/{id}/cancel":{"post":{"summary":"Cancel a scheduled message","tags":["Scheduled messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/scheduled-messages/{id}/pause":{"post":{"summary":"Pause a recurring message","tags":["Scheduled messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/scheduled-messages/{id}/resume":{"post":{"summary":"Resume a paused message","tags":["Scheduled messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/scheduled-messages/{id}/send-now":{"post":{"summary":"Send a scheduled message now","tags":["Scheduled messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/scheduled-messages/{id}":{"delete":{"summary":"Delete a scheduled message","tags":["Scheduled messages"],"description":"Requires messages:send permission.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.inboxy.chat","description":"Production"},{"url":"http://localhost:4000","description":"Local Development"}]}