API Reference

Quickstart

In 5 steps you'll have an instance connected and sending messages.

1. Get API key — Contact sales to obtain your tenant credentials.
2. Create instance — POST /instance/create with the name and your webhook URL.
3. Scan QR — GET /instance/:name/qr and scan the code with your phone.
4. Wait for connection — GET /instance/:name/status until you receive state: "open".
5. Send first message — POST /message/text.

# 1. Create instance
curl -X POST https://wa.sinapsia.com.ar/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"acme__soporte__main","webhookUrl":"https://my-saas.com/webhooks/whatsapp","webhookSecret":"my-secure-secret-32"}'

# 2. Get QR (base64 image)
curl https://wa.sinapsia.com.ar/instance/acme__soporte__main/qr \
  -H "apikey: YOUR_API_KEY"

# 3. Check status (wait for state: "open")
curl https://wa.sinapsia.com.ar/instance/acme__soporte__main/status \
  -H "apikey: YOUR_API_KEY"

# 4. Send first message
curl -X POST https://wa.sinapsia.com.ar/message/text \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"acme__soporte__main","to":"5491112345678","text":"Hello! This is my first message.","lane":"normal"}'

Authentication

All requests (except GET /health) require the apikey header.

apikey: YOUR_API_KEY

Instance naming

All instances follow this format:

{tenantId}__{clientId}__{label}

Example:
acme__soporte__main

Lanes (Anti-ban)

Every message is sent through one of three lanes. The lane controls the delay and send limits to protect the WhatsApp number.

Endpoints — Instances

{
  "instanceName": "acme__soporte__main",
  "webhookUrl":    "https://my-saas.com/webhooks/whatsapp",
  "webhookSecret": "secret-minimum-16-characters"
}

{ "instanceName": "acme__soporte__main", "status": "close" }

{ "qrcode": "data:image/png;base64,iVBORw0KGgo..." }

{ "phoneNumber": "5491112345678" }

{ "pairingCode": "123456" }

{
  "instanceName":       "acme__soporte__main",
  "state":              "open",
  "phoneNumber":        "5491112345678",
  "connectedAt":        "2026-03-15T10:00:00.000Z",
  "messagesQueuedCount": 0
}

{ "device": "iPhone 12", "platform": "WHATSAPP" }

[
  { "instanceName": "acme__soporte__main", "state": "open", "phoneNumber": "5491112345678" },
  { "instanceName": "acme__ventas__main",   "state": "close", "phoneNumber": null }
]

// Array of tenant instances

// Array of client instances

{ "urgent": 0, "normal": 3, "bulk": 12, "total": 15 }

Endpoints — Messages

Shared response (all send endpoints)

{
  "id":       "3b2e1f4a-8c9d-4e2f-b7a1-0d5c6e3f9b2a",
  "status":   "pending",
  "lane":     "normal",
  "queuedAt": "2026-03-15T10:30:00.000Z"
}

{
  "instanceName": "acme__soporte__main",
  "to":          "5491112345678",
  "text":        "{Hello|Hey}! Your code is 1234.",
  "lane":        "normal"
}

{
  "instanceName": "acme__soporte__main",
  "to":          "5491112345678",
  "imageUrl":    "https://cdn.example.com/photo.jpg",
  "caption":     "Check this out",
  "lane":        "normal"
}

{
  "instanceName":  "acme__soporte__main",
  "to":           "5491112345678",
  "documentUrl":  "https://cdn.example.com/invoice.pdf",
  "fileName":     "invoice-001.pdf",
  "caption":      "Your invoice attached",
  "lane":         "normal"
}

{
  "instanceName": "acme__soporte__main",
  "to":          "5491112345678",
  "audioUrl":    "https://cdn.example.com/audio.ogg",
  "lane":        "normal"
}

{
  "instanceName": "acme__soporte__main",
  "to":          "5491112345678",
  "videoUrl":    "https://cdn.example.com/video.mp4",
  "caption":     "Watch this",
  "lane":        "normal"
}

{
  "tenantId": "acme",
  "clientId": "soporte",
  "to":       "5491112345678",
  "type":     "text",
  "text":     "Hello!",
  "lane":     "normal"
}

{
  "id":           "3b2e1f4a-8c9d-4e2f-b7a1-0d5c6e3f9b2a",
  "instanceName": "acme__soporte__main",
  "lane":         "normal",
  "to":           "5491112345678",
  "type":         "text",
  "status":       "sent",
  "createdAt":    "2026-03-15T10:30:00.000Z",
  "sentAt":       "2026-03-15T10:30:07.000Z",
  "error":        null
}

Webhooks

When creating an instance a webhookUrl is provided. The gateway sends a POST to that URL each time a relevant event occurs.

HMAC signature verification

Each request includes the x-gateway-signature header with an HMAC-SHA256 hex digest of the raw body, signed with your webhookSecret. Always verify the signature before processing.

const crypto = require('crypto')

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return expected === signature
}

import hmac, hashlib

def verify_signature(raw_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return expected == signature

Retry policy

The gateway retries 3 times: delays of 1s, 5s, 30s. Your endpoint must respond 2xx quickly.

Events

instance.connected / instance.disconnected

{
  "event":        "instance.connected",
  "instanceName": "acme__soporte__main",
  "data": {
    "state":  "open",
    "reason": null
  },
  "timestamp": "2026-03-15T10:30:00.000Z"
}

message.received

{
  "event":        "message.received",
  "instanceName": "acme__soporte__main",
  "data": {
    "from":        "5491112345678",
    "pushName":    "Juan Pérez",
    "messageType": "conversation",
    "text":        "Hello, I need help",
    "messageId":   "AC3EADB76DB5BE4130602FBF2039604A",
    "timestamp":   1773596760
  },
  "timestamp": "2026-03-15T10:30:00.000Z"
}

Monitoring

Endpoints to query statistics and manage the message queue for your instances.

{
  "instances": 2,
  "totals": { "queued": 5, "sent": 1250, "failed": 3 },
  "perInstance": [
    {
      "instanceName": "acme__soporte__main",
      "queue":    { "urgent": 0, "normal": 5, "bulk": 2, "total": 7 },
      "messages": { "sent": 450, "failed": 1, "pending": 7 }
    }
  ]
}

{ "instanceName": "acme__soporte__main", "flushed": 12 }

GET /health

Health endpoint. No authentication required. Useful for monitors and load balancers.

{
  "status":          "ok",
  "tenants":         1,
  "instances":       2,
  "queuedMessages":  5,
  "uptime":          3600
}

Errors

400 error format

{
  "error":  "Validation error",
  "issues": [
    {
      "path":    ["instanceName"],
      "message": "Must follow {tenant}__{client}__{label} format"
    }
  ]
}

Spintax

Spintax allows generating text variants to avoid repetitive messages. It is resolved randomly at send time.

Syntax: {option1|option2|option3} — supports nesting.

# Simple
{Hello|Hey|Hi}! {How are you|What's up}?
→ "Hey! What's up?"

# Nested
{Good {morning|afternoon}|Hello}!
→ "Good afternoon!"

Quick reference

Integrations

Ready-to-use configuration for the most popular platforms. All examples send a text message via POST /message/text — the same pattern applies to all other endpoints.

n8n

Add an HTTP Request node and configure it as follows:

Method:   POST
URL:      https://wa.sinapsia.com.ar/message/text
Auth:     Header Auth  →  Name: apikey  /  Value: {{ $vars.WA_API_KEY }}
Body:     JSON

{
  "instanceName": "acme__support__main",
  "to":            "{{ $json.phone }}",
  "text":          "{{ $json.message }}",
  "lane":          "normal"
}

Make (ex-Integromat)

Module HTTP → Make a request:

URL:           https://wa.sinapsia.com.ar/message/text
Method:        POST
Headers:       apikey: YOUR_API_KEY
Body type:     Raw
Content type:  application/json
Request body:

{
  "instanceName": "acme__support__main",
  "to":            "{{1.phone}}",
  "text":          "{{1.message}}",
  "lane":          "normal"
}

Zapier

Action Webhooks by Zapier → POST:

URL:          https://wa.sinapsia.com.ar/message/text
Payload Type: JSON
Data:
  instanceName  acme__support__main
  to            (phone field from trigger)
  text          (message field from trigger)
  lane          normal
Headers:
  apikey        YOUR_API_KEY

Power Automate

Add an HTTP action to your flow:

Method:  POST
URI:     https://wa.sinapsia.com.ar/message/text
Headers:
  apikey        @{variables('WA_API_KEY')}
  Content-Type  application/json
Body:
{
  "instanceName": "acme__support__main",
  "to":            "@{triggerBody()?['phone']}",
  "text":          "@{triggerBody()?['message']}",
  "lane":          "normal"
}

Pipedream

Add a Node.js code step:

import axios from "axios"

export default defineComponent({
  async run({ steps, $ }) {
    const { data } = await axios.post(
      "https://wa.sinapsia.com.ar/message/text",
      {
        instanceName: "acme__support__main",
        to:           steps.trigger.event.phone,
        text:         steps.trigger.event.message,
        lane:         "normal",
      },
      { headers: { apikey: process.env.WA_API_KEY } }
    )
    return data
  },
})

Home Assistant

Add to configuration.yaml. Store the API key in secrets.yaml.

# configuration.yaml
rest_command:
  send_whatsapp:
    url: https://wa.sinapsia.com.ar/message/text
    method: POST
    headers:
      apikey: !secret wa_api_key
      Content-Type: application/json
    payload: >
      {"instanceName":"acme__support__main",
       "to":"{{ to }}",
       "text":"{{ message }}",
       "lane":"normal"}
    content_type: application/json

Your backend

// native fetch (Node.js 18+)
const res = await fetch("https://wa.sinapsia.com.ar/message/text", {
  method: "POST",
  headers: {
    "apikey": process.env.WA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instanceName: "acme__support__main",
    to: "15551234567",
    text: "Hello from Node.js!",
    lane: "normal",
  }),
})
const data = await res.json()

import httpx, os

res = httpx.post(
    "https://wa.sinapsia.com.ar/message/text",
    headers={"apikey": os.environ["WA_API_KEY"]},
    json={
        "instanceName": "acme__support__main",
        "to":            "15551234567",
        "text":          "Hello from Python!",
        "lane":          "normal",
    },
)
data = res.json()

// Guzzle HTTP
$client = new \GuzzleHttp\Client();
$res = $client->post('https://wa.sinapsia.com.ar/message/text', [
    'headers' => ['apikey' => getenv('WA_API_KEY')],
    'json'    => [
        'instanceName' => 'acme__support__main',
        'to'           => '15551234567',
        'text'         => 'Hello from PHP!',
        'lane'         => 'normal',
    ],
]);
$data = json_decode($res->getBody(), true);

import (
    "bytes"; "encoding/json"; "net/http"; "os"
)

payload, _ := json.Marshal(map[string]string{
    "instanceName": "acme__support__main",
    "to":           "15551234567",
    "text":         "Hello from Go!",
    "lane":         "normal",
})
req, _ := http.NewRequest("POST", "https://wa.sinapsia.com.ar/message/text", bytes.NewBuffer(payload))
req.Header.Set("apikey", os.Getenv("WA_API_KEY"))
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

Responsible use

WhatsApp can ban numbers it detects as spam or that violate its terms. The gateway applies delays and rate limits automatically, but you are ultimately responsible for how the service is used.

Mandatory rules

Warning signs

• WhatsApp shows "This account is not allowed to use WhatsApp"
• Messages show a single checkmark and are never delivered
• Contacts report they can't message you

If you see any of these signs, pause sending immediately and contact soporte@sinapsia.com.ar.

Responsibilities

SinapsIA is not responsible for bans resulting from misuse of the service.