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.

How to use this guide

This guide is dual-mode. You can read it yourself and follow Setup manually — the path the sections below lay out — or you can hand the whole thing to your OpenClaw agent (or any agent that can fetch a URL) and let it do the setup for you. Both paths land at the same place: four WhatsApp skills installed, a token and webhook wired up, your agent answering customer messages.

If you’re reading this yourself

Scroll through the capability groups below — Incoming, Outbound, CRM & analytics, Operations — and decide which ones matter for your use case. Then follow Setup manually; it’s four steps and about ten minutes. Every capability lists the exact API calls it makes, and every code block in this guide has been run against the live TimelinesAI API before publication. If you get stuck, Things-to-know collects every gotcha that will cost you an hour if you don’t know about it in advance.

If you want your agent to do the setup

Paste this prompt into OpenClaw (or Claude Code, Cursor, Claude desktop, any agent that can read a URL). It points at this guide by URL so the agent reads the live version, then walks you through install, token, webhook, smoke-test, and enabling your first skill — asking for input only where it genuinely needs something from you.

Read https://timelines.ai/guide/openclaw-whatsapp-skills end to end.

Then help me set up an OpenClaw + TimelinesAI WhatsApp agent:

1. Clone InitechSoftware/openclaw-whatsapp-skills into ~/.openclaw/workspace/
   and symlink the four skills into ~/.openclaw/skills/.

2. Ask me for my TimelinesAI API token (Integrations → Public API → Copy
   on app.timelines.ai) and write it to ~/.openclaw/workspace/.env.timelinesai
   as TIMELINES_AI_API_KEY.

3. Run the smoke-test curl from Setup. If it fails, walk me through the
   "If you see something else" failure block in the guide.

4. Help me deploy examples/vercel-webhook-receiver from the companion repo
   and register the webhook with TimelinesAI.

5. Ask which of the four skills I want to enable first — whatsapp-autoresponder,
   whatsapp-lead-qualifier, whatsapp-send, or whatsapp-delivery-check — and
   walk me through its capability section plus any relevant gotchas from
   Things-to-know.

6. Before enabling anything that sends outbound messages, show me Channel
   choice so I pick the right WhatsApp channel (personal number vs Business
   API) for my use case.

The prompt intentionally stops before turning any outbound sending on — it routes you through Channel choice first so you pick the right WhatsApp channel (personal vs Business API) for what you’re actually trying to do. Ban risk is real and upstream, not something the gateway can protect you from.

Setup

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

1. 1

   Connect your WhatsApp number

   Sign in at app.timelines.ai, scan the QR code with the phone that holds your business number. TimelinesAI runs the gateway from here on. Same flow as the standard personal-number setup.

2. 2

   Get an API token

   Integrations → Public API → Copy. Save as TIMELINES_AI_API_KEY. One token covers the whole workspace.

3. 3

   Install a skill from the companion repo

   Clone InitechSoftware/openclaw-whatsapp-skills into ~/.openclaw/workspace/, then symlink each skill directory into ~/.openclaw/skills/. Four-line quick start in the companion README.

4. 4

   Register a webhook

   Point message:received:new at a public HTTPS URL. TimelinesAI will push incoming messages to it. Your receiver invokes OpenClaw.

Smoke-test the token

Before you build anything, confirm auth works:

curl -sS -w "\nHTTP: %{http_code}\n" \
  -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  https://app.timelines.ai/integrations/api/whatsapp_accounts

You should see

{
  "status": "ok",
  "data": {
    "whatsapp_accounts": [
      {
        "id": "<phone>@s.whatsapp.net",
        "phone": "+<phone>",
        "status": "connected",
        "account_name": "<your label>"
      }
    ]
  }
}

If you see something else

• HTTP 401 with the bare text Unauthorized — the token didn’t land. Re-check step 2, make sure you included the Bearer prefix, and confirm the token didn’t get line-wrapped on paste. Note the response is plain text, not JSON — piping to jq will error out.
• A bootstrap-styled HTML “Page not found” page with HTTP 404 — you’ve got a trailing slash or a typo in the path. The API serves HTML (not a JSON error) for bad paths, so if your output starts with <!DOCTYPE html>, drop any trailing slash and re-check the path.

Register the webhook once

# Generate a random secret once. Add it as a query param so only
# TimelinesAI's registered URL can reach your receiver.
WEBHOOK_SECRET=$(openssl rand -hex 16)
WEBHOOK_URL="https://your-app.example.com/api/webhook?secret=${WEBHOOK_SECRET}"

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

Minimal webhook receiver (Node / Vercel)

~40 lines. Validates the ?secret= query param, drops outbound echoes, acks 200 within the 5-second retry window, then forwards the message to your OpenClaw host.

// api/webhook.js
export default async function handler(req, res) {
  // Path-segment auth — TimelinesAI doesn't sign webhooks yet, so the
  // ?secret=<token> you registered is the only thing stopping strangers
  // from invoking this endpoint.
  if (req.query.secret !== process.env.WEBHOOK_SECRET) {
    return res.status(404).end();
  }
  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 });
  }

  // Drop your agent's own sends echoing back as "received".
  // TimelinesAI also fires message:received:new for outbound messages
  // synced from another WhatsApp client on the same number.
  if (data.from_me === true) {
    return res.status(200).json({ ignored: "from_me" });
  }

  // Ack FAST. TimelinesAI retries 3x with a 5-second timeout per attempt —
  // if you take longer than 5s the same event hits you up to 3 times.
  res.status(200).json({ ok: true });

  // TL webhook payloads sometimes arrive flat (data.chat_id) and sometimes
  // nested (data.chat.id) depending on event flavor and version. Destructure
  // with fallback so both shapes work — see Things to know below.
  const chatId = data.chat_id ?? data.chat?.id;
  const whatsappAccountId =
    data.whatsapp_account_id ?? data.chat?.whatsapp_account_id;

  // Fire-and-forget handoff to wherever your OpenClaw host accepts
  // inbound messages. For production durability replace this with a
  // push to a queue (QStash, Inngest, SQS) your agent drains separately.
  try {
    await fetch(process.env.OPENCLAW_HOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        chat_id: chatId,
        whatsapp_account_id: whatsappAccountId,
        text: data.text,
        sender_phone: data.sender_phone,
        message_uid: data.message_uid,
      }),
    });
  } catch (err) {
    console.error("[timelinesai-webhook] handoff failed:", err);
  }
}

OPENCLAW_HOOK_URL is whatever endpoint your OpenClaw deployment exposes for inbound messages — it depends on how you host the agent. For a production-grade reference with durability notes, see examples/vercel-webhook-receiver in the companion repo.

What's inside your OpenClaw workspace

You connected a TimelinesAI token and symlinked skills from the companion repo. Here’s what you actually installed, and which files you edit when you want to change how your agent thinks, what it knows, and how it behaves. Nothing here is magic — it’s all plain markdown and env files in two directories.

Skills — ~/.openclaw/skills/<skill>/

Every skill you symlinked is a directory with one required file (SKILL.md) and any resources that file references. If you want to change how your FAQ handler sounds, or re-order the lead qualifier’s questions, the edit lives in that skill’s SKILL.md. No code to recompile, no build step.

For the four WhatsApp skills specifically — whatsapp-autoresponder, whatsapp-lead-qualifier, whatsapp-send, whatsapp-delivery-check — the top of each SKILL.md has the role and allowed tools; the body has the actual prompt your agent runs with. Read one of them end-to-end before you edit; the patterns repeat.

Workspace — ~/.openclaw/workspace/

The workspace directory is OpenClaw’s home for everything that isn’t a skill: who your agent is, what it knows about you, what tools it has, how it boots. OpenClaw’s own docs say “this folder is home. Treat it that way.” These files ship with the install — you fill them out over time:

Per-integration env files

Alongside the canonical files above, you add one env file per integration you wire up. These aren’t part of the OpenClaw install — they’re yours, and they hold secrets that should never be committed to a public repo:

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.

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.

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.

When API calls fail

Five failure modes will eventually hit your skill. Each one looks different in the response, and each one has a different correct response.

A small shell pattern that branches on each status code:

$ # Capture the HTTP status into a variable, then branch
$ http_code=$(curl -sS -o /tmp/resp.json -w "%{http_code}" \
    -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)

$ case "$http_code" in
    200|201) ;;                                # ok, carry on
    400)     echo "bad body: $(cat /tmp/resp.json)"; exit 1 ;;
    401)     echo "token expired - rotate"; exit 2 ;;
    429)     sleep 30; retry_once ;;           # respect Retry-After
    5*)      sleep $((2 ** attempt)); retry_with_backoff ;;
  esac

Operating safely in production

Two more things that aren't failures, but will save you a bad day later.

Conversation context

The webhook hands your skill a single message — the one that just arrived. No prior turns, no chat history, no running transcript. For a stateless FAQ or an after-hours responder that's plenty. For a conversational agent that has to remember what the customer said three turns ago, your skill has to fetch the context itself. Three patterns cover the full range, from the cheapest possible loop to the one that actually remembers.

Fetching the window is a single GET. Response is a flat array of messages on the chat, newest last, mixing inbound customer turns with your own outbound replies and any notes your skill has written:

$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    "https://app.timelines.ai/integrations/api/chats/12345678/messages?limit=20"
{"status":"ok","data":[
  {"message_uid":"INBOUND-UID-PLACEHOLDER",
   "text":"hi, is the blue one still available?",
   "sender_phone":"+15550200",
   "message_type":"text","origin":"WhatsApp",
   "created_at":"2026-04-14T10:22:03Z"},
  {"message_uid":"OUTBOUND-UID-PLACEHOLDER",
   "text":"Yes, one left. Want me to hold it for you?",
   "sender_phone":"",
   "message_type":"text","origin":"Public API",
   "created_at":"2026-04-14T10:22:41Z"},
  {"message_uid":"INBOUND-UID-PLACEHOLDER-2",
   "text":"yes please, until tomorrow",
   "sender_phone":"+15550200",
   "message_type":"text","origin":"WhatsApp",
   "created_at":"2026-04-14T10:23:08Z"}
]}

Gotchas that bite in production

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.

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.

$ # 1. Read current stage from the chat's labels. Labels nest under
$ # data.labels as a string array — see Response shapes in Things to know.
$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    https://app.timelines.ai/integrations/api/chats/12345678/labels
{"status":"ok","data":{"labels":["discovery/q1"]}}

$ # 2. Save the customer's answer as a structured note. Notes are stored
$ # as messages with message_type=note and aren't pushed to WhatsApp.
$ cat > /tmp/note.json <<'JSON'
{"text":"team_size=12"}
JSON
$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/note.json \
    https://app.timelines.ai/integrations/api/chats/12345678/notes
{"status":"ok","data":{"message_uid":"NOTE-UID-PLACEHOLDER"}}

$ # 3. Advance the stage label. POST /labels REPLACES the full set, so
$ # read existing labels, swap q1 for q2, POST the combined list. The
$ # body key is "labels" (plural, array) — not "label" singular.
$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    https://app.timelines.ai/integrations/api/chats/12345678/labels \
  | jq -c '.data.labels | map(if . == "discovery/q1" then "discovery/q2" else . end) | {labels: .}' \
  > /tmp/labels.json
$ cat /tmp/labels.json
{"labels":["discovery/q2"]}
$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/labels.json \
    https://app.timelines.ai/integrations/api/chats/12345678/labels
{"status":"ok","data":{"labels":["discovery/q2"]}}

$ # The attachment URL in the webhook payload expires in ~15 minutes.
$ # Download it inline in the receiver, before queuing async work.
$ ATTACH_URL="https://files.timelines.ai/abc123/receipt.jpg?expires=..."
$ curl -sS "$ATTACH_URL" -o /tmp/receipt.jpg

$ # Process /tmp/receipt.jpg with OpenClaw vision tools, then write
$ # the extracted fields back as a structured note on the chat:
$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary '{"text":"receipt: amount=$42.50 vendor=Cafe Madrid"}' \
    https://app.timelines.ai/integrations/api/chats/12345678/notes

$ # Send the raw emoji character in the body. Save to a UTF-8 file and
$ # use --data-binary so shells can't downgrade it.
$ printf '{"reaction":"👀"}' > /tmp/react.json

$ curl -sS -X PATCH \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/react.json \
    https://app.timelines.ai/integrations/api/messages/INBOUND-UID-PLACEHOLDER/reactions
{"status":"ok"}

Outbound — messages your agent starts

Messages your agent initiates, not replies. Triggered by an event in your other tools (a new order, a failed payment, a meeting booked) or a direct human instruction about a specific person.

Before every capability in this section: the customer either opened the thread recently (within WhatsApp's 24-hour session window) or explicitly expects this message. If neither is true, don't send it from a personal number — that's Business API territory.

$ 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"}}

$ # Step 1 - upload the file bytes as multipart/form-data.
$ # The form field name is "file". The response gives you a uid.
$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -F "file=@/path/to/quote.pdf" \
    https://app.timelines.ai/integrations/api/files_upload
{"status":"ok","data":{
  "uid":"FILE-UID-PLACEHOLDER",
  "filename":"quote.pdf",
  "size":128453,
  "mimetype":"application/pdf",
  "uploaded_by_email":"you@yourcompany.com",
  "uploaded_at":"2026-04-14 10:22:03 +0000",
  "temporary_download_url":"https://tl-prod-data.s3.amazonaws.com/..."
}}

$ # Step 2 - attach the uploaded file to a chat message using file_uid.
$ cat > /tmp/send.json <<'JSON'
{"text":"Quote attached for your review.",
 "file_uid":"FILE-UID-PLACEHOLDER"}
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/chats/12345678/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

Read endpoints give your agent enough data to answer analytical questions and sync state with your CRM in natural language.

$ # Pull the last page of a chat's messages (50 per page, fixed).
$ # Messages nest under data.messages — not a flat .data[] array.
$ # FILTER message_type=="whatsapp" to exclude notes (see Things to know
$ # below — notes live in the same timeline with from_me=false and would
$ # otherwise corrupt the response-time calculation).
$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    "https://app.timelines.ai/integrations/api/chats/12345678/messages?page=1" \
  | jq -r '.data.messages[] | select(.message_type=="whatsapp") | "\(.timestamp)\tfrom_me=\(.from_me)\t\(.text[0:40])"'

# 2026-04-12 12:28:40 +0300  from_me=false  Hi - is the order shipped?
# 2026-04-12 12:30:15 +0300  from_me=true   Yes - tracking ABC123, ETA 2-3
# 2026-04-12 14:02:11 +0300  from_me=false  Got it, thanks!
# ...

$ # Compute first-reply latency from each consecutive (false -> true)
$ # pair, then average across all chats. Pure client-side aggregation.
$ # For full history walk ?page=2, ?page=3, ... until data.has_more_pages is false.

$ # 1. Pull recent chats with their phone numbers. /chats returns 50 per
$ # page under data.chats — paginate with ?page=N if you need more.
$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    "https://app.timelines.ai/integrations/api/chats?page=1" \
  | jq -r '.data.chats[] | "\(.id)\t\(.phone)"'

# 12345678   +15550100
# 12345679   +15550200
# ...

$ # 2. For each phone, look up your CRM (HubSpot/Pipedrive/Close).
$ #    Pseudo-code:
$ #      contact = hubspot.search_by_phone(phone)
$ #      stage   = contact.deal_stage if contact else "unknown"

$ # 3. Add the deal stage label WITHOUT wiping existing labels.
$ # POST /labels is REPLACE semantics (full set), so GET current labels,
$ # append the new one, and POST the combined list.
$ curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    https://app.timelines.ai/integrations/api/chats/12345678/labels \
  | jq -c '.data.labels + ["hubspot/qualified-lead"] | unique | {labels: .}' \
  > /tmp/labels.json
$ curl -sS -X POST \
    -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @/tmp/labels.json \
    https://app.timelines.ai/integrations/api/chats/12345678/labels

Scale and handoff

Patterns for human-in-the-loop workflows, multi-agent routing, and conversation memory. All four capabilities below are designed to coexist with humans working the same chats from the TimelinesAI shared inbox.

$ # 1. Count outbound 'whatsapp' messages (skip notes) in this chat.
$ # Messages nest under data.messages — not a flat .data[] array.
$ TURNS=$(curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
    "https://app.timelines.ai/integrations/api/chats/12345678/messages?page=1" \
  | jq '[.data.messages[] | select(.from_me==true and .message_type=="whatsapp")] | length')
$ echo $TURNS
8

$ # 2. Past the threshold? Append 'escalate' to the chat's labels and stop.
$ # POST /labels REPLACES the full set, so read existing first, combine,
$ # then POST — otherwise you wipe every other label on the chat.
$ if [ "$TURNS" -ge 5 ]; then
    curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
      https://app.timelines.ai/integrations/api/chats/12345678/labels \
    | jq -c '.data.labels + ["escalate"] | unique | {labels: .}' \
    > /tmp/labels.json
    curl -sS -X POST \
      -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @/tmp/labels.json \
      https://app.timelines.ai/integrations/api/chats/12345678/labels
  fi

$ # 3. Before every future send, GET /chats/{id}/labels and bail
$ #    if .data.labels contains 'escalate' or 'needs-human'.

Test your agent end-to-end with a second WhatsApp number

After setup you can see capabilities listed here, but you can’t see your agent actually work until a real customer messages it. That’s a bad loop for iteration. Here’s a better one: connect a second WhatsApp number to the same TimelinesAI workspace, use it as a scripted customer, and watch your real agent skill handle the conversation end-to-end. No mocks, no fake webhooks — it’s your real agent, your real API, just with a second number playing the role of the human on the other side.

The pattern

TimelinesAI lets multiple WhatsApp numbers live in one workspace and routes their inbound webhooks through the same receiver. The trick is the `whatsapp_account_id` field on every webhook payload — it carries the JID of the number that received the message. Read it, switch on it, dispatch to either a persona step (when your agent just replied to the customer) or an agent step (when the customer just messaged your agent). Each side sends via the normal POST /messages or POST /chats/{id}/messages from the other side’s perspective.

Architecture

  [+1 555 0100]                   [+1 555 0200]
     persona                    agent under test
        |                              |
        |    one TimelinesAI workspace |
        |                              |
        +------->  Public API  <-------+
                        |
                 message:received:new
                        |
                        v
           +--------------------------+
           |  Your test receiver      |
           |  switch (accountJid) {   |
           |    persona_jid -> next   |
           |    agent_jid   -> skill  |
           |  }                       |
           +--------------------------+

Persona sender

The persona side is a scripted customer: a list of lines to say next. When it’s time for the next turn, POST to /messages with the agent’s phone number as the recipient. TimelinesAI handles the routing because both numbers are in one workspace.

// persona-sender.js — send the next scripted customer turn from the
// persona WhatsApp number to the agent-under-test number. TimelinesAI
// routes the send because both numbers share one workspace.

const PERSONA_SCRIPT = [
  "hi I saw your ad",
  "we want to reduce customer churn",
  "we are 25 people",
  "we need to roll out in Q3",
];
let idx = 0;

export async function sendNextPersonaTurn() {
  if (idx >= PERSONA_SCRIPT.length) return;
  const text = PERSONA_SCRIPT[idx++];

  await fetch("https://app.timelines.ai/integrations/api/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TIMELINES_AI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: Buffer.from(JSON.stringify({
      phone: process.env.AGENT_UNDER_TEST_PHONE,
      text,
    }), "utf-8"),
  });
  console.log(`[persona] sent: ${text}`);
}

Receiver jid-switch

One receiver, one branch per side. Everything else you already know from Setup — the `?secret=` auth, the `from_me` echo filter, the flat-vs-nested payload fallback — applies here unchanged.

// api/webhook.js — route events by which number received them
export default async function handler(req, res) {
  if (req.query.secret !== process.env.WEBHOOK_SECRET) return res.status(404).end();
  const { event_type, data } = req.body || {};
  if (event_type !== "message:received:new") return res.status(200).end();
  if (data?.from_me === true) return res.status(200).end();
  res.status(200).json({ ok: true });

  const accountJid = data.whatsapp_account_id ?? data.chat?.whatsapp_account_id;
  if (accountJid === process.env.AGENT_UNDER_TEST_JID) {
    // Customer just messaged the agent — run your agent-under-test skill
    await handleAgentTurn(data);
  } else if (accountJid === process.env.PERSONA_JID) {
    // Agent just replied to the persona — advance the scripted scenario
    await advancePersona(data);
  }
}

Those two snippets are the core idea. The full harness — persona scripts, scenario loader, CLI kickoff, split-pane color logger, Vercel config — lives in examples/test-harness/ in the companion repo, with its own README that walks through deploy, env vars, webhook registration, and running your first scenario end-to-end.

Watching it happen

The harness runs autonomously — it doesn’t need you to approve each reply. Your oversight happens in the TimelinesAI dashboard: open the chat between your persona and agent numbers in another browser tab and every turn shows up live. If the agent says something dumb, send a manual reply from the agent’s inbox to steer the conversation. If you need to change behavior mid-run, add a label or write a note on the chat — both are visible to the agent’s skill on its next turn. Stop the run by deleting the registered webhook or shutting down the Vercel function; the scenario halts immediately.

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

What this guide does NOT cover, and why.

Related guides

If you're building this for a real customer channel, these three pages cover adjacent territory you'll touch sooner or later.