{"openapi":"3.0.3","info":{"title":"VortSender API","version":"1.0.0","description":"WhatsApp customer-engagement OS — public developer API. Authenticate with Authorization: Bearer vs_live_…"},"servers":[{"url":"/api/v1"}],"paths":{"/messages":{"post":{"summary":"Send a WhatsApp message","description":"Send text, template, or interactive reply-button messages via a connected WhatsApp account.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional idempotency key to safely retry sends"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SendTextMessage"},{"$ref":"#/components/schemas/SendTemplateMessage"},{"$ref":"#/components/schemas/SendInteractiveMessage"}]},"examples":{"text":{"summary":"Text","value":{"to":"+233XXXXXXXXX","type":"text","text":{"body":"Hello from VortSender"}}},"template":{"summary":"Template","value":{"to":"+233XXXXXXXXX","type":"template","template":{"name":"hello_world","language":"en","bodyParams":["Ada"]}}},"interactive":{"summary":"Interactive buttons","value":{"to":"+233XXXXXXXXX","type":"interactive","interactive":{"type":"button","body":{"text":"Choose an option"},"action":{"buttons":[{"type":"reply","reply":{"id":"yes","title":"Yes"}},{"type":"reply","reply":{"id":"no","title":"No"}}]}}}}}}}},"responses":{"200":{"description":"Message accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Missing scope or feature disabled"},"404":{"description":"WhatsApp connection not found"}}}},"/orders":{"get":{"summary":"List orders","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":25}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated orders"}}},"post":{"summary":"Create an order","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string"},"description":{"type":"string"},"total":{"type":"number","description":"Amount in minor units (pesewas)"},"currency":{"type":"string","default":"GHS"},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"integer"},"unitPrice":{"type":"integer"}}}}}}}}},"responses":{"200":{"description":"Order created"}}}},"/orders/{id}":{"get":{"summary":"Get order by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"},"404":{"description":"Not found"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Developers → Create API key (vs_live_…)"}},"schemas":{"ApiSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"},"requestId":{"type":"string"}}},"ConnectionFields":{"type":"object","properties":{"to":{"type":"string","description":"E.164 recipient","example":"+233XXXXXXXXX"},"connectionId":{"type":"string","description":"Optional connection cuid"},"phoneNumberId":{"type":"string","description":"Optional Meta phone number id or connection id"}},"required":["to"]},"SendTextMessage":{"allOf":[{"$ref":"#/components/schemas/ConnectionFields"},{"type":"object","required":["text"],"properties":{"type":{"type":"string","enum":["text"],"default":"text"},"text":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":4096}}}}}]},"SendTemplateMessage":{"allOf":[{"$ref":"#/components/schemas/ConnectionFields"},{"type":"object","required":["type","template"],"properties":{"type":{"type":"string","enum":["template"]},"template":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"language":{"type":"string","default":"en"},"bodyParams":{"type":"array","items":{"type":"string"},"maxItems":10},"components":{"type":"array","items":{}}}}}}]},"SendInteractiveMessage":{"allOf":[{"$ref":"#/components/schemas/ConnectionFields"},{"type":"object","required":["type","interactive"],"properties":{"type":{"type":"string","enum":["interactive"]},"interactive":{"type":"object","required":["body","action"],"properties":{"type":{"type":"string","enum":["button"],"default":"button"},"body":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":1024}}},"action":{"type":"object","required":["buttons"],"properties":{"buttons":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","properties":{"type":{"type":"string","enum":["reply"]},"reply":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string"},"title":{"type":"string","maxLength":20}}}}}}}}}}}}]}}}}