← Spansend · API api.spansend.com · OpenAPI

Activation quickstart

For client bots / agents. Base: https://api.spansend.com. Billing off until you enable. Activation = test message visible in WhatsApp.

Happy path

Create tenant — POST /v1/tenants with name + plan. Optional email on create — needed later for recover-key if you lose the API key (no PATCH email yet).
Success: tenant_id + api_key. Save the key now — shown once.
QR — GET /v1/tenants/{id}/session/qr with X-API-Key. Scan Linked Devices.
Success: qr.base64. QR expires in ~20s — refetch if stale; don’t reuse screenshots.
Status — GET /v1/tenants/{id}/status. Poll until ready.
Success: top-level status: "connected" and connection.state: "open". Public id field is session_id. Gate on status (live-mapped).
Chats → test-send — GET …/chats?q= then POST /v1/test-send with exact chat_id + matching recipient_label + confirm:true.
Success: send accepted; message appears in WhatsApp.

Copy-paste

BASE=https://api.spansend.com

curl -sS -X POST "$BASE/v1/tenants" \
  -H 'Content-Type: application/json' \
  -d '{"name":"agent-1","plan":"pro","email":"[email protected]"}'
# → save api_key once

curl -sS "$BASE/v1/tenants/$TENANT_ID/session/qr" -H "X-API-Key: $API_KEY"
# scan qr.base64 within ~20s; refetch if expired

curl -sS "$BASE/v1/tenants/$TENANT_ID/status" -H "X-API-Key: $API_KEY"
# ready when status=connected and connection.state=open

curl -sS "$BASE/v1/tenants/$TENANT_ID/chats?q=NAME&limit=50" -H "X-API-Key: $API_KEY"

curl -sS -X POST "$BASE/v1/test-send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"chat_id":"CHAT_ID","recipient_label":"Exact Label From Chats","text":"Spansend activation test","confirm":true}'

Status mapping

If you see awaiting_qr while connection.state is already open, re-fetch status — healthy mapping is open → connected. Don’t start chats until status is connected.

`connection.state`	top-level `status`
`open`	`connected`
`connecting`	`connecting`
`close` / `closed`	`awaiting_qr`

Lost API key

Still have the key? POST /v1/tenants/{id}/rotate-key.

Key gone? POST /v1/tenants/recover-key → check email from [email protected] for the token (~20 min TTL) → POST …/recover-key/confirm.

Connect your agent (MCP)

After Activation, paste this into your agent. Endpoint https://api.spansend.com/mcp/ (prefer trailing slash) · auth X-API-Key · tools get_status, get_session_qr, list_chats, confirm_send.

Cursor

{
  "mcpServers": {
    "spansend": {
      "url": "https://api.spansend.com/mcp/",
      "headers": {
        "X-API-Key": "wb_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Uses mcp-remote (stdio bridge). Put the key in env.

{
  "mcpServers": {
    "spansend": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.spansend.com/mcp/",
        "--header",
        "X-API-Key:${SPANSEND_API_KEY}"
      ],
      "env": {
        "SPANSEND_API_KEY": "wb_live_YOUR_KEY"
      }
    }
  }
}

Codex

In ~/.codex/config.toml (prefer env_http_headers for the key).

[mcp_servers.spansend]
url = "https://api.spansend.com/mcp/"
http_headers = { "X-API-Key" = "wb_live_YOUR_KEY" }

Generic

{
  "url": "https://api.spansend.com/mcp/",
  "transport": "streamable-http",
  "headers": {
    "X-API-Key": "wb_live_YOUR_KEY"
  }
}

Full markdown: repo docs/activation.md. Product-only. Billing off until you enable.