{
  "openapi": "3.0.3",
  "info": {
    "title": "SMSGatewayHub WhatsApp Business API",
    "version": "1.0.0",
    "description": "Send WhatsApp templates, session messages, interactive messages and bulk campaigns; track statuses; manage opt-outs and media. Every operation is selected with the `action` query parameter. Full guide: https://www.smsgatewayhub.com/cpaas/whatsapp/docs.ashx",
    "contact": { "name": "SMSGatewayHub support", "email": "support@smsgatewayhub.com", "url": "https://www.smsgatewayhub.com" }
  },
  "servers": [ { "url": "https://www.smsgatewayhub.com/cpaas/whatsapp" } ],
  "security": [ { "bearer": [] } ],
  "paths": {
    "/api.ashx?action=send": {
      "post": {
        "operationId": "send", "summary": "Send a template, or a session message inside the 24-hour window",
        "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TemplateMessage" }, { "$ref": "#/components/schemas/SessionMessage" } ] } } } },
        "responses": { "200": { "$ref": "#/components/responses/Queued" }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api.ashx?action=bulk": {
      "post": {
        "operationId": "bulk", "summary": "Send one template to up to 1000 recipients (creates a campaign)",
        "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": [ "template", "recipients" ],
          "properties": {
            "template": { "type": "string" }, "language": { "type": "string", "default": "en" }, "name": { "type": "string" },
            "scheduleAt": { "type": "string", "example": "2026-10-07T10:30:00", "description": "India time, within 30 days" },
            "recipients": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/Recipient" } } } } } } },
        "responses": { "200": { "description": "Campaign created", "content": { "application/json": { "schema": {
          "type": "object", "properties": { "ok": { "type": "boolean" }, "campaignId": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "scheduled" ] }, "scheduledAt": { "type": "string", "nullable": true },
            "accepted": { "type": "integer" }, "rejectedCount": { "type": "integer" },
            "messages": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "to": { "type": "string" }, "messageId": { "type": "integer" }, "ref": { "type": "string" } } } },
            "rejected": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "to": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } },
          "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api.ashx?action=meta": {
      "post": {
        "operationId": "metaSend", "summary": "Meta Cloud API compatible send (synchronous, returns Meta's response)",
        "parameters": [ { "name": "phone_number_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Idempotency" } ],
        "requestBody": { "required": true, "description": "Exactly Meta's POST /{phone-number-id}/messages body", "content": { "application/json": { "schema": { "type": "object", "required": [ "messaging_product", "to", "type" ], "properties": { "messaging_product": { "type": "string", "enum": [ "whatsapp" ] }, "to": { "type": "string" }, "type": { "type": "string" }, "biz_opaque_callback_data": { "type": "string" } }, "additionalProperties": true } } } },
        "responses": { "200": { "description": "Meta's response plus sgh_message_id", "content": { "application/json": { "schema": { "type": "object", "properties": { "messaging_product": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object" } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "sgh_message_id": { "type": "integer" } } } } } },
          "400": { "description": "Meta-format error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } }
      }
    },
    "/api.ashx?action=status": {
      "get": {
        "operationId": "status", "summary": "Status of a message (id or ref) or of up to 100 messages (ids)",
        "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer" } }, { "name": "ref", "in": "query", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "schema": { "type": "string", "example": "1045,1046" } } ],
        "responses": { "200": { "description": "Message (or messages[] when ids is used)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api.ashx?action=messages": {
      "get": {
        "operationId": "messages", "summary": "List messages (100 per page, max 31 days)",
        "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "cancelled" ] } },
          { "name": "number", "in": "query", "schema": { "type": "string" } }, { "name": "campaignId", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ],
        "responses": { "200": { "description": "Page of messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "page": { "type": "integer" }, "hasMore": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } } }
      }
    },
    "/api.ashx?action=templates": { "get": { "operationId": "templates", "summary": "Approved templates and the values each needs", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string" }, "variables": { "type": "integer" }, "headerType": { "type": "string" }, "headerVariable": { "type": "boolean" }, "buttonVariables": { "type": "integer" }, "components": { "type": "array", "items": { "type": "object" } } } } } } } } } } } } },
    "/api.ashx?action=media": { "post": { "operationId": "uploadMedia", "summary": "Upload a file and get a public https link", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "link": { "type": "string" }, "fileName": { "type": "string" }, "size": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" } } } },
    "/api.ashx?action=contact": { "get": { "operationId": "contact", "summary": "Contact details and 24-hour window", "parameters": [ { "name": "number", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "number": { "type": "string" }, "known": { "type": "boolean" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object" }, "optedOut": { "type": "boolean" }, "blocked": { "type": "boolean" }, "windowOpen": { "type": "boolean" }, "windowClosesAt": { "type": "string" } } } } } } } } },
    "/api.ashx?action=optouts": { "get": { "operationId": "optouts", "summary": "Opted-out numbers (500 per page)", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Opt-outs" } } } },
    "/api.ashx?action=optout": { "post": { "operationId": "optout", "summary": "Add or remove an opt-out", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "string" }, "op": { "type": "string", "enum": [ "add", "remove" ], "default": "add" } } } } } }, "responses": { "200": { "description": "Done" } } } },
    "/api.ashx?action=balance": { "get": { "operationId": "balance", "summary": "Billing mode and wallet balance", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "billingActive": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "per_message", "plan", "free" ] }, "currency": { "type": "string" }, "balance": { "type": "number" }, "planName": { "type": "string", "nullable": true }, "planValidTill": { "type": "string", "nullable": true } } } } } } } } }
  },
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key from Panel > WhatsApp > API (sghwa_...)" } },
    "parameters": { "Idempotency": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Same key within 24 hours returns the first result instead of sending again" } },
    "responses": {
      "Queued": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "messageId": { "type": "integer" }, "status": { "type": "string", "example": "queued" }, "ref": { "type": "string", "nullable": true }, "duplicate": { "type": "boolean" } } } } } },
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "template_not_found" }, "message": { "type": "string" }, "docs": { "type": "string" } } },
      "Recipient": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "example": "919876543210" }, "variables": { "type": "array", "items": { "type": "string" } }, "header": { "$ref": "#/components/schemas/Header" }, "buttons": { "type": "array", "items": { "type": "string" } }, "ref": { "type": "string", "maxLength": 100 } } },
      "Header": { "type": "object", "properties": { "text": { "type": "string" }, "media": { "type": "string", "format": "uri" }, "filename": { "type": "string" } } },
      "TemplateMessage": { "type": "object", "required": [ "to", "template" ], "properties": { "to": { "type": "string" }, "type": { "type": "string", "enum": [ "template" ], "default": "template" }, "template": { "type": "string" }, "language": { "type": "string", "default": "en" }, "variables": { "type": "array", "items": { "type": "string" } }, "header": { "$ref": "#/components/schemas/Header" }, "buttons": { "type": "array", "items": { "type": "string" } }, "ref": { "type": "string", "maxLength": 100 } } },
      "SessionMessage": { "type": "object", "required": [ "to", "type" ], "properties": {
        "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "image", "video", "audio", "document", "interactive" ] }, "ref": { "type": "string" },
        "text": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "object", "properties": { "body": { "type": "string" } } } ] },
        "media": { "type": "object", "properties": { "link": { "type": "string", "format": "uri" }, "caption": { "type": "string" }, "filename": { "type": "string" } } },
        "interactive": { "type": "object", "required": [ "type", "body" ], "properties": {
          "type": { "type": "string", "enum": [ "buttons", "list", "cta_url" ] }, "header": { "type": "string", "maxLength": 60 }, "body": { "type": "string", "maxLength": 1024 }, "footer": { "type": "string", "maxLength": 60 },
          "buttons": { "type": "array", "maxItems": 3, "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "maxLength": 20 } } } },
          "button": { "type": "string", "maxLength": 20 },
          "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "maxLength": 72 } } } } } } },
          "text": { "type": "string", "maxLength": 20 }, "url": { "type": "string", "format": "uri" } } } } },
      "Message": { "type": "object", "properties": { "messageId": { "type": "integer" }, "toNumber": { "type": "string" }, "messageType": { "type": "string" }, "templateName": { "type": "string", "nullable": true }, "campaignId": { "type": "integer", "nullable": true },
        "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "cancelled" ] }, "errorCode": { "type": "string", "nullable": true }, "errorText": { "type": "string", "nullable": true }, "clientRef": { "type": "string", "nullable": true },
        "createdAt": { "type": "string" }, "sentAt": { "type": "string", "nullable": true }, "deliveredAt": { "type": "string", "nullable": true }, "readAt": { "type": "string", "nullable": true }, "repliedAt": { "type": "string", "nullable": true }, "clickedAt": { "type": "string", "nullable": true }, "failedAt": { "type": "string", "nullable": true }, "pricingCategory": { "type": "string", "nullable": true }, "fallbackStatus": { "type": "string", "nullable": true } } }
    }
  }
}