Construa um agente de WhatsApp
com OpenClaw + TimelinesAI

O que seu agente pode fazer com WhatsApp

Com um skill do TimelinesAI instalado, seu agente OpenClaw pode operar o WhatsApp como um canal de cliente real. A versão longa desta lista está nas seções abaixo — cada capacidade tem as chamadas de API específicas que precisa.

Como usar este guia

Este guia é dual-mode. Você pode ler você mesmo e seguir o Setup manualmente — o caminho que as seções abaixo descrevem — ou pode entregar o guia inteiro para o seu agente OpenClaw (ou qualquer agente que consiga ler uma URL) e deixar que ele faça o setup pra você. Os dois caminhos chegam no mesmo lugar: quatro skills de WhatsApp instalados, token e webhook conectados, seu agente respondendo mensagens de clientes.

Se você está lendo isso você mesmo

Passe pelos grupos de capabilities abaixo — Incoming, Outbound, CRM & analytics, Operations — e decida quais importam pro seu caso de uso. Depois siga o Setup manualmente; são quatro passos e uns dez minutos. Cada capability lista as chamadas exatas de API que ela faz, e todo code block deste guia foi executado contra a API real do TimelinesAI antes da publicação. Se você travar, Coisas para saber reúne cada gotcha que vai te custar uma hora se você não souber dele de antemão.

Se você quer que seu agente faça o setup

Cole este prompt no OpenClaw (ou Claude Code, Cursor, Claude desktop, qualquer agente que consiga ler uma URL). Ele aponta pra este guia por URL pra que o agente leia a versão live, e depois te acompanha por install, token, webhook, smoke-test e habilitar seu primeiro skill — pedindo input só onde ele genuinamente precisa de algo seu.

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.

O prompt para de propósito antes de ligar qualquer envio outbound — ele te rotea primeiro por Channel choice pra você escolher o canal de WhatsApp certo (número pessoal vs Business API) pro que você está realmente tentando fazer. O risco de ban é real e vive upstream, não é algo do qual o gateway pode te proteger.

Setup

Quatro coisas para conectar. Depois disso, seu skill só faz chamadas de API.

1. 1

   Conecte seu número de WhatsApp

   Entre em app.timelines.ai, escaneie o QR com o telefone que tem seu número comercial. O TimelinesAI gerencia o gateway daqui em diante. Mesmo fluxo do setup padrão de número pessoal.

2. 2

   Pegue um token de API

   Integrações → API Pública → Copiar. Salve como TIMELINES_AI_API_KEY. Um único token cobre todo o workspace.

3. 3

   Instale um skill do repositório companheiro

   Clone InitechSoftware/openclaw-whatsapp-skills em ~/.openclaw/workspace/, depois faça symlink de cada diretório de skill em ~/.openclaw/skills/. Guia rápido de quatro linhas no README do repositório companheiro.

4. 4

   Registre um webhook

   Aponte message:received:new para uma URL HTTPS pública. O TimelinesAI vai mandar push das mensagens recebidas. Seu receptor invoca o OpenClaw.

Smoke-test do token

Antes de construir qualquer coisa, confirme que o auth funciona:

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

Você deveria ver

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

Se você vir outra coisa

• HTTP 401 com o texto puro Unauthorized — o token não foi aplicado. Reveja o passo 2, confirme que incluiu o prefixo Bearer e que o token não quebrou em linhas ao colar. A resposta é texto puro, não JSON — passar para o jq vai dar erro.
• Uma página HTML estilizada “Page not found” com HTTP 404 — você tem uma barra final ou um erro de digitação no caminho. A API serve HTML (não um erro JSON) para caminhos errados, então se sua saída começa com <!DOCTYPE html>, tire qualquer barra final e confira o caminho.

Registre o webhook uma 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 mínimo de webhook (Node / Vercel)

~40 linhas. Valida o query param ?secret=, descarta os echos de saída, responde 2xx dentro da janela de retry de 5 segundos e depois encaminha a mensagem para o seu 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 é o endpoint que o seu deployment de OpenClaw expõe para mensagens recebidas — depende de como você hospeda o agente. Para uma referência com notas de durabilidade pronta para produção, veja examples/vercel-webhook-receiver no repositório companheiro.

O que está dentro do seu workspace do OpenClaw

Você conectou um token de TimelinesAI e fez symlink de skills do repositório companheiro. Aqui está o que você realmente instalou, e quais arquivos você edita quando quer mudar como seu agente pensa, o que ele sabe e como se comporta. Nada aqui é mágica — é tudo markdown simples e arquivos env em dois diretórios.

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

Cada skill que você fez symlink é um diretório com um arquivo obrigatório (SKILL.md) mais os recursos que ele referencia. Se quer mudar como seu FAQ handler soa ou re-ordenar as perguntas do lead qualifier, a edição mora no SKILL.md daquele skill. Sem código para recompilar, sem build step.

Para os quatro skills de WhatsApp — whatsapp-autoresponder, whatsapp-lead-qualifier, whatsapp-send, whatsapp-delivery-check — o topo de cada SKILL.md tem o role e as tools permitidas; o body tem o prompt real com o qual seu agente roda. Leia um deles end-to-end antes de editar; os padrões se repetem.

Workspace — ~/.openclaw/workspace/

O diretório workspace é a casa do OpenClaw para tudo que não é skill: quem é seu agente, o que ele sabe de você, que tools ele tem, como ele inicializa. Os próprios docs do OpenClaw dizem “esta pasta é casa. Trate-a assim”. Esses arquivos vêm com o install — você preenche com o tempo:

Arquivos env por integração

Junto aos arquivos canônicos acima, você adiciona um arquivo env para cada integração que conecta. Esses NÃO fazem parte do install do OpenClaw — são seus, e guardam segredos que nunca deveriam ser commitados em um repo público:

Números pessoais vs WhatsApp Business API

Antes de construir fluxos de saída, entenda a qual canal de WhatsApp seu caso de uso pertence. Escolher errado leva a banimento.

Seguro com os skills deste guia (número pessoal)

• •Conversas recebidas. O cliente te escreve primeiro, você responde. Sem risco.
• •Envios transacionais. Confirmações de pedido, atualizações de envio, notificações de entrega, recibos de pagamento, lembretes de compromisso — qualquer mensagem que o cliente espera porque acabou de fazer algo com seu negócio.
• •Notificações disparadas por eventos em outras ferramentas. Negócio do HubSpot → confirmação de demo, falha de pagamento do Stripe → nota de recuperação, agendamento do Calendly → lembrete pré-reunião. O cliente optou quando usou a ferramenta upstream.
• •Responder dentro da janela de atendimento de 24 horas do WhatsApp. Quando o cliente te escreve, você tem 24 horas para responder livremente. Os skills de auto-resposta, FAQ e qualificação de leads operam dentro dessa janela.

NÃO seguro em números pessoais

• •Cold outreach para listas que você comprou ou raspou — o WhatsApp bane números por isso em horas.
• •Broadcasts de marketing para clientes que não optaram explicitamente.
• •Campanhas promocionais, ofertas de vendas, push sazonal, lançamentos de produto.
• •Qualquer coisa parecida com um blast de marketing. Se você está perguntando “qual throughput eu consigo”, você está no canal errado.

Como saber qual canal você precisa

1. 1.O cliente te escreveu primeiro, ou você está respondendo dentro de uma sessão ativa de 24 horas? → Número pessoal, este guia.
2. 2.O cliente está prestes a receber algo que ele explicitamente espera (pedido, compromisso, pagamento, entrega)? → Número pessoal, envio transacional.
3. 3.Disparado por um evento opt-in do cliente no seu CRM ou ferramenta de billing? → Número pessoal, envio disparado por evento.
4. 4.Broadcast, cold outreach ou campanha promocional? → Business API, use o dashboard do TimelinesAI.
5. 5.Não tem certeza? → Não envie. Trate como promocional e roteie pelo caminho Business API.

Cada capacidade de saída abaixo assume que você passou neste teste. Se não tem certeza, releia esta seção antes de shipar. O TimelinesAI não pode te proteger do banimento na camada do WhatsApp — o ban acontece upstream, na infraestrutura do WhatsApp, não no gateway.

Referência da API

Cada endpoint que você precisa para construir cada capacidade abaixo. URL base https://app.timelines.ai/integrations/api. Auth Authorization: Bearer $TIMELINES_AI_API_KEY.

Coisas para saber

Alguns detalhes fáceis de passar batido na referência e que cada um vai te custar uma hora se você não souber.

Quando as chamadas de API falham

Cinco modos de falha vão atingir seu skill cedo ou tarde. Cada um aparece diferente na resposta e cada um tem uma resposta correta diferente.

Um padrãozinho de shell que ramifica por cada código de status:

$ # 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 com segurança em produção

Mais duas coisas que não são falhas, mas vão te poupar de um dia ruim depois.

Contexto da conversa

O webhook entrega ao seu skill uma única mensagem — a que acabou de chegar. Sem turnos anteriores, sem histórico de chat, sem transcrição em andamento. Para um FAQ sem estado ou um respondedor fora do horário, isso basta. Para um agente de conversa que precisa lembrar o que o cliente disse três turnos atrás, o seu skill tem que buscar o contexto por conta própria. Três padrões cobrem toda a faixa, do loop mais barato ao que realmente lembra.

Buscar a janela é um único GET. A resposta é um array plano de mensagens do chat, a mais nova por último, misturando turnos recebidos do cliente com suas próprias respostas enviadas e qualquer nota que o seu skill tenha escrito:

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

Armadilhas que mordem em produção

Persistência de estado

Skills do OpenClaw não mantêm estado em memória entre invocações. Conversas de WhatsApp são multi-turno. A solução é guardar o estado no próprio chat:

• •Etiquetas guardam o estágio discreto — discovery/q1, qualified, escalate. Adicione com POST /chats/{id}/labels, leia com GET /chats/{id}/labels.
• •Notas guardam dados estruturados — team_size=8, rascunhos de resposta, scores de leads. Adicione com POST /chats/{id}/notes. Leia iterando GET /chats/{id}/messages e filtrando message_type == "note".

A vantagem: segurança contra crash, visibilidade para o time humano, handoff limpo — um humano pode limpar uma etiqueta para voltar o fluxo, ou adicionar escalate para assumir. O trade-off: cada transição de estado é uma chamada HTTP. Para fluxos voltados ao cliente isso é OK.

Enviar do número certo

Se seu workspace tem mais de um número de WhatsApp conectado, seu skill precisa garantir que envia do número esperado. Cada chat tem um campo whatsapp_account_id com o JID completo (tipo TELEFONE@s.whatsapp.net) do número dono. Quando você faz POST /chats/{id}/messages, o remetente é sempre esse JID — você não escolhe, o chat escolhe.

O padrão:

1. 1Hardcode o JID de remetente permitido no environment de cada skill (ex.: ALLOWED_SENDER_JID).
2. 2Antes de enviar, GET /chats/{id} e compare whatsapp_account_id com o seu JID permitido.
3. 3Se não bater, pule o envio — escale para um humano ou descarte o evento.

Duas chamadas HTTP extras por turno, zero chance de enviar do persona errado. Para workspaces de um número só isso não se aplica.

Mensagens recebidas — o que seu agente pode lidar

Toda vez que um cliente manda mensagem para o seu número de WhatsApp, o TimelinesAI dispara um evento message:received:new para o seu webhook com o chat id, o texto, o telefone do remetente e os anexos. Seu skill lê o evento, decide o que fazer e responde com POST /chats/{chat_id}/messages. Tudo abaixo é uma variação desse 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"}

Saída — mensagens que seu agente inicia

Mensagens que seu agente inicia, não respostas. Disparadas por um evento nas suas outras ferramentas (um pedido novo, um pagamento que falhou, uma reunião agendada) ou por instrução humana direta sobre uma pessoa específica.

Antes de cada capacidade desta seção: o cliente abriu o thread recentemente (dentro da janela de sessão de 24 horas do WhatsApp) ou explicitamente espera essa mensagem. Se nenhuma das duas é verdade, não envie de um número pessoal — isso é território 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 e análise

Os endpoints de leitura dão ao seu agente dados suficientes para responder perguntas analíticas e sincronizar estado com seu CRM em linguagem 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

Escala e handoff

Padrões para fluxos human-in-the-loop, roteamento multi-agente e memória de conversa. As quatro capacidades abaixo são desenhadas para coexistir com humanos trabalhando os mesmos chats da caixa compartilhada do 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'.

Teste seu agente end-to-end com um segundo número de WhatsApp

Depois do setup você pode ver as capabilities listadas aqui, mas não consegue ver seu agente realmente trabalhando até que um cliente real mande mensagem pra ele. Esse é um loop ruim pra iterar. Aqui está um melhor: conecte um segundo número de WhatsApp ao mesmo workspace do TimelinesAI, use-o como cliente scripted e observe seu skill real lidar com a conversa end-to-end. Sem mocks, sem webhooks falsos — é seu agente real, sua API real, só que com um segundo número fazendo o papel do humano do outro lado.

O padrão

TimelinesAI permite que vários números de WhatsApp vivam em um só workspace e roteia os webhooks recebidos pelo mesmo receiver. O truque é o campo whatsapp_account_id em todo payload de webhook — ele carrega o JID do número que recebeu a mensagem. Leia, faça switch nele, e despache ou para o passo persona (quando seu agente acabou de responder o cliente) ou para o passo agent (quando o cliente acabou de mandar mensagem para seu agente). Cada lado envia via o POST /messages ou POST /chats/{id}/messages normais da perspectiva do outro.

Arquitetura

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

O lado persona é um cliente scripted: uma lista de linhas para dizer a seguir. Quando é hora do próximo turno, POST em /messages com o número de telefone do agente como destinatário. O TimelinesAI cuida do roteamento porque os dois números estão em um mesmo 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 com jid-switch

Um receiver, um branch por lado. Todo o resto que você já sabe do Setup — a auth com ?secret=, o filtro from_me de echoes, o fallback flat-vs-nested do payload — se aplica aqui sem mudanças.

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

Esses dois snippets são a ideia central. O harness completo — scripts de persona, loader de cenários, kickoff por CLI, logger split-pane colorido, config de Vercel — mora em examples/test-harness/ no repositório companheiro, com seu próprio README que guia pelo deploy, env vars, registro de webhook e rodar seu primeiro cenário end-to-end.

Observando acontecer

O harness roda autônomo — não precisa que você aprove cada resposta. Sua supervisão acontece no dashboard do TimelinesAI: abra o chat entre seu número persona e seu número agente em outra aba do navegador e cada turno aparece ao vivo. Se o agente disser algo bobo, mande uma resposta manual da caixa de entrada do agente para redirecionar a conversa. Se você precisa mudar o comportamento no meio de um run, adicione uma label ou escreva uma nota no chat — ambas são visíveis para o skill do agente no próximo turno. Pare o run deletando o webhook registrado ou desligando a função da Vercel; o cenário para imediatamente.

Exemplo: uma volta completa

Um loop concreto de cinco passos mostrando como a API se parece na prática — como seu agente envia uma saída, confirma a entrega, processa a resposta do cliente e manda um follow-up. Os números de telefone, chat IDs e message UIDs abaixo são placeholders — substitua pelos seus.

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

Limites e ressalvas

O que este guia NÃO cobre, e por quê.

Guias relacionados

Se você está construindo isso para um canal de cliente real, estas três páginas cobrem território adjacente que você vai tocar mais cedo ou mais tarde.