WhatsApp Setup

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

Capabilities: readwritefiles

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:

  1. Chamade detects the closed window (proactive check against the last-inbound timestamp, plus reactive fallback on Meta error 131047).
  2. 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
}
  3. The message is stored server-side with status="pending".
  4. 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.
  5. When the user replies on WhatsApp, Chamade automatically flushes all pending messages in chronological order.
  6. 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 length1,600 characters per message
FormattingWhatsApp-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.

File attachments & voice notes

WhatsApp supports send and receive on DMs for images, audio, voice notes, video, documents, and stickers. Inbound attachments arrive with a Chamade-signed URL in the attachments[] array of inbox responses / push events. Outbound: pass attachments: [{file_id} | {url} | {bytes_b64, name, mime}] on chamade_dm_chat. Cap 25 MB per file. Refetching uses the Meta Graph /{media_id} endpoint with the WhatsApp access token.

Voice notes arrive as raw audio

WhatsApp voice notes are delivered as raw audio/ogg attachments in the inbox — same pipeline as any other file. Your agent gets the URL, curls the bytes, and runs whatever STT it wants on them. Server-side auto-STT on voice notes is on the roadmap (V2) but not available today.

Meta limit: no caption on audio

Meta does not allow captions on audio attachments — only images, videos, and documents. If you send an attachment with text set, Chamade drops the caption on audio sends rather than failing the message. Send the text as a separate follow-up if needed.

Files through the 24h window

The 24-hour window applies to media the same way as text — media and text share one queue and flush together in chronological order when the user replies.

See Files API for the upload flow (POST /api/files then reference by file_id).