Construye un agente de WhatsApp
con OpenClaw + TimelinesAI

Qué puede hacer tu agente con WhatsApp

Con un skill de TimelinesAI instalado, tu agente OpenClaw puede operar WhatsApp como un canal de cliente real. La versión larga de esta lista está en las secciones de abajo — cada capacidad tiene las llamadas API específicas que necesita.

Cómo usar esta guía

Esta guía es dual-mode. Puedes leerla tú mismo y seguir el Setup a mano — el camino que las secciones de abajo despliegan — o puedes entregarla entera a tu agente OpenClaw (o cualquier agente que pueda leer una URL) y dejar que haga el setup por ti. Ambos caminos llegan al mismo lugar: cuatro skills de WhatsApp instalados, un token y un webhook conectados, tu agente respondiendo mensajes de clientes.

Si estás leyendo esto tú mismo

Pasa por los grupos de capacidades de abajo — Incoming, Outbound, CRM & analytics, Operations — y decide cuáles importan para tu caso de uso. Luego sigue Setup manualmente; son cuatro pasos y unos diez minutos. Cada capability lista las llamadas de API exactas que hace, y cada code block en esta guía fue ejecutado contra la API real de TimelinesAI antes de publicar. Si te atascas, Things-to-know reúne todos los gotchas que te costarían una hora si no los conoces con antelación.

Si quieres que tu agente haga el setup

Pega este prompt en OpenClaw (o Claude Code, Cursor, Claude desktop, cualquier agente que pueda leer una URL). Apunta a esta guía por URL para que el agente lea la versión live, y luego te acompaña por install, token, webhook, smoke-test y habilitar tu primer skill — pidiéndote input sólo cuando de verdad necesita algo de ti.

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.

El prompt se detiene deliberadamente antes de encender cualquier envío outbound — te rutea primero por Channel choice para que elijas el canal de WhatsApp correcto (número personal vs Business API) para lo que realmente estás intentando hacer. El riesgo de ban es real y vive upstream, no es algo de lo que el gateway te pueda proteger.

Setup

Cuatro cosas que conectar. Después, tu skill solo hace llamadas API.

1. 1

   Conecta tu número de WhatsApp

   Inicia sesión en app.timelines.ai, escanea el código QR con el teléfono que tiene tu número de negocio. TimelinesAI gestiona el gateway desde aquí. Mismo flujo que el setup estándar de número personal.

2. 2

   Obtén un token de API

   Integraciones → API Pública → Copiar. Guárdalo como TIMELINES_AI_API_KEY. Un solo token cubre todo el workspace.

3. 3

   Instala un skill del repo compañero

   Clona InitechSoftware/openclaw-whatsapp-skills en ~/.openclaw/workspace/, luego haz symlink de cada directorio de skill en ~/.openclaw/skills/. Guía rápida de cuatro líneas en el README del repo compañero.

4. 4

   Registra un webhook

   Apunta message:received:new a una URL HTTPS pública. TimelinesAI le hará push de los mensajes entrantes. Tu receptor invoca a OpenClaw.

Prueba rápida del token

Antes de construir nada, confirma que la auth funciona:

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

Deberías ver

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

Si ves otra cosa

• HTTP 401 con el texto plano Unauthorized — el token no se aplicó. Revisa el paso 2, asegúrate de incluir el prefijo Bearer y de que el token no se haya partido en líneas al pegarlo. La respuesta es texto plano, no JSON — pasarla a jq dará error.
• Una página HTML con estilo bootstrap “Page not found” con HTTP 404 — tienes una barra final o un error tipográfico en la ruta. La API devuelve HTML (no un error JSON) para rutas mal escritas, así que si tu salida empieza con <!DOCTYPE html>, quita cualquier barra final y revisa la ruta.

Registra el webhook una vez

# 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

Receptor de webhook mínimo (Node / Vercel)

~40 líneas. Valida el query param ?secret=, descarta los echos de salida, responde 2xx en la ventana de reintento de 5 segundos y luego pasa el mensaje a tu host OpenClaw.

// 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 es el endpoint que tu despliegue de OpenClaw expone para los mensajes entrantes — depende de cómo alojes el agente. Para una referencia con notas de durabilidad lista para producción, mira examples/vercel-webhook-receiver en el repo compañero.

Qué hay dentro de tu workspace de OpenClaw

Conectaste un token de TimelinesAI y symlink'easte skills del repo compañero. Aquí está qué instalaste realmente, y cuáles archivos editas cuando quieres cambiar cómo piensa tu agente, qué sabe y cómo se comporta. Nada aquí es magia — es todo markdown simple y archivos env en dos directorios.

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

Cada skill que symlink'easte es un directorio con un archivo obligatorio (SKILL.md) más los recursos que ese archivo referencia. Si quieres cambiar cómo suena tu FAQ handler o re-ordenar las preguntas del lead qualifier, la edición vive en el SKILL.md de ese skill. Sin código que recompilar, sin build step.

Para los cuatro skills de WhatsApp — whatsapp-autoresponder, whatsapp-lead-qualifier, whatsapp-send, whatsapp-delivery-check — la parte superior de cada SKILL.md tiene el role y las tools permitidas; el body tiene el prompt real con el que corre tu agente. Lee uno de ellos end-to-end antes de editar; los patrones se repiten.

Workspace — ~/.openclaw/workspace/

El directorio workspace es la casa de OpenClaw para todo lo que no es un skill: quién es tu agente, qué sabe de ti, qué tools tiene, cómo arranca. Los propios docs de OpenClaw dicen “esta carpeta es hogar. Trátala así”. Estos archivos vienen con el install — los llenas con el tiempo:

Archivos env por integración

Junto a los archivos canónicos de arriba, añades un archivo env por cada integración que conectes. Estos NO son parte del install de OpenClaw — son tuyos, y guardan secretos que nunca deberían commitearse en un repo público:

Números personales vs WhatsApp Business API

Antes de construir flujos salientes, entiende a qué canal de WhatsApp pertenece tu caso de uso. Elegir mal banea números.

Seguro con los skills de esta guía (número personal)

• •Conversaciones entrantes. El cliente te escribe primero, tú respondes. Sin riesgo.
• •Envíos transaccionales. Confirmaciones de pedido, actualizaciones de envío, notificaciones de entrega, recibos de pago, recordatorios de cita — cualquier mensaje que un cliente espera porque acaba de hacer algo con tu negocio.
• •Notificaciones disparadas por eventos en otras herramientas. Deal de HubSpot → confirmación de demo, fallo de pago de Stripe → nota de recuperación, reserva de Calendly → recordatorio previo a la reunión. El cliente optó cuando usó la herramienta upstream.
• •Responder dentro de la ventana de servicio al cliente de 24 horas de WhatsApp. Una vez que el cliente te escribe, tienes 24 horas para responder libremente. Los skills de auto-respuesta, FAQ y calificador de leads operan dentro de esta ventana.

NO seguro en números personales

• •Cold outreach a listas que compraste o scrapeaste — WhatsApp banea números por esto en horas.
• •Broadcasts de marketing a clientes que no optó explícitamente.
• •Campañas promocionales, ofertas de ventas, empujones de temporada, lanzamientos de producto.
• •Cualquier cosa que se parezca a un blast de marketing. Si te estás preguntando “cuánto throughput puedo sacar”, estás en el canal equivocado.

Cómo saber qué canal necesitas

1. 1.¿El cliente te escribió primero, o estás respondiendo dentro de una sesión activa de 24 horas? → Número personal, esta guía.
2. 2.¿El cliente está a punto de recibir algo que explícitamente espera (pedido, cita, pago, entrega)? → Número personal, envío transaccional.
3. 3.¿Disparado por un evento opt-in del cliente en tu CRM o herramienta de facturación? → Número personal, envío disparado por evento.
4. 4.¿Broadcast, cold outreach o campaña promocional? → Business API, usa el dashboard de TimelinesAI.
5. 5.¿No estás seguro? → No envíes. Trátalo como promocional y rutéalo al camino Business API.

Cada capacidad saliente más abajo asume que pasaste este test. Si no estás seguro, vuelve a leer esta sección antes de shipear. TimelinesAI no puede protegerte del baneo a nivel de WhatsApp — el baneo se aplica upstream, en la infraestructura de WhatsApp, no en el gateway.

Referencia de la API

Cada endpoint que necesitas para construir cada capacidad de abajo. URL base https://app.timelines.ai/integrations/api. Auth Authorization: Bearer $TIMELINES_AI_API_KEY.

Cosas que saber

Algunos detalles fáciles de pasar por alto en la referencia y que cada uno te costará una hora si no los conoces.

Cuando las llamadas API fallan

Cinco modos de fallo te van a tocar tarde o temprano. Cada uno se ve distinto en la respuesta y cada uno tiene una respuesta correcta distinta.

Un pequeño patrón de shell que ramifica por cada código de estado:

$ # 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

Operar con seguridad en producción

Dos cosas más que no son fallos, pero te ahorrarán un mal día más adelante.

Contexto de conversación

El webhook le entrega a tu skill un solo mensaje — el que acaba de llegar. Sin turnos previos, sin historial de chat, sin transcripción activa. Para un FAQ sin estado o un respondedor fuera de horario eso sobra. Para un agente conversacional que tiene que recordar lo que el cliente dijo tres turnos antes, tu skill tiene que traer el contexto por su cuenta. Tres patrones cubren todo el rango, del bucle más barato al que de verdad recuerda.

Traer la ventana es un único GET. La respuesta es un array plano de mensajes del chat, el más nuevo al final, mezclando turnos entrantes del cliente con tus propias respuestas salientes y cualquier nota que haya escrito tu skill:

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

Trampas que muerden en producción

Persistencia de estado

Los skills de OpenClaw no mantienen estado en memoria entre invocaciones. Las conversaciones de WhatsApp son multi-turno. La solución es guardar el estado en el propio chat:

• •Las etiquetas guardan la etapa discreta — discovery/q1, qualified, escalate. Añade con POST /chats/{id}/labels, lee con GET /chats/{id}/labels.
• •Las notas guardan datos estructurados — team_size=8, borradores de respuesta, scores de leads. Añade con POST /chats/{id}/notes. Lee iterando GET /chats/{id}/messages y filtrando message_type == "note".

La ventaja: seguridad ante crashes, visibilidad para los humanos del equipo, handoff limpio — un humano puede limpiar una etiqueta para rebobinar el flujo, o añadir escalate para tomar el control. El trade-off: cada transición de estado es una llamada HTTP. Para flujos cara al cliente eso está bien.

Enviar desde el número correcto

Si tu workspace tiene más de un número de WhatsApp conectado, tu skill tiene que asegurarse de enviar desde el número esperado. Cada chat tiene un campo whatsapp_account_id con el JID completo (como TELEFONO@s.whatsapp.net) del número dueño. Cuando haces POST /chats/{id}/messages, el remitente es siempre ese JID — tú no lo eliges, lo elige el chat.

El patrón:

1. 1Hardcodea el JID de remitente permitido en el entorno de cada skill (p. ej. ALLOWED_SENDER_JID).
2. 2Antes de enviar, GET /chats/{id} y compara whatsapp_account_id con tu JID permitido.
3. 3Si no coinciden, salta el envío — escala a un humano o descarta el evento.

Dos llamadas HTTP extra por turno, cero posibilidad de enviar desde el persona equivocado. Para workspaces de un solo número esto no aplica.

Mensajes entrantes — lo que tu agente puede manejar

Cada vez que un cliente le escribe a tu número de WhatsApp, TimelinesAI dispara un evento message:received:new a tu webhook con el chat id, el texto, el teléfono del remitente y los adjuntos. Tu skill lee el evento, decide qué hacer y responde con POST /chats/{chat_id}/messages. Todo lo de abajo es una variación de ese 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"}

Salientes — mensajes que tu agente inicia

Mensajes que tu agente inicia, no respuestas. Disparados por un evento en tus otras herramientas (un nuevo pedido, un pago fallido, una reunión agendada) o por una instrucción humana directa sobre una persona concreta.

Antes de cada capacidad de esta sección: el cliente o abrió el hilo recientemente (dentro de la ventana de sesión de 24 horas de WhatsApp) o explícitamente espera este mensaje. Si ninguna de las dos cosas es cierta, no lo envíes desde un número personal — ese es territorio Business API.

$ 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 y analítica

Los endpoints de lectura le dan a tu agente datos suficientes para responder preguntas analíticas y sincronizar estado con tu CRM en lenguaje natural.

$ # 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

Escalado y handoff

Patrones para flujos human-in-the-loop, enrutado multi-agente y memoria de conversación. Las cuatro capacidades de abajo están diseñadas para coexistir con humanos trabajando los mismos chats desde la bandeja compartida de TimelinesAI.

$ # 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'.

Prueba tu agente end-to-end con un segundo número de WhatsApp

Después del setup puedes ver las capacidades listadas aquí, pero no puedes ver tu agente en acción hasta que un cliente real le escribe. Ese es un mal loop para iterar. Aquí tienes uno mejor: conecta un segundo número de WhatsApp al mismo workspace de TimelinesAI, úsalo como un cliente scripted y observa a tu skill real manejar la conversación end-to-end. Sin mocks, sin webhooks falsos — es tu agente real, tu API real, solo con un segundo número jugando el papel del humano al otro lado.

El patrón

TimelinesAI permite que varios números de WhatsApp vivan en un solo workspace y rutea sus webhooks entrantes por el mismo receptor. El truco es el campo whatsapp_account_id en cada payload de webhook — lleva el JID del número que recibió el mensaje. Léelo, haz switch sobre él, y despacha al paso persona (cuando tu agente acaba de responderle al cliente) o al paso agent (cuando el cliente acaba de escribirle a tu agente). Cada lado envía vía el POST /messages o POST /chats/{id}/messages normales desde la perspectiva del otro.

Arquitectura

  [+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

El lado persona es un cliente scripted: una lista de líneas para decir a continuación. Cuando es hora del siguiente turno, POST a /messages con el número de teléfono del agente como destinatario. TimelinesAI maneja el ruteo porque ambos números están en un mismo 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}`);
}

Receptor con jid-switch

Un receptor, un branch por lado. Todo lo demás que ya conoces del Setup — la auth con ?secret=, el filtro from_me de echoes, el fallback flat-vs-nested del payload — se aplica aquí sin cambios.

// 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);
  }
}

Esos dos snippets son la idea core. El harness completo — scripts de persona, cargador de escenarios, kickoff por CLI, logger split-pane con colores, config de Vercel — vive en examples/test-harness/ en el repo compañero, con su propio README que te guía por el deploy, los env vars, el registro del webhook y correr tu primer escenario end-to-end.

Mirándolo pasar

El harness corre autónomo — no necesita que apruebes cada respuesta. Tu supervisión sucede en el dashboard de TimelinesAI: abre el chat entre tu número persona y tu número agente en otra pestaña del navegador y cada turno aparece en vivo. Si el agente dice algo tonto, envía una respuesta manual desde la bandeja del agente para redirigir la conversación. Si necesitas cambiar el comportamiento en medio de un run, añade una label o escribe una nota en el chat — ambas son visibles para el skill del agente en su siguiente turno. Para el run borrando el webhook registrado o apagando la función de Vercel; el escenario se detiene inmediatamente.

Ejemplo: una vuelta completa

Un loop concreto de cinco pasos que enseña cómo se ve la API en la práctica — cómo tu agente envía un saliente, confirma la entrega, procesa la respuesta del cliente y manda un follow-up. Los números de teléfono, chat IDs y message UIDs de abajo son placeholders — sustitúyelos por los tuyos.

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

Límites y advertencias

Lo que esta guía NO cubre, y por qué.

Guías relacionadas

Si estás construyendo esto para un canal de cliente real, estas tres páginas cubren territorio adyacente que vas a tocar tarde o temprano.