Developer docs

Build WhatsApp messaging workflows with Whatsly.

Pair devices, create scoped API credentials, send messages, receive signed webhooks, and connect MCP-compatible tools from one developer-friendly platform.

Start building Create workspace

Message API

curl -X POST https://api.whatsly.mysaas.tools/api/v1/messages/send \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-ID: whs_live_your_key_id" \
  -H "X-Api-Key-Secret: whs_secret_your_secret" \
  -d '{
    "device_id": 1,
    "to": "+966500000000",
    "message_type": "text",
    "text": {
      "body": "Hello from Whatsly"
    },
    "idempotency_key": "order-1001"
  }'

Quickstart Authentication Messages Templates Webhooks Integrations MCP Errors

Quickstart

Go from workspace to first message.

Whatsly uses workspace-scoped devices and device-scoped API keys. A connected device must be available before outbound messages can be sent.

Pair a device

Scan a QR code from Whatsly and confirm the device is connected.

Create API key

Generate a device API key and copy the secret once.

Send a message

Call the public message endpoint with your device id.

Add webhooks

Subscribe to message and device events with signed delivery.

Authentication

Authenticate with device API credentials.

Public API requests use two headers. The key is scoped to one Whatsly device and should only include the scopes your workflow needs.

Required headers

X-Api-Key-ID

The public key identifier.

X-Api-Key-Secret

The one-time secret copied when the key was created.

Content-Type

Use application/json for request bodies.

Scopes

messages:send

Send outbound messages through the device.

messages:read

Read conversation or message data where supported.

device:status

Inspect device connection state.

Messages

Send text, media, template, and location messages.

Use the same endpoint for supported outbound message types. Device ownership, subscription state, quotas, rate limits, and abuse controls are enforced before delivery.

text

Send a plain text message with a body.

media

Send a file by HTTPS URL with an optional caption.

template

Render a saved Whatsly template with variables.

location

Send latitude, longitude, and an optional place name.

curl -X POST https://api.whatsly.mysaas.tools/api/v1/messages/send \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-ID: whs_live_your_key_id" \
  -H "X-Api-Key-Secret: whs_secret_your_secret" \
  -d '{
    "device_id": 1,
    "to": "+966500000000",
    "message_type": "text",
    "text": {
      "body": "Hello from Whatsly"
    },
    "idempotency_key": "order-1001"
  }'

Templates

Use reusable Whatsly templates with variables.

Templates are created inside your Whatsly workspace and can be sent through the public API. Variables let you personalize operational messages without rebuilding the message body every time.

Supported variables

{name}{phone_number}{my_name}{my_email}{my_contact_number}{1}{2}{3}

Numbered API variables support practical placeholders from {1} through {20}.

{
  "device_id": 1,
  "to": "+966500000000",
  "message_type": "template",
  "template_id": 12,
  "variables": {
    "name": "Ahmed",
    "1": "Order #1001",
    "2": "SAR 250"
  },
  "idempotency_key": "order-1001"
}

Webhooks

Receive signed message and device events.

Webhooks can be workspace-wide or device-scoped. Whatsly delivers JSON payloads with an event id, event type, timestamp, tenant id, device id, and event data.

Event catalog

message.received

message.sent

message.failed

device.connected

device.disconnected

device.connection.failed

device.revoked

Signature verification

Verify X-Whatsly-Signature using HMAC SHA256 over timestamp + "." + raw JSON payload with the webhook signing secret.

{
  "event_id": "evt_01H...",
  "event_type": "message.received",
  "occurred_at": "2026-06-03T10:00:00Z",
  "tenant_id": 1,
  "device_id": 1,
  "data": {
    "message": {
      "id": 101,
      "direction": "inbound",
      "from_phone": "+966500000000",
      "to_phone": "+966511111111",
      "message_type": "text",
      "body": "Hi, is my order ready?"
    }
  }
}

Integrations

Connect commerce workflows to Whatsly.

Whatsly integrations help external systems send operational WhatsApp messages while keeping conversations and replies inside the workspace inbox.

Whatsly for WooCommerce

Send WooCommerce order confirmations, payment reminders, COD confirmations, and order status updates through a connected Whatsly device. Plugin download is available from eligible workspace plans.

Read setup docs Open integration

MCP

Connect MCP-compatible AI clients to Whatsly.

The Whatsly MCP server lets approved clients use focused Whatsly tools through your workspace credentials. MCP access is controlled by plan features and scoped API keys.

Install with npx

npx -y @whatsly/mcp-server

Use a dedicated Whatsly API key for MCP workflows. Keep credentials in your MCP client configuration or secret manager.

View MCP overview

{
  "mcpServers": {
    "whatsly": {
      "command": "npx",
      "args": ["-y", "@whatsly/mcp-server"],
      "env": {
        "WHATSLY_API_BASE_URL": "https://api.whatsly.mysaas.tools",
        "WHATSLY_API_KEY_ID": "<your-api-key-id>",
        "WHATSLY_API_KEY_SECRET": "<your-api-key-secret>",
        "WHATSLY_DEFAULT_DEVICE_ID": "<your-device-id>"
      }
    }
  }
}

Errors

Handle responses predictably.

Whatsly returns JSON responses. Store message ids, honor idempotency keys, and treat rate limit or quota errors as signals to slow down or review plan usage.

401 / 403

Check API credentials, scopes, plan access, or workspace permissions.

422

Check phone numbers, message body length, media URLs, templates, and device state.

429

Slow down requests or review per-device and workspace usage controls.