Skip to main content

WhatsApp

WhatsApp endpoints for sending template messages, listing approved templates, and listing conversations. All endpoints use API-key authentication and the standard response envelope — see Getting Started for x-api-key, base URL, and rate limits.

Send Template Message​

Send a pre-approved WhatsApp template message.

POST /v1/send-message

cURL​

curl -X POST 'https://app.superwaba.com/api/developer/v1/send-message' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "ORD-456" }
        ]
      }
    ]
  }
}'

Request Body​

{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "ORD-456" }
        ]
      }
    ]
  }
}

Parameters​

ParameterTypeRequiredDescription
tostringYesPhone number in E.164 format without + (e.g. "919876543210")
typestringNoMessage type. Default: "template"
template.namestringYesApproved template name
template.language.codestringYesTemplate language code (e.g. "en")
template.componentsarrayNoTemplate variable values (header, body, button params)

Response - 201 Created​

{
  "success": true,
  "data": {
    "waMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
    "status": "sent",
    "conversationId": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "contactId": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef"
  }
}

Response - 400 Missing Field​

{
  "success": false,
  "message": "Missing required field: to",
  "code": "MISSING_FIELD",
  "fix": "Include \"to\" field with phone number in E.164 format (e.g. \"919876543210\")"
}

Response - 401 Invalid API Key​

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Response - 429 Monthly Limit Reached​

{
  "success": false,
  "message": "Monthly API event limit reached (5000/5000). Upgrade your plan for more.",
  "code": "API_LIMIT_REACHED"
}

Response - 500 Server Error​

{
  "success": false,
  "message": "Internal server error"
}

List Templates​

Retrieve all approved WhatsApp message templates for your organization.

GET /v1/templates

cURL​

curl -X GET 'https://app.superwaba.com/api/developer/v1/templates' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response - 200 OK​

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "hello_world",
      "language": "en",
      "status": "APPROVED",
      "category": "MARKETING",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}, welcome to SuperWaba!"
        }
      ]
    },
    {
      "id": "template_def456",
      "name": "order_update",
      "language": "en",
      "status": "APPROVED",
      "category": "UTILITY",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}}, your order {{2}} has been shipped."
        }
      ]
    }
  ]
}

Response - 401 Invalid API Key​

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

List Conversations​

GET /v1/conversations/whatsapp

cURL​

curl -X GET 'https://app.superwaba.com/api/developer/v1/conversations/whatsapp?page=1&limit=20' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Query Parameters​

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber20Results per page (max: 100)

Response - 200 OK​

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "contact": {
          "name": "Priya Sharma",
          "phone": "+919876543210"
        },
        "last_message": "Hi, I need help with my order",
        "status": "open",
        "updated_at": "2026-05-26T14:22:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 42
    }
  }
}

Response - 401 Invalid API Key​

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}