Quickstart: your first message in 3 steps

Create an API key, send a WhatsApp message from your own number and receive your first signed webhook — in about ten minutes.

Before you start

You need a Mursilat account whose plan includes API access, and one number linked in Numbers (scan the QR from WhatsApp → Linked devices). Every request below is real: it uses your number and your plan.

1. Create an API key

Open Settings → API keys in the dashboard and press New key (account owners only).
Name it after the system that will use it (e.g. “Shop backend”) and pick the Send messages preset — it grants messages:send and messages:read only.
Choose the numbers it may use (all, or only some), and optionally the server IPs allowed to use it.
Copy the key (wsl_live_…). It is shown once; Mursilat keeps only a keyed hash and can never show it again.

Keep the key in an environment variable on your server, never in a browser or mobile app. Check that it works — GET /v2/me needs no scope and tells you what the key can do:

GET /v2/me

curl -X GET "https://mursilat.com/api/v2/me" \
  -H "Authorization: Bearer $WASLA_API_KEY"

const res = await fetch('https://mursilat.com/api/v2/me', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}"}
res = requests.get(
    "https://mursilat.com/api/v2/me",
    headers=headers,
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/me');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

2. Send your first message

Find the id of your number (a key restricted to some numbers lists only those), then send. Idempotency-Key is required on sends: if your request times out, send it again with the same key and it will never be delivered twice.

List your numbers

curl -X GET "https://mursilat.com/api/v2/numbers" \
  -H "Authorization: Bearer $WASLA_API_KEY"

const res = await fetch('https://mursilat.com/api/v2/numbers', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}"}
res = requests.get(
    "https://mursilat.com/api/v2/numbers",
    headers=headers,
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/numbers');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

Send a text message

curl -X POST "https://mursilat.com/api/v2/messages" \
  -H "Authorization: Bearer $WASLA_API_KEY" \
  -H "Idempotency-Key: order-1042-confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "cm1abcd2345efgh6789ijkl",
  "to": "201001234567",
  "type": "text",
  "text": "طلبك اتشحن 🚚 *شكرًا*",
  "reference": "order-1042"
}'

const res = await fetch('https://mursilat.com/api/v2/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
    'Idempotency-Key': 'order-1042-confirm',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "numberId": "cm1abcd2345efgh6789ijkl",
    "to": "201001234567",
    "type": "text",
    "text": "طلبك اتشحن 🚚 *شكرًا*",
    "reference": "order-1042"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}", "Idempotency-Key": "order-1042-confirm"}
res = requests.post(
    "https://mursilat.com/api/v2/messages",
    headers=headers,
    json={
        "numberId": "cm1abcd2345efgh6789ijkl",
        "to": "201001234567",
        "type": "text",
        "text": "طلبك اتشحن 🚚 *شكرًا*",
        "reference": "order-1042"
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/messages');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
        'Idempotency-Key: order-1042-confirm',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'numberId' => 'cm1abcd2345efgh6789ijkl',
        'to' => '201001234567',
        'type' => 'text',
        'text' => 'طلبك اتشحن 🚚 *شكرًا*',
        'reference' => 'order-1042'
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

This sends a real WhatsApp message

Send to your own phone first. Every send goes through the Number Shield: under load you get status: "queued" with estimatedDelayMs, and messages to new contacts are paced.

3. Receive a webhook

Delivery receipts, customer replies and button answers arrive at your HTTPS endpoint, signed. Register one URL for all your numbers (this needs a key with webhooks:write — create a second key for it, or add the scope):

PUT /v2/webhook

curl -X PUT "https://mursilat.com/api/v2/webhook" \
  -H "Authorization: Bearer $WASLA_API_KEY" \
  -H "Idempotency-Key: order-1042-confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/mursilat",
  "events": null
}'

const res = await fetch('https://mursilat.com/api/v2/webhook', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
    'Idempotency-Key': 'order-1042-confirm',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/mursilat",
    "events": null
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}", "Idempotency-Key": "order-1042-confirm"}
res = requests.put(
    "https://mursilat.com/api/v2/webhook",
    headers=headers,
    json={
        "url": "https://example.com/mursilat",
        "events": None
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/webhook');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
        'Idempotency-Key: order-1042-confirm',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://example.com/mursilat',
        'events' => null
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

The answer contains the signing secret once. Verify every request with it — compute the HMAC over the raw body, compare in constant time and reject old timestamps:

// Node.js + Express. Use the RAW body: JSON.parse → JSON.stringify changes bytes and breaks the signature.
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.WASLA_WEBHOOK_SECRET;
const seen = new Set(); // use Redis/DB in production

function verifyWaslaSignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header || !secret) return false;
  const parts = {};
  for (const pair of header.split(',')) {
    const i = pair.indexOf('=');
    if (i > 0) parts[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
  }
  const t = parts.t;
  const v1 = parts.v1;
  if (!/^\d+$/.test(t || '') || !/^[0-9a-f]{64}$/i.test(v1 || '')) return false;
  // Reject old (replayed) or far-future timestamps.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(t + '.')
    .update(rawBody) // the RAW bytes exactly as received, not re-serialized JSON
    .digest();
  const received = Buffer.from(v1, 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

app.post('/webhooks/mursilat', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWaslaSignature(req.body, req.get('X-Wasla-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // answer fast (within 10s); do the work after

  if (seen.has(event.id)) return; // retries reuse the same event id
  seen.add(event.id);
  if (event.type === 'interactive.reply') {
    console.log(event.data.reference, '→', event.data.reply.id);
  }
});

app.listen(3000);

<?php
// Use the RAW body (php://input), never a re-encoded json_decode() result.
function wasla_verify_signature(string $rawBody, string $header, string $secret, int $toleranceSec = 300): bool
{
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        $kv = explode('=', trim($pair), 2);
        if (count($kv) === 2) {
            $parts[$kv[0]] = $kv[1];
        }
    }
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if ($secret === '' || !ctype_digit($t) || !preg_match('/^[0-9a-f]{64}$/i', $v1)) {
        return false;
    }
    // Reject old (replayed) or far-future timestamps.
    if (abs(time() - (int) $t) > $toleranceSec) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, strtolower($v1)); // constant-time
}

$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_WASLA_SIGNATURE'] ?? '';

if (!wasla_verify_signature($rawBody, $header, getenv('WASLA_WEBHOOK_SECRET') ?: '')) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($rawBody, true);
http_response_code(200); // answer fast (within 10s)

// Retries reuse the same event id — store it and skip duplicates.
if ($event['type'] === 'interactive.reply') {
    error_log($event['data']['reference'] . ' -> ' . $event['data']['reply']['id']);
}

# Python 3 + Flask. Use the RAW body (request.get_data()), not request.json re-encoded.
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WASLA_WEBHOOK_SECRET"]


def verify_wasla_signature(raw_body: bytes, header: str, secret: str, tolerance_sec: int = 300) -> bool:
    parts = {}
    for pair in (header or "").split(","):
        key, sep, value = pair.strip().partition("=")
        if sep:
            parts[key] = value
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not secret or not t.isdigit() or len(v1) != 64:
        return False
    # Reject old (replayed) or far-future timestamps.
    if abs(time.time() - int(t)) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1.lower())  # constant-time


@app.post("/webhooks/mursilat")
def mursilat_webhook():
    raw = request.get_data()  # bytes exactly as received
    if not verify_wasla_signature(raw, request.headers.get("X-Wasla-Signature", ""), SECRET):
        abort(401)
    event = json.loads(raw)
    # Retries reuse the same event id — store it and skip duplicates.
    if event["type"] == "interactive.reply":
        print(event["data"]["reference"], "->", event["data"]["reply"]["id"])
    return "", 200  # answer fast (within 10s)

# Recompute a signature by hand (debugging). body.json = the raw request body, byte for byte.
# Header: X-Wasla-Signature: t=1760097603,v1=<hex>
T=1760097603
printf '%s.' "$T" | cat - body.json | openssl dgst -sha256 -hmac "$WASLA_WEBHOOK_SECRET" -hex
# → compare the hex digest with v1 (and check that T is within 5 minutes of now)

Then trigger a test event and watch it arrive (and in the delivery log):

POST /v2/webhook/test

curl -X POST "https://mursilat.com/api/v2/webhook/test" \
  -H "Authorization: Bearer $WASLA_API_KEY" \
  -H "Idempotency-Key: order-1042-confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "cm1abcd2345efgh6789ijkl"
}'

const res = await fetch('https://mursilat.com/api/v2/webhook/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WASLA_API_KEY}`,
    'Idempotency-Key': 'order-1042-confirm',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "numberId": "cm1abcd2345efgh6789ijkl"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WASLA_API_KEY']}", "Idempotency-Key": "order-1042-confirm"}
res = requests.post(
    "https://mursilat.com/api/v2/webhook/test",
    headers=headers,
    json={
        "numberId": "cm1abcd2345efgh6789ijkl"
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://mursilat.com/api/v2/webhook/test');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WASLA_API_KEY'),
        'Idempotency-Key: order-1042-confirm',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'numberId' => 'cm1abcd2345efgh6789ijkl'
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) { throw new Exception($data['error']['code'] . ': ' . $data['error']['message']); }
print_r($data);

You can paste what your server received into the payload inspector to check the signature in your browser.

Next steps

Authentication — scopes, number restriction, IP allowlist and rotation.
Errors — the error envelope and every code with what to do.
Sending your first campaign safely.
Interactive buttons and their numbered fallback.