🏠 Home ℹ️ About Us
📩 Contact Us 🔔 Notice
🔑 Log In 📝 Free Sign Up
⚙️ Developer Reference

WhatsApp Business (WABA) API

Send template messages, custom messages, and files via WhatsApp channel through the iSMS platform. This guide covers authentication, request formats, responses, webhooks, template management and balance. Also see the META Messenger API →

{ } JSON API 🧾 Templates, Text & Files 📡 Webhooks 🗂 Template Management v2.0 · Updated March 5, 2026
💬
Billing: All WABA messages are charged per message by Meta across all four message categories. The 24-hour customer service window is a messaging rule only — it defines when free-form replies are allowed, not how messages are billed. Message categories: Marketing · Utility · Authentication/OTP · Service/Customer Service (user-initiated conversations) — all per message. Pricing varies by destination country. Contact us for a quote.

🚀 Overview

One JSON endpoint is used for all WhatsApp outbound message types. Separate endpoints cover templates and balance.
template

Send pre-approved Meta message templates with dynamic variable substitution.

✓ Available anytime
message

Send custom free-text messages to users who have recently messaged your WABA number.

⏱ Within 24-hour window
file

Send images, PDFs, documents, and other files via a direct publicly accessible URL.

⏱ Within 24-hour window

Template messages (Marketing, Utility, Authentication/OTP) can be sent anytime. Custom/free-text messages and files are only available within an active 24-hour user-initiated window — this is the Service message category. All four categories are charged per message.

Supported channels

whatsapp✓ Available
viber⏳ Under development
ℹ️
This API is available to all registered iSMS customers with an active WABA account. Contact our team to get your AppId and AppSecret credentials.

🔗 API Endpoint

Three endpoint URLs are provided. We recommend using Resource URL 1 for production — configure your integration to fall back to URLs 2 and 3 if the primary is unavailable.
POSThttps://www.isms.com.my/isms_send_waba.php
URL 1https://www.isms.com.my/isms_send_waba.phpRecommended
URL 2https://smtpapi.vocotext.com/isms_send_waba.php
URL 3https://smtpapi2.vocotext.com/isms_send_waba.php
SettingValue
Content-Typeapplication/json
MethodPOST only
EncodingUTF-8 JSON
⚠️
All request bodies must be valid JSON. Ensure your HTTP client sets the Content-Type: application/json header in every request.

🔐 Authentication

Every request includes both iSMS account login credentials and WABA application credentials.
un / pwdYour iSMS account username and password.
AppId / AppSecretWABA application credentials issued when your WABA account is activated.
FromSender phone number — must be your registered WABA number.
agreedtermMust be set to YES — confirms acceptance of iSMS Terms.
🔒
Keep passwords and application secrets on your server. Never place them in browser JavaScript, mobile applications or public source repositories.
🛡️
IP whitelist: API requests must come from a server IP address whitelisted on your account — other IPs are rejected with error 1003. See IP Whitelisting & Fixed-IP Relay.

🧩 Request Parameters

Complete parameter reference for the Send Message API. Required parameters must be in every request. Conditional parameters depend on message type.
ParameterTypeRequiredDescriptionExample
AppIdStringRequiredApplication ID from iSMS console8671971xxx
AppSecretStringRequiredApplication secret from iSMS console0b34b7cc...
unStringRequiredYour iSMS account usernameiSMS
pwdStringRequiredYour iSMS account passwordiSMS123
agreedtermStringRequiredMust be set to "YES" — confirms acceptance of iSMS TermsYES
ChannelTypeStringRequiredMessage channel. Currently supported: whatsapp. For Facebook Messenger, use the separate Messenger API.whatsapp
TypeStringRequiredMessage type: template, message, or filetemplate
FromStringRequiredSender phone number — must be registered WABA number604642xxxx
ToStringRequiredRecipient phone number in international format6018222xxxx
TemplateCodeStringConditionalTemplate code — required when Type = template744c4b5c...
LanguageStringConditionalTemplate language code — required when Type = templateen
TemplateParamsObjectConditionalTemplate variable values as JSON — when Type = template{"param1":"val"}
ContentStringConditionalMessage text body — required when Type = messageHello World
fileUrlStringConditionalDirect public URL to file — required when Type = filehttps://...
fileNameStringConditionalDisplay name for the file — required when Type = fileinvoice.pdf
⚠️
The fileUrl must be a direct, publicly accessible URL. URLs behind Cloudflare or similar proxy services may not be accessible by the WABA delivery system.

🧾 Send Template Message

Template messages (Marketing, Utility, Authentication/OTP) are pre-approved by WhatsApp and can be sent anytime — ideal for notifications, OTP, reminders, and transactional alerts. These are charged per message regardless of session status.

JSON Request Body

JSONRequest Body
{
  "AppId": "8671971xxxxxxx",
  "AppSecret": "0b34b7cc0cbxxxxxc",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "Type": "template",
  "TemplateCode": "90934259xxxxxx",
  "TemplateParams": {
    "param1": "your value here"
  },
  "Language": "en",
  "From": "604xxxxxxx",
  "To": "601X-XXXXXXX"
}

PHP Example

PHPsend_template.php
<?php
$url = "https://www.isms.com.my/isms_send_waba.php";

$data = [
    "AppId"       => "your_app_id",
    "AppSecret"   => "your_app_secret",
    "un"          => "your_username",
    "pwd"         => "your_password",
    "agreedterm"  => "YES",
    "Type"        => "template",
    "TemplateCode" => "your_template_code",
    "TemplateParams" => ["param1" => date("Y-m-d H:i:s")],
    "Language"    => "en",
    "From"        => "your_waba_number",
    "To"          => "recipient_number"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo "cURL error: " . curl_error($ch);
} else {
    $result = json_decode($response, true);
    echo "Status: " . $result['statusCode'];
    echo " | MessageId: " . $result['messageId'];
}

curl_close($ch);
?>

💬 Send Custom Message

Send free-form text messages. Only available within the active 24-hour Service session — triggered when a user messages your WABA number first. Service messages are charged per message — the 24-hour window only defines when free-form replies are allowed, not how messages are billed.
JSONRequest Body
{
  "AppId": "867197xxxx",
  "AppSecret": "0b34b7ccxxxx",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "Type": "message",
  "Content": "Hello! Your appointment is confirmed for tomorrow at 10am.",
  "From": "604xxxxxxx",
  "To": "601X-XXXXXXX"
}
PHPsend_message.php
<?php
$url = "https://www.isms.com.my/isms_send_waba.php";

$data = [
    "AppId"      => "your_app_id",
    "AppSecret"  => "your_app_secret",
    "un"         => "your_username",
    "pwd"        => "your_password",
    "agreedterm" => "YES",
    "Type"       => "message",
    "Content"    => "Hello! Your appointment is confirmed for tomorrow at 10am.",
    "From"       => "your_waba_number",
    "To"         => "recipient_number"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
echo $response;
curl_close($ch);
?>

📎 Send File

Send images, PDFs, and other documents via a direct public URL. The file must be accessible by our servers without authentication.
JSONRequest Body
{
  "AppId": "8671971xxxxx",
  "AppSecret": "0b34b7cc0cbxxxxx",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "Type": "file",
  "fileUrl": "https://example.com/files/marketing.png",
  "fileName": "marketing_brochure",
  "From": "604xxxxxxx",
  "To": "601X-XXXXXXX"
}
PHPsend_file.php
<?php
$url = "https://www.isms.com.my/isms_send_waba.php";

$data = [
    "AppId"      => "your_app_id",
    "AppSecret"  => "your_app_secret",
    "un"         => "your_username",
    "pwd"        => "your_password",
    "agreedterm" => "YES",
    "Type"       => "file",
    "fileUrl"    => "https://example.com/files/marketing.png",
    "fileName"   => "marketing_brochure",
    "From"       => "your_waba_number",
    "To"         => "recipient_number"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
echo $response;
curl_close($ch);
?>

✅ Response Format

Success Response

JSONSuccess response
{
  "requestId": "C9122953-C329-3D9A-9191-7EB5D70D54FC",
  "statusCode": "OK",
  "messageId": "202311882856605014114304"
}
ParameterTypeDescription
requestIdStringUnique identifier for the API request — use for support enquiries
statusCodeStringOK or 0 = success. Any other value indicates failure. See Error Codes.
messageIdStringUnique identifier for the sent message — use for delivery status tracking

❌ Error Codes

Any statusCode other than 0 / OK means the request was not accepted.

General Errors

0 / OK
Request successful
-1
The system is busy — retry after a short delay
1000
Unknown error
1001
Authentication failed — check username and password
1002
Account suspended or expired
1003
IP address not allowed — see IP Whitelisting & Fixed-IP Relay
1004
Insufficient credits
1008
Missing required parameter

WABA-Specific Errors

50500
Invalid destination phone number
70500
Invalid WABA account
70501
Invalid WABA API key
70502
Insufficient WABA credits

Application & Session Errors

40001
Invalid AppSecret or AccessToken
40008
Invalid message type
41000
Required parameter not specified
42001
Access token expired
45001
API call limit exceeded
45010
Reply time limit exceeded (outside 24h window)
47001
JSON parsing error — check request body format
48001
Not authorized to call this API

Template Errors

60005
templateCode parameter not specified
60006
Template code does not exist
60012
Invalid parameter format
70001
Scenario sending policy not configured

🛡️ IP Whitelisting & Fixed-IP Relay

API requests are accepted only from server IP addresses whitelisted on your account. If your application runs on cloud hosting where the outgoing IP keeps changing — AWS, Google Cloud, Azure, serverless or auto-scaling platforms — send your API calls through one server with a fixed IP and whitelist that single address.
🔒
Why a whole cloud IP range cannot be whitelisted: those ranges are shared by every other customer of the cloud provider. Whitelisting a range would let any server inside it pass the IP check on your account, so only individual fixed IP addresses are accepted.
💡
Check this first: most cloud providers can give your application a fixed outgoing IP — for example an Elastic IP or NAT Gateway on AWS, or a reserved static IP / Cloud NAT on Google Cloud. If yours can, whitelist that IP and keep calling the API directly; no relay is needed. Use the relay below when a fixed outgoing IP is not available or not practical on your platform.

Request Flow

Direct from a changing IP — rejected
☁️Your applicationAWS · Google Cloud · AzureIP keeps changing
HTTPS request sent directly
🔒iSMS APIChecks the calling IPIP not whitelisted
Blocked
⛔Request rejectedNothing is sentError 1003
Through a fixed-IP relay — accepted
1☁️Your applicationAny cloud, any IPIP keeps changing
HTTPS + relay key
2🖥️Fixed-IP relayYour VPS or hosting203.0.113.10
HTTPS, same JSON
3✅iSMS APIChecks the calling IPRelay IP whitelisted
WhatsApp
4📱RecipientReceives the WhatsApp messageDelivered
📬
Inbound-message and delivery-status webhooks are sent by iSMS straight to your webhook URL — they do not pass through the relay.

How the Relay Works

1

Your application → relay

Your application sends its normal JSON request to your relay URL instead of the iSMS API, and adds a secret X-Relay-Key header. Its own IP can be anything.

2

Relay → iSMS API

The relay checks the key, then forwards the same JSON body to the API over HTTPS. The request now arrives from the relay's fixed IP.

3

iSMS checks and accepts

That fixed IP is on your whitelist, so the request passes the IP check and is processed like any direct API call — same AppId / AppSecret, un / pwd, template and credit rules.

4

Delivery and response

The message goes out to the recipient, and the API response (statusCode, messageId) travels back through the relay to your application unchanged.

Setting It Up

What to doDetails
1. Get a fixed-IP serverA small VPS, or a hosting plan with a dedicated IP, is enough — the relay only passes small HTTPS requests. It needs one fixed public IPv4 address, PHP with cURL, and an HTTPS (SSL) address.
2. Whitelist its IPOn that server, run curl -4 ifconfig.me to confirm its outgoing IP, then submit that IP under Account → Request IP Whitelist in the member portal — see the Request IP Whitelist guide.
3. Install the relayUpload api_relay.php (below) and replace $RELAY_KEY with your own long random secret.
4. Point your application at itChange the API URL to your relay URL and add the X-Relay-Key header. The JSON body, your credentials and your response handling stay the same.

PHP Relay Script

PHPapi_relay.php
<?php
// api_relay.php — upload to your fixed-IP server (the IP on your whitelist)

$RELAY_KEY = 'CHANGE-ME-long-random-secret';   // known only to your own application

// The only API addresses this relay will forward to
$ALLOWED = [
    'isms_send_waba.php'                     => 'https://www.isms.com.my/isms_send_waba.php',
    'api_waba_list_template_json.php'        => 'https://smtpapi.vocotext.com/api_waba_list_template_json.php',
    'api_waba_list_template_detail_json.php' => 'https://smtpapi.vocotext.com/api_waba_list_template_detail_json.php',
    'api_waba_create_template.php'           => 'https://smtpapi.vocotext.com/api_waba_create_template.php',
    'api_waba_delete_template.php'           => 'https://smtpapi.vocotext.com/api_waba_delete_template.php',
    'api_waba_balance_json.php'              => 'https://smtpapi.vocotext.com/api_waba_balance_json.php',
];

// 1. Only your own application may use this relay
$key = $_SERVER['HTTP_X_RELAY_KEY'] ?? '';
if (!hash_equals($RELAY_KEY, $key)) {
    http_response_code(403);
    exit('RELAY: FORBIDDEN');
}

// 2. Forward to the addresses listed above only — never to a URL supplied by the caller
$endpoint = $_GET['endpoint'] ?? '';
if (!is_string($endpoint) || !isset($ALLOWED[$endpoint])) {
    http_response_code(400);
    exit('RELAY: UNKNOWN ENDPOINT');
}

// 3. Pass the JSON body on unchanged — it leaves from this server's fixed IP
$ch = curl_init($ALLOWED[$endpoint]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, file_get_contents('php://input'));
curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);   // the whitelist is IPv4
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 4. Hand the API response back to your application as-is
if ($result === false) {
    http_response_code(502);
    exit('RELAY: API UNREACHABLE');
}
http_response_code($status);
header('Content-Type: application/json');
echo $result;
?>
ℹ️
The sample forwards sending to Resource URL 1. If your integration falls back to URLs 2 and 3, add each one to $ALLOWED under its own name and call that name when the primary is unavailable. The relay is now part of your sending path, so host it somewhere reliable.

The Only Change in Your Application

PHPyour application
<?php
// Before — direct to the API (rejected whenever your IP changes)
$url = "https://www.isms.com.my/isms_send_waba.php";
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);

// After — through your relay (the JSON body stays exactly the same)
$url = "https://relay.example.com/api_relay.php?endpoint=isms_send_waba.php";
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Relay-Key: CHANGE-ME-long-random-secret"
]);
?>
🔐
Protect the relay. An unprotected relay cancels out the protection of IP whitelisting — anyone holding your API credentials could send through it. Serve it over HTTPS only, and keep the relay key long, random and out of public code; change it at once if it is ever exposed. Keep the address list in the script — never turn the relay into a general proxy that forwards to any URL it is given. If a relayed request times out, do not resend it blindly: the first attempt may already have been accepted, and a resend would deliver (and charge) the message twice.

📥 Inbound Messages (Webhook)

When a WhatsApp user sends a message to your WABA number, iSMS will immediately forward it to your registered webhook URL via an HTTPS POST request. The entire payload is delivered as a single response parameter encoded in base64.
ℹ️
Contact us to register your webhook URL. Once configured, all inbound messages to your WABA number will be pushed to your endpoint automatically.

Webhook Method & URL Format

POSThttps://{yoururl}?response=xxxxx
ParameterLocationTypeDescription
response Query String String The full inbound message payload encoded as base64_encode(). Decode this value to retrieve the JSON object containing all message fields.

Decoded Payload Fields

After decoding the response parameter with base64_decode(), you will receive a JSON object with the following fields:

ParameterTypeRequiredDescription
MessageIdStringYesThe message ID.
FromStringYesThe phone number of the message sender.
ToStringYesThe phone number of the message receiver.
TimestampLongYesThe timestamp is a Unix timestamp in milliseconds.
DisplayNameStringYesThe display name of the message sender.
TypeStringYesThe type of the media resources that are included in the message. Valid values:
TEXT LOCATION DOCUMENT VIDEO AUDIO REPLY IMAGE CONTACTS
MessageStringYesThe content of the message. If Type is TEXT, the message content is text. For every other type, Message is a JSON object — see Message Payload by Type.
NameStringYesThe name of the end user.

Sample Decoded Payload (JSON)

This is what you get after base64_decode($response) and json_decode():

JSONDecoded payload
{
  "MessageId": "C9122953-C329-3D9A-9191-7EB5D70D54FC",
  "From":      "60123456789",
  "To":        "604642XXXXX",
  "Timestamp": 1712390400000,
  "DisplayName": "Ahmad Razif",
  "Name":      "Ahmad Razif",
  "Type":      "TEXT",
  "Message":   "Hello, I would like to know more about your services."
}

🗂 Message Payload by Type

When Type is not TEXT, the Message field is a JSON object with the fields below.
LOCATIONA location
latitudeFloatRequired

The latitude of the location.

longitudeFloatRequired

The longitude of the location.

nameStringOptional

The name of the location.

addressStringOptional

The address of the location.

JSONMessage value
{
  "latitude":  3.1478,
  "longitude": 101.6953,
  "name":      "Kuala Lumpur City Centre",
  "address":   "Kuala Lumpur, 50088, Malaysia"
}
IMAGEAn image
urlStringRequired

The URL of the image file.

captionStringOptional

The caption of the image.

JSONMessage value
{
  "url":     "https://cdn.example.com/photo.jpg",
  "caption": "Check out our latest product!"
}
VIDEOA video file
urlStringRequired

The URL of the video file.

captionStringOptional

The caption of the video.

JSONMessage value
{
  "url":     "https://cdn.example.com/promo.mp4",
  "caption": "Watch our promo video"
}
AUDIOAn audio file
urlStringRequired

The URL of the audio file.

JSONMessage value
{
  "url": "https://cdn.example.com/voicenote.ogg"
}
DOCUMENTA document
urlStringRequired

The URL of the document file.

filenameStringOptional

The file name of the document as displayed to the recipient.

captionStringOptional

The caption of the document.

JSONMessage value
{
  "url":      "https://cdn.example.com/invoice.pdf",
  "filename": "Invoice_April2025.pdf",
  "caption":  "Please find your invoice attached."
}
REPLYA reply button
replyMessageIdStringRequired

The MessageId of the original message the user is replying to.

textStringRequired

The text content of the reply.

JSONMessage value
{
  "replyMessageId": "C9122953-C329-3D9A-9191-7EB5D70D54FC",
  "text":           "Yes, I confirm my appointment."
}

🐘 PHP Webhook Receiver

Save this as your webhook endpoint file on your server. Register its URL with iSMS support.
PHPwaba_inbound_webhook.php
<?php
/**
 * waba_inbound_webhook.php
 * iSMS will POST to: https://yoursite.com/waba_inbound_webhook.php?response=xxxxx
 * The ?response= param is base64 encoded JSON.
 */

// 1. Read the raw base64-encoded response from query string
$encoded = $_POST['response'] ?? $_GET['response'] ?? '';

if (empty($encoded)) {
    http_response_code(400);
    echo 'Missing response parameter';
    exit;
}

// 2. Decode the base64 payload
$json = base64_decode($encoded);

if ($json === false) {
    http_response_code(400);
    echo 'Invalid base64 encoding';
    exit;
}

// 3. Parse JSON into array
$msg = json_decode($json, true);

if (!$msg || !isset($msg['MessageId'])) {
    http_response_code(400);
    echo 'Invalid payload';
    exit;
}

// 4. Extract fields
$messageId   = $msg['MessageId']   ?? '';
$from        = $msg['From']        ?? '';
$to          = $msg['To']          ?? '';
$timestamp   = $msg['Timestamp']   ?? 0;
$displayName = $msg['DisplayName'] ?? '';
$name        = $msg['Name']        ?? '';
$type        = $msg['Type']        ?? 'TEXT';
$message     = $msg['Message']     ?? '';

// 5. Convert timestamp (milliseconds) to readable datetime
$datetime = date('Y-m-d H:i:s', $timestamp / 1000);

// 6. Your business logic here — e.g. save to DB, trigger auto-reply, etc.
// Example: log to file
$log = sprintf(
    "[%s] From:%s To:%s Type:%s Msg:%s\n",
    $datetime, $from, $to, $type, $message
);
file_put_contents('inbound_log.txt', $log, FILE_APPEND | LOCK_EX);

// 7. Always respond 200 OK — iSMS may retry if it receives non-200
http_response_code(200);
echo 'OK';
?>
⚠️
Your webhook endpoint must respond with HTTP 200 within 10 seconds. If iSMS receives a non-200 response or timeout, the webhook will be retried. Always return 200 OK immediately and process the payload asynchronously if needed.
✅
Use the MessageId field to deduplicate messages in case of retries — store processed IDs in your database and skip any that have already been handled.

📬 Delivery Status (Webhook)

Receive real-time delivery status updates via webhook. WhatsApp Business API provides true handset-level delivery tracking — unlike SMS which only confirms Telco SMSC receipt, WABA reports actual message status at the recipient's device.
MessageIdUnique identifier for the sent message
FromSender phone number (your WABA number)
ToRecipient phone number
StatusMessage status: Sent (submitted to WhatsApp), Delivered (confirmed received at recipient's handset), or Read (recipient opened the message). Unlike SMS DLR, WhatsApp delivery status reflects true handset-level confirmation.
ErrorDescriptionError description if message failed to deliver

📄 Template List API

Fetch all WhatsApp message templates associated with your account — including type, name, approval status, language, and components. The component field is base64 encoded.
POSThttps://smtpapi.vocotext.com/api_waba_list_template_json.php
ParameterTypeRequiredDescription
unStringRequiredYour iSMS account username
pwdStringRequiredYour iSMS account password

JSON Request Body

JSONRequest body
{
  "un": "your_username",
  "pwd": "your_password"
}

Success Response

JSONSuccess response
{
  "status": "success",
  "data": [
    {
      "templateType": "PROMOTIONAL",
      "name": "New Year Offer",
      "auditStatus": "pass",
      "language": "en",
      "templateCode": "1XXXXXXXXX90",
      "last_updated_on": "2024-07-21T14:55:30Z",
      "component": "eyJ0eXBlIjogIkJPRFki...",
      "status_code": "200",
      "status_message": "Approved"
    }
  ]
}
ℹ️
The component field is base64 encoded. Use a base64 decoder (or PHP's base64_decode()) to read template component data.

PHP Example (POST)

PHPlist_templates.php
<?php
$url  = "https://smtpapi.vocotext.com/api_waba_list_template_json.php";
$data = json_encode(["un" => "your_username", "pwd" => "your_password"]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
$templates = json_decode($response, true);

if ($templates['status'] === 'success') {
    foreach ($templates['data'] as $tpl) {
        echo $tpl['name'] . " — " . $tpl['auditStatus'] . "\n";
    }
}
curl_close($ch);
?>

🔎 Template Detail API

Fetch a single approved template by its templateCode — including its category and components. Use this before sending to confirm a template is approved and to read the variables it expects. Only templates with auditStatus = pass are returned.
POSThttps://smtpapi.vocotext.com/api_waba_list_template_detail_json.php
ParameterTypeRequiredDescription
unStringRequiredYour iSMS account username
pwdStringRequiredYour iSMS account password
templateCodeStringRequiredThe template code to look up (see Template List API). Send it as a string, in quotes.

JSON Request Body

JSONRequest body
{
  "un": "your_username",
  "pwd": "your_password",
  "templateCode": "1242381527277813760"
}

Success Response

JSONSuccess response
{
  "status": "success",
  "data": [
    {
      "templateType": "WHATSAPP",
      "name": "order_update_01",
      "auditStatus": "pass",
      "language": "en",
      "templateCode": "1242381527277813760",
      "last_updated_on": "2026-03-21 14:55:30",
      "component": "eyJ0eXBlIjogIkJPRFki...",
      "category": "UTILITY",
      "status_code": "OK"
    }
  ]
}

Error Response

JSONError response
{
  "status": "error",
  "message": "Invalid Data"
}
ℹ️
Invalid Data means the template code does not exist under your account, or the template has not been approved yet. The component field is base64 encoded, the same as in the Template List API.

PHP Example

PHPtemplate_detail.php
<?php
$url  = "https://smtpapi.vocotext.com/api_waba_list_template_detail_json.php";
$data = json_encode([
    "un"           => "your_username",
    "pwd"          => "your_password",
    "templateCode" => "1242381527277813760"
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
$result   = json_decode($response, true);

if ($result['status'] === 'success') {
    $tpl        = $result['data'][0];
    $components = json_decode(base64_decode($tpl['component']), true);
    echo $tpl['name'] . " (" . $tpl['category'] . ")\n";
    print_r($components);
} else {
    echo $result['message'];
}
curl_close($ch);
?>

➕ Create Template API

Create a new WhatsApp message template and submit it directly to Meta for approval. Newly created templates appear in the Template List API with their review status.
POSThttps://smtpapi.vocotext.com/api_waba_create_template.php
ParameterTypeRequiredDescription
unStringRequiredYour iSMS account username
pwdStringRequiredYour iSMS account password
AppIdStringRequiredYour WABA App ID
AppSecretStringRequiredYour WABA App Secret
agreedtermStringRequiredSet to YES to agree with the API terms & conditions
FromStringRequiredYour WABA business number
templateTypeStringOptionalTemplate channel type. Default: WHATSAPP
nameStringRequiredTemplate name — lowercase letters, numbers and underscore only, max 60 characters (e.g. order_update_01)
languageStringRequiredTemplate locale code, e.g. en, ms, zh_CN, id
categoryStringRequiredUTILITY (transactional) / MARKETING (promotional) / AUTHENTICATION (OTP)
componentsArrayRequiredTemplate component objects — see Template Components below
exampleObjectConditionalSample values for each $(variable) used — required by Meta review whenever the template contains variables

Template Components

ComponentRequiredDescription
BODYRequiredtext up to 1,024 characters. Supports $(variable) placeholders and WhatsApp formatting: *bold* _italic_ ~strike~
HEADEROptionalformat: TEXT (text up to 60 chars) or IMAGE / VIDEO / DOCUMENT (url = publicly accessible sample media for Meta review; add fileName for documents)
FOOTEROptionaltext up to 60 characters
BUTTONSOptionalbuttons array — up to 3 QUICK_REPLY buttons, or up to 2 call-to-action buttons (max 2 URL, max 1 PHONE_NUMBER). Quick replies cannot be mixed with URL / call buttons. A URL may end with one $(variable) (urlType: dynamic); button text max 25 characters

JSON Request Body — Utility / Marketing

JSONRequest body
{
  "AppId": "your_app_id",
  "AppSecret": "your_app_secret",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "From": "your_waba_number",
  "templateType": "WHATSAPP",
  "name": "order_update_01",
  "language": "en",
  "category": "UTILITY",
  "components": [
    { "type": "BODY", "text": "Hi $(name), your order $(orderid) has been shipped." },
    { "type": "FOOTER", "text": "Reply STOP to unsubscribe" },
    { "type": "BUTTONS", "buttons": [
        { "type": "URL", "text": "Track Order", "urlType": "dynamic", "url": "https://example.com/track/$(orderid)" }
    ] }
  ],
  "example": { "name": "Ali", "orderid": "INV-10023" }
}

Authentication (OTP) Templates — Fixed Format

⚠️
Authentication templates use a fixed format defined by Meta. The BODY text must be an empty string — Meta generates the message wording automatically, and the verification code parameter when sending is verificationCode. Configurable options: addSecretRecommendation (security disclaimer) on BODY, codeExpirationMinutes (1–90) on FOOTER, and a COPY_CODE button (or ONE_TAP with autofillText / packageName / signatureHash for Android autofill). Submitting body text for an Authentication template is rejected with InvalidParameter.AuthenticationBodyTextMustEmpty.
JSONRequest body
{
  "AppId": "your_app_id",
  "AppSecret": "your_app_secret",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "From": "your_waba_number",
  "templateType": "WHATSAPP",
  "name": "login_otp_01",
  "language": "en",
  "category": "AUTHENTICATION",
  "components": [
    { "type": "BODY", "text": "", "addSecretRecommendation": "true" },
    { "type": "FOOTER", "codeExpirationMinutes": 10 },
    { "type": "BUTTONS", "buttons": [ { "type": "COPY_CODE", "text": "Copy code" } ] }
  ]
}

Success Response

JSONSuccess response
{
  "requestId": "3876f7cb-77fd-47a1-9f34-b673xxxxxxx",
  "statusCode": "OK",
  "templateCode": "1242381527277813760",
  "templateName": "order_update_01"
}

Error Response

JSONError response
{
  "requestId": "ec33ce8c-e871-4764-a39f-72f5xxxxxxx",
  "statusCode": "InvalidParameter.TemplateTypeNotSupport",
  "errorMessage": "Unsupported template type"
}

Validation Error Codes

70510
Invalid template type (WHATSAPP / VIBER only)
70511
Invalid template category (UTILITY / MARKETING / AUTHENTICATION only)
70512
Invalid template name (lowercase letters, numbers and underscore only)
70513
Invalid components (must be a non-empty array)
70514
Component text length exceeded (BODY 1,024 / HEADER & FOOTER 60 characters)
ℹ️
The general error codes (see Error Codes) also apply. Other rejection codes are returned directly from the WhatsApp Business Platform in statusCode / errorMessage.
📌
Approval flow: after creation the template is reviewed by Meta (usually a few minutes up to 24 hours). Track the result via the Template List API — only templates with audit status pass can be used for sending.

PHP Example

PHPcreate_template.php
<?php
$url  = "https://smtpapi.vocotext.com/api_waba_create_template.php";
$data = [
    "AppId"        => "your_app_id",
    "AppSecret"    => "your_app_secret",
    "un"           => "your_username",
    "pwd"          => "your_password",
    "agreedterm"   => "YES",
    "From"         => "your_waba_number",
    "templateType" => "WHATSAPP",
    "name"         => "order_update_01",
    "language"     => "en",
    "category"     => "UTILITY",
    "components"   => [
        ["type" => "BODY", "text" => "Hi $(name), your order has shipped."]
    ],
    "example"      => ["name" => "Ali"]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

🗑 Delete Template API

Permanently delete a message template from your WhatsApp Business account.
POSThttps://smtpapi.vocotext.com/api_waba_delete_template.php
⚠️
Deletion is permanent and cannot be undone. Any system still sending with the deleted template will fail immediately. The template is also removed from the Template List API after the next sync.
ParameterTypeRequiredDescription
unStringRequiredYour iSMS account username
pwdStringRequiredYour iSMS account password
AppIdStringRequiredYour WABA App ID
AppSecretStringRequiredYour WABA App Secret
agreedtermStringRequiredSet to YES to agree with the API terms & conditions
FromStringRequiredYour WABA business number
templateCodeStringRequiredThe template code to delete (see Template List API)
languageStringRequiredThe template's locale code, e.g. en
templateTypeStringOptionalTemplate channel type. Default: WHATSAPP

JSON Request Body

JSONRequest body
{
  "AppId": "your_app_id",
  "AppSecret": "your_app_secret",
  "un": "your_username",
  "pwd": "your_password",
  "agreedterm": "YES",
  "From": "your_waba_number",
  "templateCode": "1242381527277813760",
  "language": "en",
  "templateType": "WHATSAPP"
}

Success Response

JSONSuccess response
{
  "requestId": "ccb775bf-00dd-445d-9bb0-6e83xxxxxxx",
  "statusCode": "OK",
  "templateCode": "1242381527277813760",
  "language": "en"
}

Error Response — template not found

JSONError response
{
  "requestId": "11aa2357-75a1-4ee5-8728-a55dxxxxxxx",
  "statusCode": "ERR-OPERATION-CONFIG-028",
  "errorMessage": "Template not found"
}
ℹ️
Deleting an already-deleted or unknown template returns ERR-OPERATION-CONFIG-028. The general error codes (see Error Codes) also apply.

PHP Example

PHPdelete_template.php
<?php
$url  = "https://smtpapi.vocotext.com/api_waba_delete_template.php";
$data = json_encode([
    "AppId"        => "your_app_id",
    "AppSecret"    => "your_app_secret",
    "un"           => "your_username",
    "pwd"          => "your_password",
    "agreedterm"   => "YES",
    "From"         => "your_waba_number",
    "templateCode" => "1242381527277813760",
    "language"     => "en",
    "templateType" => "WHATSAPP"
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

💰 Balance API

Check your WABA account credit balance. Each WABA account may have multiple phone numbers — the balance for each registered number is returned separately. Use your main account login — subuser logins cannot read the balance.
POSThttps://smtpapi.vocotext.com/api_waba_balance_json.php
ParameterTypeRequiredDescription
unStringRequiredYour iSMS account username
pwdStringRequiredYour iSMS account password

JSON Request Body

JSONRequest body
{
  "un": "your_username",
  "pwd": "your_password"
}

Success Response

JSONSuccess response
{
  "status": "success",
  "data": [
    {
      "waba_number": "601X-XXXXXXX",
      "waba_status": "1",
      "waba_credit_balance": "100.00",
      "waba_credit_currency": "MYR",
      "expiry_date": "2026-12-31"
    }
  ]
}
PHPcheck_balance.php
<?php
$url  = "https://smtpapi.vocotext.com/api_waba_balance_json.php";
$data = json_encode(["un" => "your_username", "pwd" => "your_password"]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
$result   = json_decode($response, true);

if ($result['status'] === 'success') {
    foreach ($result['data'] as $acct) {
        echo $acct['waba_number'] . ": MYR " . $acct['waba_credit_balance'];
    }
}
curl_close($ch);
?>

Need API Access or Integration Help?

Contact our developer support team — we'll get your AppId, AppSecret, and WABA number configured.

Contact Sales / Get API Access →

📱 SMS Coverage — Every Country We Reach Jump to a country's rate by first letter

A B C D E F G H I J K L M N O P Q R S T U V Y Z