{"openapi":"3.0.3","info":{"title":"Convexa API","version":"v1","description":"WhatsApp APIs made simple. Authenticate with Authorization: Bearer cvx_live_…"},"servers":[{"url":"https://api.convexa.co.in/v1"}],"tags":[{"name":"Authentication"},{"name":"Messages"},{"name":"Contacts"},{"name":"Conversations"},{"name":"Broadcasts"},{"name":"Webhooks"},{"name":"Infrastructure"}],"paths":{"/health":{"get":{"operationId":"health","summary":"Health check","description":"No authentication required. Use this for uptime checks and to verify your Base URL.","tags":["Infrastructure"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/HealthData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"example":{"success":true,"data":{"status":"ok","service":"convexa-api","version":"v1"},"meta":{"request_id":"req_..."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/me":{"get":{"operationId":"me","summary":"Verify your access token","description":"Call this first after generating a token. Returns the account bound to the token and the scopes granted.","tags":["Authentication"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MeData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"example":{"success":true,"data":{"account":{"id":"uuid","name":"Web Work"},"key":{"id":"uuid","scopes":["messages:send","contacts:read"]}},"meta":{"request_id":"req_..."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/messages":{"post":{"operationId":"messages.send","summary":"Send a WhatsApp message","description":"Convexa resolves your WhatsApp connection from the access token. Provide a phone number in E.164 (or digits with country code). Contact and conversation are created automatically if needed.","tags":["Messages"],"parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SendMessageResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"example":{"success":true,"data":{"message_id":"uuid","whatsapp_message_id":"wamid...","conversation_id":"uuid","contact_id":"uuid","contact_created":true},"meta":{"request_id":"req_..."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"},"example":{"to":"919876543210","type":"text","text":"Hello from Convexa"}}}}}},"/messages/{id}":{"get":{"operationId":"messages.get","summary":"Get message status","description":"Returns the canonical status ladder (sending/sent/delivered/read/failed) plus WhatsApp message id and error details when failed. Account-scoped — a foreign id returns 404.","tags":["Messages"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Message UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MessageDetail"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"example":{"success":true,"data":{"message_id":"uuid","whatsapp_message_id":"wamid...","status":"delivered","type":"template","to":"919876543210","sent_at":"2026-01-01T10:00:00.000Z","delivered_at":"2026-01-01T10:00:02.000Z","read_at":null,"failed_at":null,"error":null},"meta":{"request_id":"req_..."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/contacts":{"get":{"operationId":"contacts.list","summary":"List contacts","description":"List contacts with optional search and tag filter.","tags":["Contacts"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1–100, default 50)"},"description":"Page size (1–100, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor from meta.next_cursor"},"description":"Opaque cursor from meta.next_cursor"},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Search by name or phone"},"description":"Search by name or phone"},{"name":"tag","in":"query","required":false,"schema":{"type":"string","format":"uuid","description":"Filter by tag UUID"},"description":"Filter by tag UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ContactList"},"meta":{"$ref":"#/components/schemas/ListResponseMeta"}}},"example":{"success":true,"data":[{"id":"uuid","phone":"+919876543210","name":"Jane","tags":[]}],"meta":{"request_id":"req_...","next_cursor":null}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]},"post":{"operationId":"contacts.create","summary":"Create a contact","description":"Find-or-create by phone. If the contact already exists, returns 200 with created:false behavior via status code (existing → 200, new → 201).","tags":["Contacts"],"parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Contact"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactRequest"},"example":{"phone":"+919876543210","name":"Jane Doe","email":"jane@example.com","company":"Acme","tags":["vip"]}}}}}},"/contacts/{id}":{"get":{"operationId":"contacts.get","summary":"Get a contact","description":"Read one contact by ID.","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Contact UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Contact"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]},"patch":{"operationId":"contacts.update","summary":"Update a contact","description":"Update name, email, company, or tags.","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Contact UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Contact"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequest"},"example":{"name":"Jane D.","email":null,"tags":["vip"]}}}}}},"/conversations":{"get":{"operationId":"conversations.list","summary":"List conversations","description":"List conversations, newest first.","tags":["Conversations"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1–100, default 50)"},"description":"Page size (1–100, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor"},"description":"Opaque cursor"},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"open | pending | resolved | closed | spam"},"description":"open | pending | resolved | closed | spam"},{"name":"contact_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","description":"Filter by contact UUID"},"description":"Filter by contact UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ConversationList"},"meta":{"$ref":"#/components/schemas/ListResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/conversations/{id}":{"get":{"operationId":"conversations.get","summary":"Get a conversation","description":"Read one conversation by ID.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Conversation"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/conversations/{id}/messages":{"get":{"operationId":"conversations.messages","summary":"List messages in a conversation","description":"Read message history and delivery status.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation UUID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1–100, default 50)"},"description":"Page size (1–100, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor"},"description":"Opaque cursor"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MessageList"},"meta":{"$ref":"#/components/schemas/ListResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/broadcasts":{"post":{"operationId":"broadcasts.create","summary":"Send a template broadcast","description":"Creates the broadcast record, enqueues durable delivery via the jobs queue, and returns quickly (HTTP 202). Meta sending continues in the background (`after()` + `/api/broadcasts/cron`). Poll GET /broadcasts/:id for progress. Large recipient lists are processed in resume-safe chunks — pending recipients are not lost if a worker is interrupted.","tags":["Broadcasts"],"parameters":[],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CreateBroadcastResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBroadcastRequest"},"example":{"name":"July promo","template_name":"promo_july","template_language":"en_US","recipients":[{"to":"+919876543210","params":["Jane"]},{"to":"+919876543211"}]}}}}}},"/broadcasts/{id}":{"get":{"operationId":"broadcasts.get","summary":"Get broadcast report","description":"Poll broadcast progress with pending / sent / delivered / read / replied / failed counts.","tags":["Broadcasts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Broadcast UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Broadcast"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"example":{"success":true,"data":{"id":"uuid","status":"sending","total_recipients":1000,"pending_count":50,"sent_count":950,"delivered_count":930,"read_count":600,"replied_count":100,"failed_count":20},"meta":{"request_id":"req_..."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/broadcasts/{id}/recipients":{"get":{"operationId":"broadcasts.recipients","summary":"List broadcast recipients","description":"Paginated per-recipient delivery report with optional status filter.","tags":["Broadcasts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Broadcast UUID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1–100, default 50)"},"description":"Page size (1–100, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor from meta.next_cursor"},"description":"Opaque cursor from meta.next_cursor"},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"pending | sent | delivered | read | replied | failed"},"description":"pending | sent | delivered | read | replied | failed"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BroadcastRecipientList"},"meta":{"$ref":"#/components/schemas/ListResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}},"/webhooks":{"get":{"operationId":"webhooks.list","summary":"List webhooks","description":"List registered webhook endpoints.","tags":["Webhooks"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WebhookEndpointList"},"meta":{"$ref":"#/components/schemas/ListResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]},"post":{"operationId":"webhooks.create","summary":"Create a webhook","description":"The signing secret is returned only once. Store it to verify X-Convexa-Signature headers.","tags":["Webhooks"],"parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WebhookEndpointCreated"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"},"example":{"url":"https://example.com/webhooks/convexa","events":["message.received","message.status_updated"]}}}}}},"/webhooks/{id}":{"get":{"operationId":"webhooks.get","summary":"Get a webhook","description":"Read one webhook endpoint.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]},"patch":{"operationId":"webhooks.update","summary":"Update a webhook","description":"Update URL, events, or active flag.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"},"example":{"is_active":true}}}}},"delete":{"operationId":"webhooks.delete","summary":"Delete a webhook","description":"Remove a webhook endpoint.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook UUID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/WebhookDeleted"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden / feature not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerAuth":[]}]}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"cvx_live_","description":"Convexa Access Token"}},"schemas":{"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}},"ListResponseMeta":{"type":"object","required":["request_id","next_cursor"],"properties":{"request_id":{"type":"string"},"next_cursor":{"type":"string","nullable":true}}},"ErrorEnvelope":{"type":"object","required":["success","error","meta"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"HealthData":{"type":"object","required":["status","service","version"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","enum":["convexa-api"]},"version":{"type":"string","enum":["v1"]}}},"MeData":{"type":"object","required":["account","key"],"properties":{"account":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"key":{"type":"object","required":["id","scopes"],"properties":{"id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}}}}}},"ContactTag":{"type":"object","required":["id","name","color"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string"}}},"Contact":{"type":"object","required":["id","phone","name","email","company","avatar_url","tags","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"phone":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ContactTag"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContactList":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"ConversationContact":{"type":"object","required":["id","phone","name","email","company","tags"],"properties":{"id":{"type":"string","format":"uuid"},"phone":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ContactTag"}}}},"Conversation":{"type":"object","required":["id","contact_id","status","assigned_agent_id","last_message_text","last_message_at","unread_count","created_at","updated_at","contact"],"properties":{"id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","pending","resolved","closed","spam"]},"assigned_agent_id":{"type":"string","format":"uuid","nullable":true},"last_message_text":{"type":"string","nullable":true},"last_message_at":{"type":"string","format":"date-time","nullable":true},"unread_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact":{"oneOf":[{"$ref":"#/components/schemas/ConversationContact"},{"type":"null"}]}}},"ConversationList":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"Message":{"type":"object","required":["id","conversation_id","direction","sender_type","content_type","content_text","media_url","template_name","whatsapp_message_id","status","reply_to_message_id","interactive_reply_id","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"sender_type":{"type":"string"},"content_type":{"type":"string"},"content_text":{"type":"string","nullable":true},"media_url":{"type":"string","nullable":true},"template_name":{"type":"string","nullable":true},"whatsapp_message_id":{"type":"string","nullable":true},"status":{"type":"string"},"reply_to_message_id":{"type":"string","format":"uuid","nullable":true},"interactive_reply_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"MessageList":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"SendMessageRequest":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Recipient phone number (E.164 or digits with country code)"},"type":{"type":"string","enum":["text","template","interactive","image","video","document","audio"],"default":"text"},"text":{"type":"string","description":"Text body or media caption"},"media_url":{"type":"string","format":"uri"},"filename":{"type":"string"},"template":{"type":"object","required":["name","language"],"properties":{"name":{"type":"string"},"language":{"type":"string"},"params":{"description":"Positional body parameters (array of strings) or structured header/body/button params (object).","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object"}]}}},"interactive_payload":{"oneOf":[{"$ref":"#/components/schemas/InteractiveButtonsPayload"},{"$ref":"#/components/schemas/InteractiveListPayload"}]},"reply_to_message_id":{"type":"string","format":"uuid","description":"Message UUID in the same conversation to reply to"},"name":{"type":"string","description":"Contact name when creating a new contact"}},"examples":{"text":{"to":"919876543210","type":"text","text":"Hello from Convexa"},"template":{"to":"919876543210","type":"template","template":{"name":"order_update","language":"en_US","params":["A123"]}},"template-structured":{"to":"919876543210","type":"template","template":{"name":"order_update","language":"en_US","params":{"body":["A123"]}}},"image":{"to":"919876543210","type":"image","media_url":"https://example.com/photo.jpg","text":"Optional caption"},"video":{"to":"919876543210","type":"video","media_url":"https://example.com/clip.mp4"},"document":{"to":"919876543210","type":"document","media_url":"https://example.com/invoice.pdf","filename":"invoice.pdf"},"audio":{"to":"919876543210","type":"audio","media_url":"https://example.com/voice.ogg"},"interactive":{"to":"919876543210","type":"interactive","interactive_payload":{"kind":"buttons","body":"Would you like to continue?","buttons":[{"id":"yes","title":"Yes"},{"id":"no","title":"No"}]}},"interactive-list":{"to":"919876543210","type":"interactive","interactive_payload":{"kind":"list","body":"Choose a department","button_label":"Options","sections":[{"title":"Support","rows":[{"id":"billing","title":"Billing","description":"Invoices and payments"},{"id":"tech","title":"Technical help"}]}]}}}},"InteractiveButton":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string"},"title":{"type":"string","maxLength":20}}},"InteractiveButtonsPayload":{"type":"object","required":["kind","body","buttons"],"properties":{"kind":{"type":"string","enum":["buttons"]},"body":{"type":"string","maxLength":1024},"header":{"type":"string","maxLength":60},"footer":{"type":"string","maxLength":60},"buttons":{"type":"array","items":{"$ref":"#/components/schemas/InteractiveButton"},"minItems":1,"maxItems":3}}},"InteractiveListRow":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string"},"title":{"type":"string","maxLength":24},"description":{"type":"string","maxLength":72}}},"InteractiveListSection":{"type":"object","required":["rows"],"properties":{"title":{"type":"string"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/InteractiveListRow"},"minItems":1}}},"InteractiveListPayload":{"type":"object","required":["kind","body","button_label","sections"],"properties":{"kind":{"type":"string","enum":["list"]},"body":{"type":"string","maxLength":1024},"header":{"type":"string","maxLength":60},"footer":{"type":"string","maxLength":60},"button_label":{"type":"string","maxLength":20},"sections":{"type":"array","items":{"$ref":"#/components/schemas/InteractiveListSection"},"minItems":1,"maxItems":10}}},"SendMessageResponse":{"type":"object","required":["message_id","whatsapp_message_id","conversation_id","contact_id","contact_created"],"properties":{"message_id":{"type":"string","format":"uuid"},"whatsapp_message_id":{"type":"string"},"conversation_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"contact_created":{"type":"boolean"}}},"CreateContactRequest":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"UpdateContactRequest":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}}}},"CreateBroadcastRequest":{"type":"object","required":["template_name","recipients"],"properties":{"name":{"type":"string"},"template_name":{"type":"string"},"template_language":{"type":"string"},"recipients":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["to"],"properties":{"to":{"type":"string"},"params":{"type":"array","items":{"type":"string"}}}}}}},"CreateBroadcastResponse":{"type":"object","required":["broadcast_id","status","total_recipients","accepted","rejected"],"properties":{"broadcast_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["sending"]},"total_recipients":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"integer"}}},"Broadcast":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"template_name":{"type":"string"},"template_language":{"type":"string","nullable":true},"status":{"type":"string"},"total_recipients":{"type":"integer"},"pending_count":{"type":"integer"},"sent_count":{"type":"integer"},"delivered_count":{"type":"integer"},"read_count":{"type":"integer"},"replied_count":{"type":"integer"},"failed_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"BroadcastRecipient":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid","nullable":true},"phone":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"status":{"type":"string"},"whatsapp_message_id":{"type":"string","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"read_at":{"type":"string","format":"date-time","nullable":true},"replied_at":{"type":"string","format":"date-time","nullable":true},"failed_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"}}},"BroadcastRecipientList":{"type":"array","items":{"$ref":"#/components/schemas/BroadcastRecipient"}},"MessageDetail":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"whatsapp_message_id":{"type":"string","nullable":true},"status":{"type":"string"},"type":{"type":"string"},"content_type":{"type":"string"},"to":{"type":"string","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"read_at":{"type":"string","format":"date-time","nullable":true},"failed_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","required":["id","url","events","is_active","last_delivery_at","failure_count","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"failure_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpointCreated":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Signing secret — returned only once at creation"}}}]},"WebhookEndpointList":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"WebhookDeleted":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","enum":[true]}}},"CreateWebhookRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1}}},"UpdateWebhookRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1},"is_active":{"type":"boolean"}}}}},"x-rate-limit":{"limit":120,"windowSeconds":60,"description":"120 requests per 60 seconds per access token (per server instance)"}}