Build a WhatsApp agent
with OpenClaw + TimelinesAI

What your agent can do with WhatsApp

With a TimelinesAI skill installed, your OpenClaw agent can operate WhatsApp as a real customer channel. The long version of this list is in the sections below — every capability has the specific API calls it needs.

Setup

Four things to wire together. After this, your skill just makes API calls.

Smoke-test the token

Before you build anything, confirm auth works:

curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  https://app.timelines.ai/integrations/api/whatsapp_accounts

You should see a JSON list of your connected numbers, each with an id (JID), phone, status, and account_name. If not, see Tips below.

Register the webhook once

curl -sS -X POST \
  -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"message:received:new","url":"https://your-app.example.com/webhook","enabled":true}' \
  https://app.timelines.ai/integrations/api/webhooks

Minimal webhook receiver (Node / Vercel)

~30 lines. Accepts the webhook POST, hands incoming messages off to OpenClaw. Return 2xx within 5 seconds or TimelinesAI retries.

// api/webhook.js
export default async function handler(req, res) {
  if (req.method !== "POST") return res.status(405).end();

  const { event_type, data } = req.body || {};
  if (event_type !== "message:received:new") {
    return res.status(200).json({ ignored: event_type });
  }

  // Ack fast, then hand off to the agent.
  res.status(200).json({ ok: true });

  await fetch(process.env.OPENCLAW_HOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      chat_id: data.chat_id,
      text: data.text,
      sender_phone: data.sender_phone,
    }),
  });
}

Personal numbers vs WhatsApp Business API

Before you build outbound flows, understand which WhatsApp channel your use case belongs to. Picking wrong gets numbers banned.

Safe with the skills in this guide (personal number)

• •Inbound conversations. Customer messages you first, you reply. No risk.
• •Transactional sends. Order confirmations, shipping updates, delivery notifications, payment receipts, appointment reminders — any message a customer expects because they just did something with your business.
• •Event-triggered notifications from other tools. HubSpot deal → demo confirmation, Stripe failed payment → recovery note, Calendly booking → pre-meeting reminder. The customer opted in when they used the upstream tool.
• •Replying inside WhatsApp's 24-hour customer service window. Once a customer messages you, you have 24 hours to reply freely. The autoresponder, FAQ handler, and lead qualifier skills operate inside this window.

NOT safe on personal numbers

• •Cold outreach to lists you bought or scraped — WhatsApp bans numbers for this within hours.
• •Marketing broadcasts to customers who didn't specifically opt in.
• •Promotional campaigns, sales offers, seasonal pushes, product launches.
• •Anything resembling a marketing blast. If you're asking “what throughput can I get”, you're on the wrong channel.

How to tell which channel you need

1. 1.Did the customer message you first, or are you replying inside an active 24-hour session? → Personal number, this guide.
2. 2.Is the customer about to receive something they explicitly expect (order, appointment, payment, delivery)? → Personal number, transactional send.
3. 3.Triggered by a customer-opted-in event in your CRM or billing tool? → Personal number, event-triggered send.
4. 4.Broadcast, cold outreach, or promotional campaign? → Business API, use the TimelinesAI dashboard.
5. 5.Not sure? → Don't send. Treat it as promotional and route it to the Business API path.

Every outbound capability below assumes you've passed this test. If you're not sure, re-read this section before shipping. TimelinesAI cannot protect you from the WhatsApp-layer ban — the ban is enforced upstream, at WhatsApp's infrastructure, not at the gateway.

Things to know

A few details that are easy to miss from the reference and will each cost you an hour if you don't know them.

API reference

Every endpoint you need to build every capability below. Base URL https://app.timelines.ai/integrations/api. Auth Authorization: Bearer $TIMELINES_AI_API_KEY.

Incoming messages — what your agent can handle

Every time a customer messages your WhatsApp number, TimelinesAI fires a message:received:new event to your webhook with the chat id, text, sender phone, and attachments. Your skill reads the event, decides what to do, and replies with POST /chats/{chat_id}/messages. Everything below is a variation on that loop.

Outbound — messages your agent sends

These are messages your agent starts, not replies. Triggered by a customer action your other tools detect (new order, failed payment, demo scheduled), or by a direct human instruction about a specific person. All of these assume the customer either messaged you first or explicitly expects a transactional message — if neither is true, it belongs on WhatsApp Business API, not here.

$ cat > /tmp/send.json <<'JSON'
{"phone":"+15550200",
 "text":"Hi - your order shipped. Tracking: ABC123."}
JSON

$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/send.json \
    https://app.timelines.ai/integrations/api/messages
{"status":"ok","data":{"message_uid":"OUTBOUND-UID-PLACEHOLDER"}}

$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    https://app.timelines.ai/integrations/api/messages/OUTBOUND-UID-PLACEHOLDER/status_history
{"status":"ok","data":[
  {"status":"Sent",     "timestamp":"2026-04-12 12:28:40 +0000"},
  {"status":"Delivered","timestamp":"2026-04-12 12:28:41 +0000"}
]}

CRM and analytics

TimelinesAI's read endpoints give your agent enough data to answer analytical questions and sync state with your CRM in natural language.

Scale and handoff

Patterns for human-in-the-loop workflows, multi-agent routing, and conversation memory.

State persistence

OpenClaw skills don't keep state in memory across invocations. WhatsApp conversations are multi-turn. The fix is to store state on the chat itself:

• •Labels hold discrete stage — discovery/q1, qualified, escalate. Add with POST /chats/{id}/labels, read with GET /chats/{id}/labels.
• •Notes hold structured data — team_size=8, draft replies, lead scores. Add with POST /chats/{id}/notes. Read by iterating GET /chats/{id}/messages and filtering message_type == "note".

The upside: crash safety, visibility to human teammates, clean handoff — a human can clear a label to rewind the flow, or add escalate to take over. The trade-off: every state transition is an HTTP call. For customer-facing flows this is fine.

Sending from the right number

If your workspace has more than one WhatsApp number connected, your skill has to make sure it sends from the intended one. Every chat has a whatsapp_account_id field holding the full JID (like PHONE@s.whatsapp.net) of the number that owns it. When you POST /chats/{id}/messages, the sender is always that JID — you don't pick it, the chat does.

The pattern:

1. 1Hard-code the allowed sender JID in each skill’s environment (e.g. ALLOWED_SENDER_JID).
2. 2Before sending, GET /chats/{id} and compare whatsapp_account_id to your allowed JID.
3. 3If they don’t match, skip the send — surface to a human or drop the event.

Two extra HTTP calls per turn, zero chance of sending from the wrong persona. For single-number workspaces this doesn't apply.

Example: one full round trip

A concrete five-step loop showing what the API looks like in practice — how your agent sends an outbound, confirms delivery, processes the customer's reply, and sends a follow-up. Phone numbers, chat IDs, and message UIDs below are placeholders — substitute your own.

Your business number   → +1 555 0100 (JID: 15550100@s.whatsapp.net)
Your customer's number → +1 555 0200
API token              → $TIMELINES_AI_API_KEY

$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    https://app.timelines.ai/integrations/api/whatsapp_accounts

{"status":"ok","data":{"whatsapp_accounts":[
  {"id":"15550100@s.whatsapp.net","phone":"+15550100",
   "status":"active","account_name":"Your Business"}
]}}

$ cat > /tmp/send.json <<'JSON'
{"phone":"+15550200",
 "text":"Hi - your order shipped. Tracking: ABC123."}
JSON

$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/send.json \
    https://app.timelines.ai/integrations/api/messages

{"status":"ok","data":{"message_uid":"OUTBOUND-UID-PLACEHOLDER"}}

$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    .../messages/OUTBOUND-UID-PLACEHOLDER/status_history

{"status":"ok","data":[
  {"status":"Sent",     "timestamp":"2026-04-12 12:28:40 +0000"},
  {"status":"Delivered","timestamp":"2026-04-12 12:28:41 +0000"}
]}

{
  "event_type": "message:received:new",
  "data": {
    "chat_id": 12345678,
    "message_uid": "INBOUND-UID-PLACEHOLDER",
    "sender_phone": "+15550200",
    "sender_name": "Customer",
    "text": "Thanks! When will it arrive?",
    "timestamp": "2026-04-12 12:29:20 +0000"
  }
}

$ cat > /tmp/reply.json <<'JSON'
{"text":"Estimated delivery is 2-3 business days. You'll get tracking updates to this chat."}
JSON

$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/reply.json \
    https://app.timelines.ai/integrations/api/chats/12345678/messages

{"status":"ok","data":{"message_uid":"REPLY-UID-PLACEHOLDER"}}

Limits and caveats