Developer API

Kwital API documentation

Send WhatsApp, SMS and email from your website, CRM or billing software, check each message’s status, and manage your WhatsApp gateways, Cloud API templates and chats over HTTP.

Base URL https://kwital.com/api

HTTPS and JSON
Api-key header
60 requests a minute

Getting started

Quick start

Get your API keyOpen the API page in your member panel and generate a key. Generating a new key replaces the old one straight away.
Connect a gatewayMessages go out through your own WhatsApp devices or Cloud API numbers, SMS gateways or Android phones, and email gateways. You can pick the default gateway for API sends on the same page.
Send and checkPOST to a send endpoint, keep the id of each message from data[], then look it up to see whether it was delivered.

Get your API key Send your first message

Authentication

Send your key in the Api-key header with every request. If your tool cannot set headers, pass it as an api_key query or body parameter instead. Keep the key on your server and never put it in browser or app code.

Header

Api-key: YOUR_API_KEY

Requests with a member key act on that member’s gateways, templates, messages and credits, and need an active plan.

Responses

Responses are JSON. Most endpoints return success, message and data. Send endpoints return one item in data[] for every message they queue.

200Success

{
  "success": true,
  "message": "Sms dispatch request created successfully",
  "data": [ … ]
}

422Error

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.number": ["The contact.0.number field is required."]
  }
}

API key and plan errors use a different shape, {"status": "error", "error": "…"}. See Errors.

Message statuses

The status of each message in send and lookup responses.

pending: Accepted and waiting to be sent.
schedule: Waiting for its schedule_at time.
processing: Being handed to the gateway.
delivered: Sent successfully by the gateway.
fail: The gateway could not send it.
cancel: Cancelled before sending.

Send messages

Send WhatsApp messages

POST/api/whatsapp/send

Queue one or more WhatsApp messages. Each item in contact is one recipient and can carry text, a media file, or an approved Cloud API template.

Body (JSON)

contact array Required: List of recipients. At least one item.
contact[].number string Required: WhatsApp number with country code, digits only (for example 919829012345). Up to 255 characters.
contact[].message string Unless a template is sent: Message text. Optional only when the recipient gets a Cloud API template (template_name).
contact[].media string Optional: Attach a file: image, audio, video or document. Needs url.
contact[].url string (URL) With media: Public URL of the file. Kwital downloads it and sends it with the message; if the download fails the request returns 400.
contact[].filename string Optional: File name the recipient sees (up to 255 characters). The extension from the URL is added if you leave it out.
contact[].schedule_at string Optional: Send later instead of now. Format YYYY-MM-DD HH:MM:SS, for example 2026-10-01 09:30:00.
gateway_type string Optional: node (WhatsApp device linked by QR code) or cloud (official WhatsApp Cloud API). Top level or per contact.
gateway_identifier string Optional: Send through a specific gateway. Use a gateway_identifier from List WhatsApp gateways. Top level or per contact.
template_name string Optional: Name of an approved Cloud API template. Sending a template always uses the Cloud API. Top level or per contact.
template_language string Optional: Template language code, for example en_US. Required when the same template name exists in more than one language.
template_components array Optional: Meta template components with the values for the template variables (header, body and button parameters). Top level or per contact.
cloud_api boolean Optional: Older flag: true works like "gateway_type": "cloud".

Values set inside a contact item override the same field at the top level.
Without any gateway fields, messages go through the WhatsApp device you chose as your API default in the panel, or an available device when none is set.
Conflicting choices, such as template_name with "gateway_type": "node", an unknown gateway_identifier, or a template name that matches more than one language, return 422 with a message that explains the problem.

Request

curl -X POST "https://kwital.com/api/whatsapp/send" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "contact": [
    {
      "number": "919829012345",
      "message": "Hi Priya, your order #4821 is out for delivery."
    },
    {
      "number": "919829054321",
      "message": "Your invoice is attached.",
      "media": "document",
      "url": "https://example.com/files/invoice-4821.pdf",
      "filename": "Invoice 4821.pdf"
    }
  ]
}'

$payload = [
    'contact' => [
        [
            'number' => '919829012345',
            'message' => 'Hi Priya, your order #4821 is out for delivery.',
        ],
        [
            'number' => '919829054321',
            'message' => 'Your invoice is attached.',
            'media' => 'document',
            'url' => 'https://example.com/files/invoice-4821.pdf',
            'filename' => 'Invoice 4821.pdf',
        ],
    ],
];

$curl = curl_init('https://kwital.com/api/whatsapp/send');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/send', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact: [
      {
        number: "919829012345",
        message: "Hi Priya, your order #4821 is out for delivery."
      },
      {
        number: "919829054321",
        message: "Your invoice is attached.",
        media: "document",
        url: "https://example.com/files/invoice-4821.pdf",
        filename: "Invoice 4821.pdf"
      }
    ]
  }),
});
const result = await response.json();

Example: send an approved Cloud API template

{
  "template_name": "order_update",
  "template_language": "en_US",
  "template_components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Priya"
        },
        {
          "type": "text",
          "text": "#4821"
        }
      ]
    }
  ],
  "contact": [
    {
      "number": "919829012345"
    }
  ]
}

Response

{
  "success": true,
  "message": "WhatsApp dispatch request created successfully",
  "data": [
    {
      "id": 48213,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "message": "Hi Priya, your order #4821 is out for delivery.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "whatsapp_contact": "919829012345",
        "meta_data": null
      }
    },
    {
      "id": 48214,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "message": "Your invoice is attached.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "whatsapp_contact": "919829054321",
        "meta_data": null
      }
    }
  ]
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.number": [
      "The contact.0.number field is required."
    ]
  }
}

Send SMS

POST/api/sms/send

Queue one or more SMS messages through your SMS API gateways or your own Android phones.

Body (JSON)

contact array Required: List of recipients. At least one item.
contact[].number string Required: Phone number with country code, digits only. Up to 255 characters.
contact[].message string Required: Message text. Long messages are split into segments, and credits are charged per segment.
contact[].sms_type string Optional: plain or unicode.
contact[].gateway_identifier string Optional: Identifier of one of your SMS gateways, to send this message through it.
contact[].schedule_at string Optional: Send later instead of now. Format YYYY-MM-DD HH:MM:SS, for example 2026-10-01 09:30:00.
method string Optional: Top level. android sends from your Android phones, api from an SMS API gateway. When left out, Kwital uses your API default and falls back to whichever has an active gateway.

Request

curl -X POST "https://kwital.com/api/sms/send" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "contact": [
    {
      "number": "919829012345",
      "message": "Your OTP for Kwital is 482913. It is valid for 10 minutes.",
      "sms_type": "plain"
    },
    {
      "number": "919829054321",
      "message": "Your appointment is confirmed for 1 October at 11:00.",
      "schedule_at": "2026-09-30 18:00:00"
    }
  ]
}'

$payload = [
    'contact' => [
        [
            'number' => '919829012345',
            'message' => 'Your OTP for Kwital is 482913. It is valid for 10 minutes.',
            'sms_type' => 'plain',
        ],
        [
            'number' => '919829054321',
            'message' => 'Your appointment is confirmed for 1 October at 11:00.',
            'schedule_at' => '2026-09-30 18:00:00',
        ],
    ],
];

$curl = curl_init('https://kwital.com/api/sms/send');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/sms/send', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact: [
      {
        number: "919829012345",
        message: "Your OTP for Kwital is 482913. It is valid for 10 minutes.",
        sms_type: "plain"
      },
      {
        number: "919829054321",
        message: "Your appointment is confirmed for 1 October at 11:00.",
        schedule_at: "2026-09-30 18:00:00"
      }
    ]
  }),
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Sms dispatch request created successfully",
  "data": [
    {
      "id": 48215,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "message": "Your OTP for Kwital is 482913. It is valid for 10 minutes.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "sms_contact": "919829012345",
        "meta_data": null
      }
    },
    {
      "id": 48216,
      "created_at": "2026-09-28 10:42:05",
      "status": "schedule",
      "message": {
        "message": "Your appointment is confirmed for 1 October at 11:00.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "sms_contact": "919829054321",
        "meta_data": null
      }
    }
  ]
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.message": [
      "The contact.0.message field is required."
    ]
  }
}

Send email

POST/api/email/send

Queue one or more emails. Send JSON, or multipart/form-data when you attach files.

Body (JSON or form data)

contact array Required: List of recipients. At least one item.
contact[].email string (email) Required: Recipient email address. Up to 255 characters.
contact[].subject string Required: Subject line. Up to 255 characters.
contact[].message string Required: Email body. HTML is allowed; <script> tags are removed.
contact[].sender_name string Optional: Name shown as the sender. Up to 255 characters.
contact[].reply_to_email string (email) Optional: Reply-to address.
contact[].gateway_identifier string Optional: Identifier of one of your active email gateways. Other values fail validation.
contact[].schedule_at string Optional: Send later instead of now. Format YYYY-MM-DD HH:MM:SS, for example 2026-10-01 09:30:00.
attachments[] file Optional: Form data only. Up to 5 files of up to 10 MB each: pdf, doc, docx, xls, xlsx, csv, txt, png, jpg, jpeg, gif, zip, rar, svg, webp. Every recipient in the request gets the same attachments.

Request

curl -X POST "https://kwital.com/api/email/send" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "contact": [
    {
      "email": "priya@example.com",
      "subject": "Your order #4821 has shipped",
      "message": "<p>Hi Priya,</p><p>Your order is on its way.</p>",
      "sender_name": "Aarav Organics",
      "reply_to_email": "support@example.com"
    }
  ]
}'

$payload = [
    'contact' => [
        [
            'email' => 'priya@example.com',
            'subject' => 'Your order #4821 has shipped',
            'message' => '<p>Hi Priya,</p><p>Your order is on its way.</p>',
            'sender_name' => 'Aarav Organics',
            'reply_to_email' => 'support@example.com',
        ],
    ],
];

$curl = curl_init('https://kwital.com/api/email/send');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/email/send', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact: [
      {
        email: "priya@example.com",
        subject: "Your order #4821 has shipped",
        message: "<p>Hi Priya,</p><p>Your order is on its way.</p>",
        sender_name: "Aarav Organics",
        reply_to_email: "support@example.com"
      }
    ]
  }),
});
const result = await response.json();

Example: attach files with form data

curl -X POST "https://kwital.com/api/email/send" \
  -H "Api-key: YOUR_API_KEY" \
  -F "contact[0][email]=priya@example.com" \
  -F "contact[0][subject]=Invoice 4821" \
  -F "contact[0][message]=Please find your invoice attached." \
  -F "attachments[]=@invoice-4821.pdf"

Response

{
  "success": true,
  "message": "Email dispatch request created successfully",
  "data": [
    {
      "id": 48217,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "subject": "Your order #4821 has shipped",
        "main_body": "<p>Hi Priya,</p><p>Your order is on its way.</p>"
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "email_contact": "priya@example.com",
        "meta_data": null
      }
    }
  ]
}

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.email": [
      "The contact.0.email must be a valid email address."
    ]
  }
}

Send with a GET request

GET/api/{channel}/send

For tools that can only call a URL. {channel} is whatsapp, sms or email. Every number or address in contacts gets the same message.

Query parameters

contacts string Required: Comma-separated phone numbers (WhatsApp, SMS) or email addresses (email).
message string Required: Message text, or the email body.
subject string Email: Email subject.
sender_name string Optional: Email only. Name shown as the sender.
reply_to_email string Optional: Email only. Reply-to address.
sms_type string Optional: SMS and WhatsApp. plain or unicode.
method string Optional: SMS only. android or api.
gateway_identifier string Optional: Send through a specific gateway (for WhatsApp, a device gateway).
schedule_at string Optional: Send later. Format YYYY-MM-DD HH:MM:SS.
api_key string Optional: Your API key, if you cannot send the Api-key header.

Plain URL form: https://kwital.com/api/sms/send?api_key=YOUR_API_KEY&contacts=919829012345,919829054321&message=Hello. Keys in URLs can end up in server logs, so prefer the header when your tool supports it.
Missing fields return 422 with the reason in data.contacts. With email contact verification turned on, an invalid address returns data.email.

Request

curl "https://kwital.com/api/sms/send?contacts=919829012345%2C919829054321&message=Our+store+opens+at+10+AM+today." \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$url = 'https://kwital.com/api/sms/send?' . http_build_query([
    'contacts' => '919829012345,919829054321',
    'message' => 'Our store opens at 10 AM today.',
]);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const params = new URLSearchParams({
  contacts: "919829012345,919829054321",
  message: "Our store opens at 10 AM today."
});
const response = await fetch(`https://kwital.com/api/sms/send?${params}`, {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Sms dispatch request created successfully",
  "data": [
    {
      "id": 48218,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "message": "Our store opens at 10 AM today.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "sms_contact": "919829012345",
        "meta_data": null
      }
    },
    {
      "id": 48219,
      "created_at": "2026-09-28 10:42:05",
      "status": "pending",
      "message": {
        "message": "Our store opens at 10 AM today.",
        "file_info": null
      },
      "contact": {
        "first_name": null,
        "last_name": null,
        "sms_contact": "919829054321",
        "meta_data": null
      }
    }
  ]
}

{
  "success": false,
  "message": "Validation error",
  "data": {
    "contacts": "Contacts, message & sms_type are required"
  }
}

Get a message and its status

GET/api/get/{channel}/{id}

Look up one message by the id returned in data[] when you sent it. {channel} is whatsapp, sms or email.

Path parameters

channel string Required: whatsapp, sms or email.
id integer Required: Message ID from the send response (data[].id).

In this response the recipient is always in contact.email_contact, even for SMS and WhatsApp (it holds the phone number).
The message object has message for SMS, message and file_info for WhatsApp, and subject and main_body for email.

Request

curl "https://kwital.com/api/get/sms/48215" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$curl = curl_init('https://kwital.com/api/get/sms/48215');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/get/sms/48215', {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Successfully fetched Sms from Logs",
  "data": {
    "id": 48215,
    "created_at": "2026-09-28 10:42:05",
    "status": "delivered",
    "message": {
      "message": "Your OTP for Kwital is 482913. It is valid for 10 minutes."
    },
    "contact": {
      "first_name": null,
      "last_name": null,
      "email_contact": "919829012345",
      "meta_data": null
    }
  }
}

{
  "success": false,
  "message": "Invalid SMS Log ID",
  "data": null
}

WhatsApp setup

List WhatsApp gateways

GET/api/whatsapp/gateways

Your WhatsApp devices and Cloud API numbers, default first. Use gateway_identifier and type when sending.

Request

curl "https://kwital.com/api/whatsapp/gateways" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$curl = curl_init('https://kwital.com/api/whatsapp/gateways');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/gateways', {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp gateways",
  "data": [
    {
      "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
      "name": "Aarav Organics",
      "type": "cloud",
      "status": "active",
      "is_default": true,
      "phone_number": "+91 98290 12345",
      "phone_number_id": "109834561234567"
    },
    {
      "gateway_identifier": "c2d8f1a4-6e3b-4a9c-8d7f-1b2e3c4d5a60",
      "name": "Front desk",
      "type": "node",
      "status": "active",
      "is_default": false,
      "phone_number": "919829054321",
      "phone_number_id": null
    }
  ]
}

List WhatsApp templates

GET/api/whatsapp/templates

Your WhatsApp templates with the name and language to pass as template_name and template_language. Only templates with meta_status APPROVED can be sent.

Request

curl "https://kwital.com/api/whatsapp/templates" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$curl = curl_init('https://kwital.com/api/whatsapp/templates');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/templates', {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp templates",
  "data": [
    {
      "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
      "template_name": "order_update",
      "template_language": "en_US",
      "category": "UTILITY",
      "meta_status": "APPROVED",
      "status": "active",
      "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}}, your order {{2}} is out for delivery.",
          "example": {
            "body_text": [
              [
                "Priya",
                "#4821"
              ]
            ]
          }
        }
      ]
    }
  ]
}

Get a device QR code

POST/api/qrcode

Start a session for a WhatsApp device (QR-code gateway) and get the QR code to scan with WhatsApp on the phone. Cloud API numbers do not use QR codes.

Body (JSON)

device_id integer Optional: ID of the device gateway.
gateway_uid string Optional: The device’s gateway_identifier.
device_name string Optional: The device’s name.

Send one of the three fields. With none, your most recently added device is used.
This endpoint has its own response shape: response holds the device, data.message comes from the WhatsApp service, and data.status is 200 with a QR code in data.qr, or 301 when the device reconnected without one.

Request

curl -X POST "https://kwital.com/api/qrcode" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "device_name": "Front desk"
}'

$payload = [
    'device_name' => 'Front desk',
];

$curl = curl_init('https://kwital.com/api/qrcode');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/qrcode', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_name: "Front desk"
  }),
});
const result = await response.json();

Response

{
  "response": {
    "id": 12,
    "name": "Front desk",
    "meta_data": []
  },
  "data": {
    "status": 200,
    "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "message": "…"
  }
}

{
  "response": null,
  "data": {
    "status": 404,
    "qr": "",
    "message": "Invalid whatsapp device"
  }
}

Cloud API templates

List Cloud API templates

GET/api/whatsapp/cloud/templates

Templates created for your WhatsApp Cloud API numbers, sorted by name, with their Meta review status.

Query parameters

gateway_identifier string Optional: Only templates of this Cloud API gateway.
meta_status string Optional: Filter by Meta status, for example APPROVED, PENDING or REJECTED.
per_page integer Optional: 1 to 100. Default 50.
page integer Optional: Page number. Default 1.

Request

curl "https://kwital.com/api/whatsapp/cloud/templates?meta_status=APPROVED&per_page=20" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$url = 'https://kwital.com/api/whatsapp/cloud/templates?' . http_build_query([
    'meta_status' => 'APPROVED',
    'per_page' => 20,
]);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const params = new URLSearchParams({
  meta_status: "APPROVED",
  per_page: 20
});
const response = await fetch(`https://kwital.com/api/whatsapp/cloud/templates?${params}`, {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp Cloud templates",
  "data": {
    "templates": [
      {
        "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
        "template_name": "order_update",
        "template_language": "en_US",
        "category": "UTILITY",
        "meta_status": "APPROVED",
        "meta_template_id": "1284930571204417",
        "status": "active",
        "editable": true,
        "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
        "cloud_id": 7,
        "components": [
          {
            "type": "BODY",
            "text": "Hi {{1}}, your order {{2}} is out for delivery.",
            "example": {
              "body_text": [
                [
                  "Priya",
                  "#4821"
                ]
              ]
            }
          }
        ],
        "rejected_reason": null,
        "submit_error": null,
        "quality_score": null,
        "updated_at": "2026-09-28T10:42:05+05:30"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1
    }
  }
}

Get a Cloud API template

GET/api/whatsapp/cloud/templates/{uid}

One template by its template_identifier.

Path parameters

uid string Required: The template’s template_identifier.

Request

curl "https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$curl = curl_init('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41', {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp Cloud template",
  "data": {
    "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
    "template_name": "order_update",
    "template_language": "en_US",
    "category": "UTILITY",
    "meta_status": "APPROVED",
    "meta_template_id": "1284930571204417",
    "status": "active",
    "editable": true,
    "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
    "cloud_id": 7,
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} is out for delivery.",
        "example": {
          "body_text": [
            [
              "Priya",
              "#4821"
            ]
          ]
        }
      }
    ],
    "rejected_reason": null,
    "submit_error": null,
    "quality_score": null,
    "updated_at": "2026-09-28T10:42:05+05:30"
  }
}

{
  "success": false,
  "message": "Cloud template not found",
  "data": []
}

Create a Cloud API template

POST/api/whatsapp/cloud/templates

Create a template and submit it to Meta for review. It can be sent once meta_status is APPROVED.

Body (JSON or form data)

gateway_identifier string Required: The Cloud API gateway that owns the template.
name string Required: Up to 512 characters. Saved in lowercase with underscores, for example order_update.
language string Required: Language code, for example en_US. Up to 20 characters.
category string Required: MARKETING, UTILITY or AUTHENTICATION.
body string Required: Template text, up to 1,024 characters. Use {{1}}, {{2}}… for variables.
header_format string Optional: NONE, TEXT, IMAGE, VIDEO, DOCUMENT or LOCATION.
header string Optional: Header text for TEXT headers. Up to 60 characters.
header_media file Optional: Form data only. Sample file for IMAGE, VIDEO or DOCUMENT headers.
header_location object Optional: latitude (−90 to 90), longitude (−180 to 180), name (up to 100) and address (up to 255) for LOCATION headers.
footer string Optional: Footer text. Up to 60 characters.

Request

curl -X POST "https://kwital.com/api/whatsapp/cloud/templates" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
  "name": "order_update",
  "language": "en_US",
  "category": "UTILITY",
  "body": "Hi {{1}}, your order {{2}} is out for delivery.",
  "footer": "Aarav Organics"
}'

$payload = [
    'gateway_identifier' => '4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88',
    'name' => 'order_update',
    'language' => 'en_US',
    'category' => 'UTILITY',
    'body' => 'Hi {{1}}, your order {{2}} is out for delivery.',
    'footer' => 'Aarav Organics',
];

$curl = curl_init('https://kwital.com/api/whatsapp/cloud/templates');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/cloud/templates', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gateway_identifier: "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
    name: "order_update",
    language: "en_US",
    category: "UTILITY",
    body: "Hi {{1}}, your order {{2}} is out for delivery.",
    footer: "Aarav Organics"
  }),
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Template submitted to Meta. Current status: PENDING",
  "data": {
    "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
    "template_name": "order_update",
    "template_language": "en_US",
    "category": "UTILITY",
    "meta_status": "PENDING",
    "meta_template_id": "1284930571204417",
    "status": "active",
    "editable": false,
    "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
    "cloud_id": 7,
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} is out for delivery.",
        "example": {
          "body_text": [
            [
              "Priya",
              "#4821"
            ]
          ]
        }
      }
    ],
    "rejected_reason": null,
    "submit_error": null,
    "quality_score": null,
    "updated_at": "2026-09-28T10:42:05+05:30"
  }
}

{
  "success": false,
  "message": "Validation error",
  "data": {
    "category": [
      "The selected category is invalid."
    ]
  }
}

{
  "success": false,
  "message": "Cloud gateway not found",
  "data": null
}

Edit a Cloud API template

PUT/api/whatsapp/cloud/templates/{uid}

Change a template and re-submit it to Meta. Only templates with "editable": true can be changed (Meta status APPROVED, REJECTED, PAUSED, DISABLED, or a failed submission).

Body (JSON or form data)

uid string Required: Path parameter: the template’s template_identifier.
category string Required: MARKETING, UTILITY or AUTHENTICATION.
body string Required: Template text, up to 1,024 characters.
header_format string Optional: Same values as when creating.
header string Optional: Up to 60 characters.
header_media file Optional: New header sample file. See the note below.
header_location object Optional: Same fields as when creating.
footer string Optional: Up to 60 characters.

To upload header_media, send a POST with form data and add the field _method=PUT.

Request

curl -X PUT "https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "UTILITY",
  "body": "Hi {{1}}, your order {{2}} will arrive today.",
  "footer": "Aarav Organics"
}'

$payload = [
    'category' => 'UTILITY',
    'body' => 'Hi {{1}}, your order {{2}} will arrive today.',
    'footer' => 'Aarav Organics',
];

$curl = curl_init('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41', {
  method: 'PUT',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category: "UTILITY",
    body: "Hi {{1}}, your order {{2}} will arrive today.",
    footer: "Aarav Organics"
  }),
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Template updated and re-submitted to Meta. Current status: PENDING",
  "data": {
    "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
    "template_name": "order_update",
    "template_language": "en_US",
    "category": "UTILITY",
    "meta_status": "PENDING",
    "meta_template_id": "1284930571204417",
    "status": "active",
    "editable": false,
    "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
    "cloud_id": 7,
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} is out for delivery.",
        "example": {
          "body_text": [
            [
              "Priya",
              "#4821"
            ]
          ]
        }
      }
    ],
    "rejected_reason": null,
    "submit_error": null,
    "quality_score": null,
    "updated_at": "2026-09-28T10:42:05+05:30"
  }
}

{
  "success": false,
  "message": "This template cannot be edited while Meta status is PENDING.",
  "data": []
}

Refresh a template’s status

POST/api/whatsapp/cloud/templates/{uid}/refresh

Fetch the latest review status for one template from Meta.

Path parameters

uid string Required: The template’s template_identifier.

Request

curl -X POST "https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41/refresh" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$curl = curl_init('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41/refresh');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/cloud/templates/9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41/refresh', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Template status refreshed from Meta",
  "data": {
    "template_identifier": "9f1c2a7e-5b3d-4c8e-a1f0-3e2d7c6b5a41",
    "template_name": "order_update",
    "template_language": "en_US",
    "category": "UTILITY",
    "meta_status": "APPROVED",
    "meta_template_id": "1284930571204417",
    "status": "active",
    "editable": true,
    "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
    "cloud_id": 7,
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} is out for delivery.",
        "example": {
          "body_text": [
            [
              "Priya",
              "#4821"
            ]
          ]
        }
      }
    ],
    "rejected_reason": null,
    "submit_error": null,
    "quality_score": null,
    "updated_at": "2026-09-28T10:42:05+05:30"
  }
}

WhatsApp chat

List conversations

GET/api/whatsapp/chat/conversations

WhatsApp conversations from your inbox, most recent first.

Query parameters

gateway_identifier string Optional: Only conversations on this WhatsApp gateway.
search string Optional: Match the contact’s name, WhatsApp number, email or phone.
unread_only boolean Optional: 1 to return only conversations with unread messages.
per_page integer Optional: 1 to 100. Default 30.
page integer Optional: Page number. Default 1.

Request

curl "https://kwital.com/api/whatsapp/chat/conversations?unread_only=1&per_page=30" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$url = 'https://kwital.com/api/whatsapp/chat/conversations?' . http_build_query([
    'unread_only' => 1,
    'per_page' => 30,
]);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const params = new URLSearchParams({
  unread_only: 1,
  per_page: 30
});
const response = await fetch(`https://kwital.com/api/whatsapp/chat/conversations?${params}`, {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp conversations",
  "data": {
    "conversations": [
      {
        "conversation_id": 318,
        "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
        "gateway_name": "Front desk",
        "gateway_type": "cloud",
        "contact": {
          "id": 5521,
          "name": "Priya Sharma",
          "whatsapp": "919829012345"
        },
        "unread_count": 2,
        "last_message_at": "2026-09-28T10:40:12+05:30",
        "latest_message": {
          "id": 90412,
          "body": "Is the order shipped?",
          "created_at": "2026-09-28T10:40:12+05:30"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 30,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

{
  "success": false,
  "message": "WhatsApp gateway not found",
  "data": null
}

Get a conversation

GET/api/whatsapp/chat/conversations/{id}

Messages in one conversation, oldest first. Opening a conversation marks it as read unless you pass mark_read=0.

Parameters

id integer Required: Path parameter: conversation_id.
per_page integer Optional: 1 to 100. Default 50.
page integer Optional: Page number. Default 1.
mark_read boolean Optional: Default 1. Set 0 to keep the unread count.

Request

curl "https://kwital.com/api/whatsapp/chat/conversations/318?mark_read=0" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

$url = 'https://kwital.com/api/whatsapp/chat/conversations/318?' . http_build_query([
    'mark_read' => 0,
]);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const params = new URLSearchParams({
  mark_read: 0
});
const response = await fetch(`https://kwital.com/api/whatsapp/chat/conversations/318?${params}`, {
  method: 'GET',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
  },
});
const result = await response.json();

Response

{
  "success": true,
  "message": "WhatsApp conversation thread",
  "data": {
    "conversation": {
      "conversation_id": 318,
      "gateway_identifier": "4b7e9d12-8c3a-4f6e-9b21-7a5c3e1d0f88",
      "gateway_name": "Front desk",
      "gateway_type": "cloud",
      "contact": {
        "id": 5521,
        "name": "Priya Sharma",
        "whatsapp": "919829012345"
      },
      "unread_count": 2,
      "last_message_at": "2026-09-28T10:40:12+05:30"
    },
    "messages": [
      {
        "id": 90412,
        "body": "Is the order shipped?",
        "file_info": null,
        "created_at": "2026-09-28T10:40:12+05:30",
        "statuses": [],
        "participants": []
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

{
  "success": false,
  "message": "Conversation not found",
  "data": []
}

Reply in a conversation

POST/api/whatsapp/chat/conversations/{id}/reply

Send a reply to the contact through the conversation’s WhatsApp gateway.

Body (JSON or form data)

id integer Required: Path parameter: conversation_id.
body string Unless media is sent: Reply text. Up to 4,096 characters.
media_url string (URL) Optional: Public URL of an image or file to send. Up to 2,048 characters.
media file Optional: Form data only. A file of up to 16 MB, used instead of media_url.

Request

curl -X POST "https://kwital.com/api/whatsapp/chat/conversations/318/reply" \
  -H "Api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Yes, it was shipped this morning. Tracking: AWB 58291034."
}'

$payload = [
    'body' => 'Yes, it was shipped this morning. Tracking: AWB 58291034.',
];

$curl = curl_init('https://kwital.com/api/whatsapp/chat/conversations/318/reply');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Api-key: YOUR_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

// Run on your server (Node.js 18+) so your API key stays private.
const response = await fetch('https://kwital.com/api/whatsapp/chat/conversations/318/reply', {
  method: 'POST',
  headers: {
    'Api-key': 'YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    body: "Yes, it was shipped this morning. Tracking: AWB 58291034."
  }),
});
const result = await response.json();

Response

{
  "success": true,
  "message": "Reply sent",
  "data": {
    "message_id": 90413,
    "body": "Yes, it was shipped this morning. Tracking: AWB 58291034.",
    "created_at": "2026-09-28T10:43:30+05:30",
    "statuses": []
  }
}

{
  "success": false,
  "message": "Message body or media is required.",
  "data": []
}

Errors

Check the HTTP status first, then read message (or error for API key and plan problems). Send Accept: application/json so every error comes back as JSON.

StatusWhen it happensExample body

403 No API key in the request

{"status": "error", "message": "API key is required. Provide via header (Api-key) or URL parameter (api_key)", "error": "Invalid Api Key"}

403 The API key is wrong or was regenerated {"status": "error", "error": "Invalid Api Key"}

403 Your plan has expired {"status": "error", "error": "Your Subscription Is Expired! Buy A New Plan"}

422 A field is missing or invalid on a POST send endpoint

{"success": false, "message": "Validation failed", "errors": {"contact.0.message": ["The contact.0.message field is required."]}}

422 Invalid input on the GET send, template and chat endpoints {"success": false, "message": "Validation error", "data": {"body": ["The body field is required."]}}

422 WhatsApp gateway or template choices conflict

{"success": false, "message": "template_name requires gateway_type \"cloud\" — templates cannot be sent through a WA-Web (node) device.", "data": []}

404 The message, template, gateway or conversation does not exist in your account {"success": false, "message": "Invalid WHATSAPP Log ID", "data": null}

400 A WhatsApp media URL could not be downloaded {"success": false, "message": "Failed to download file from URL: …", "data": []}

429 More than 60 requests in a minute from one IP address {"message": "Too Many Attempts."}

500 The send could not be queued, for example not enough credits or no active gateway {"success": false, "message": "Insufficient credits — this message needs 3 credits (…) but you have 1.", "data": []}

Ready to connect your software?

Create an account, connect a WhatsApp number, SMS gateway or email gateway, and generate your API key in a few minutes.

Create an account Talk to us