A WhatsApp REST API and Webhooks Built for Integrations

const API = 'https://waba-api.startmessaging.com/api/v1';
const auth = { Authorization: 'Bearer sm_live_your_api_key' };

// 1. Check your key
const me = await fetch(`${API}/me`, { headers: auth }).then((r) => r.json());
console.log(me.data.plan.code, me.data.apiKey.scopes, me.data.limits);

// 2. Send an approved template, safe to retry with the same Idempotency-Key
const res = await fetch(`${API}/messages`, {
  method: 'POST',
  headers: {
    ...auth,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-10421-ready',
  },
  body: JSON.stringify({
    "to": "+919812345678",
    "type": "template",
    "template": {
      "name": "order_ready_for_pickup",
      "language": "en_US",
      "parameters": [
        { "text": "Asha" },
        { "text": "10421" }
      ]
    },
    "clientReference": "order-10421"
  }),
});

const { data } = await res.json();
console.log(data.id, data.status, res.headers.get('Idempotent-Replayed'));

import requests

API = 'https://waba-api.startmessaging.com/api/v1'
AUTH = {'Authorization': 'Bearer sm_live_your_api_key'}

# 1. Check your key
me = requests.get(f'{API}/me', headers=AUTH).json()['data']
print(me['plan']['code'], me['apiKey']['scopes'], me['limits'])

# 2. Send an approved template, safe to retry with the same Idempotency-Key
res = requests.post(
    f'{API}/messages',
    headers={**AUTH, 'Idempotency-Key': 'order-10421-ready'},
    json={
      "to": "+919812345678",
      "type": "template",
      "template": {
        "name": "order_ready_for_pickup",
        "language": "en_US",
        "parameters": [
          { "text": "Asha" },
          { "text": "10421" }
        ]
      },
      "clientReference": "order-10421"
    },
)

data = res.json()['data']
print(data['id'], data['status'])

<?php
$api = 'https://waba-api.startmessaging.com/api/v1';
$auth = 'Authorization: Bearer sm_live_your_api_key';

// 1. Check your key
$ch = curl_init("$api/me");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [$auth],
]);
$me = json_decode(curl_exec($ch), true)['data'];
echo $me['plan']['code'] . ' ' . implode(',', $me['apiKey']['scopes']) . "\n";

// 2. Send an approved template, safe to retry with the same Idempotency-Key
$body = <<<'JSON'
{
  "to": "+919812345678",
  "type": "template",
  "template": {
    "name": "order_ready_for_pickup",
    "language": "en_US",
    "parameters": [
      { "text": "Asha" },
      { "text": "10421" }
    ]
  },
  "clientReference": "order-10421"
}
JSON;

$ch = curl_init("$api/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        $auth,
        'Content-Type: application/json',
        'Idempotency-Key: order-10421-ready',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$data = json_decode(curl_exec($ch), true)['data'];
echo $data['id'] . ' ' . $data['status'];

import hmac, hashlib, json, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ['SM_WEBHOOK_SECRET'].encode()  # the whole whsec_… string

def verify(raw_body, ts, sigs):
    if not ts or not ts.isdigit() or not sigs:
        return False
    if abs(time.time() - int(ts)) > 300:  # 5-minute tolerance
        return False
    expected = hmac.new(SECRET, f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return any(
        hmac.compare_digest(part.strip()[3:], expected)
        for part in sigs.split(',') if part.strip().startswith('v1=')
    )

@app.post('/webhooks/startmessaging')
def startmessaging_webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get('X-SM-Timestamp'), request.headers.get('X-SM-Signature')):
        return '', 401
    event = json.loads(raw)
    # Delivered at least once: skip event['id'] if you have already handled it.
    if event['type'] == 'message.delivered':
        print(event['data']['message']['clientReference'], 'delivered')
    return '', 200

<?php
$secret = getenv('SM_WEBHOOK_SECRET'); // the whole whsec_… string
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_SM_TIMESTAMP'] ?? '';
$sigs = $_SERVER['HTTP_X_SM_SIGNATURE'] ?? '';

function sm_verify(string $raw, string $ts, string $sigs, string $secret): bool
{
    if (!ctype_digit($ts) || $sigs === '') return false;
    if (abs(time() - (int) $ts) > 300) return false; // 5-minute tolerance
    $expected = hash_hmac('sha256', $ts . '.' . $raw, $secret);
    foreach (explode(',', $sigs) as $part) {
        $part = trim($part);
        if (strncmp($part, 'v1=', 3) === 0 && hash_equals($expected, substr($part, 3))) {
            return true;
        }
    }
    return false;
}

if (!sm_verify($raw, $ts, $sigs, $secret)) {
    http_response_code(401);
    exit;
}
http_response_code(200); // answer 2xx within 5 seconds

$event = json_decode($raw, true);
// Delivered at least once: skip $event['id'] if you have already handled it.
if ($event['type'] === 'message.delivered') {
    error_log($event['data']['message']['clientReference'] . ' delivered');
}

const res = await fetch('https://waba-api.startmessaging.com/api/v1/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.SM_API_KEY, // sm_live_your_api_key
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+919812345678',
    orderId: 'ORD-10442', // the same orderId again never counts the sale twice
    value: 2499.5,
    currency: 'INR',
  }),
});

const { data } = await res.json();
console.log(data.created, data.conversion.campaign?.name ?? 'no campaign credited');

import os, requests

res = requests.post(
    'https://waba-api.startmessaging.com/api/v1/conversions',
    headers={'Authorization': f"Bearer {os.environ['SM_API_KEY']}"},  # sm_live_your_api_key
    json={
        'phone': '+919812345678',
        'orderId': 'ORD-10442',
        'value': 2499.5,
        'currency': 'INR',
    },
)

data = res.json()['data']
campaign = data['conversion']['campaign']
print(data['created'], campaign['name'] if campaign else 'no campaign credited')