WhatsApp Setup

Text chat only. Users message your AI agent via a temporary invite link — no setup needed on their side.

Capabilities: readwrite

How it works

From your Dashboard, you generate a temporary invite link (valid 15 minutes) that opens a WhatsApp conversation with your agent. Each link is single-use and tied to your account.

Go to your Dashboard, verify your email and create an API key

In the WhatsApp card, click Generate link

Copy the link or click it to open WhatsApp directly

Share the link with your user — they have 15 minutes to click it and send a message

The conversation appears in your agent's inbox

Invite link security

Each invite link is temporary (15-minute expiry) and single-use (consumed on first message). This prevents unwanted conversations from leaked links. You can generate a new link at any time — the previous one is automatically invalidated.

Multiple users, same WhatsApp number

If the same WhatsApp contact opens invite links from different Chamade accounts (different agents), each conversation is independent. The contact can talk to multiple agents without interference.

Messages without an invite token are routed to the most recently active conversation for that contact.

Agent integration

Your agent receives messages via chamade_inbox and replies via chamade_dm_chat. Replies are delivered as WhatsApp messages.

24-hour customer service window

WhatsApp enforces a 24-hour customer service window. After a user sends you a message, your agent can reply freely with plain text for 24 hours. Outside that window, Meta only allows pre-approved template messages.

Chamade handles this automatically — you do not need to manage templates yourself. Here's what happens if your agent tries to send a message outside the window:

Chamade detects the closed window (proactive check against the last-inbound timestamp, plus reactive fallback on Meta error 131047).

Your POST /api/dm/chat call returns HTTP 202 Accepted instead of 200, with a body like:

{
  "status": "queued",
  "message_id": "msg_...",
  "reason": "outside_24h_window",
  "template_sent": true,
  "queue_position": 1
}

The message is stored server-side with status="pending".
Chamade fires a pre-approved re-engagement template (agent_followup) so the user sees a short notification with a preview of your message and is nudged to reply.
When the user replies on WhatsApp, Chamade automatically flushes all pending messages in chronological order.
Your agent receives a dm_delivered event on the inbox WebSocket with the list of delivered_ids, immediately followed by the user's reply as a normal dm_chat event.

Multiple messages, one template

If your agent fires several messages in a row while the window is closed, Chamade sends one template nudge and queues the rest — this protects your WhatsApp quality rating. Pending messages that stay undelivered for more than 7 days are automatically dropped.

For the agent developer

Treat HTTP 202 as "message accepted, will be delivered asynchronously" — don't retry on your side. The dm_delivered WebSocket event is your explicit confirmation that pending messages went out.

Checking the window state before sending

Every WhatsApp conversation returned by GET /api/inbox includes a whatsapp_window block so your agent can anticipate whether the next chamade_dm_chat will land immediately or get queued:

{
  "platform": "whatsapp",
  "whatsapp_window": {
    "open": false,
    "last_inbound_at": "2026-04-10T04:02:15+00:00",
    "pending_count": 2
  }
}

The @chamade/mcp-server 2.2.0+ MCP client renders this inline in chamade_inbox output as wa=open / wa=closed (N pending), right next to each WhatsApp conversation line. No extra tool call needed — it's part of the normal inbox response.

Message limits & formatting

Max length	1,600 characters per message
Formatting	WhatsApp-specific — `bold`, `_italic_`, `~strikethrough~`, `monospace`, ```code blocks```

Formatting rules

WhatsApp requires spaces before and after formatting markers. For example, *bold* must be preceded and followed by a space (or be at the start/end of the message). Standard Markdown links are not supported.