Bir WhatsApp ajanı inşa et
OpenClaw + TimelinesAI ile

Ajanın WhatsApp ile neler yapabilir

Bir TimelinesAI skill'i kuruldu mu, OpenClaw ajanın WhatsApp'ı gerçek bir müşteri kanalı olarak çalıştırabilir. Bu listenin uzun versiyonu aşağıdaki bölümlerde — her yetenek ihtiyaç duyduğu spesifik API çağrılarına sahip.

Bu rehber nasıl kullanılır

Bu rehber dual-mode. Kendin okuyup Setup'ı manuel olarak yapabilirsin — aşağıdaki bölümlerin serdiği yol — ya da tüm rehberi OpenClaw agent'ına (veya URL okuyabilen herhangi bir agent'a) verebilir ve setup'ı senin yerine yapmasına izin verebilirsin. Her iki yol da aynı yere varıyor: kurulmuş dört WhatsApp skill'i, bağlanmış token ve webhook, müşteri mesajlarına cevap veren agent'ın.

Eğer bunu kendin okuyorsan

Aşağıdaki capability gruplarını — Incoming, Outbound, CRM & analytics, Operations — gözden geçir ve hangisinin kullanım durumun için önemli olduğuna karar ver. Sonra Setup'ı manuel olarak takip et; dört adım, yaklaşık on dakika. Her capability yaptığı tam API çağrılarını listeler ve bu rehberdeki her code block yayınlanmadan önce gerçek TimelinesAI API'ına karşı çalıştırıldı. Tıkanırsan Bilmen gerekenler, önceden bilmezsen seni bir saate mal olacak her gotcha'yı toplar.

Setup'ı agent'ın yapmasını istiyorsan

Bu prompt'u OpenClaw'a (ya da Claude Code, Cursor, Claude desktop, URL okuyabilen herhangi bir agent'a) yapıştır. Bu rehbere URL ile işaret eder ki agent live sürümü okusun, sonra seni install, token, webhook, smoke-test ve ilk skill'ini etkinleştirme boyunca gezdirir — sadece gerçekten senden bir şey gereken yerlerde input ister.

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.

Prompt bilinçli olarak herhangi bir outbound göndermeyi açmadan önce durur — gerçekten yapmaya çalıştığın şey için doğru WhatsApp kanalını (personal numara vs Business API) seçmenin için seni önce Kanal seçimi'nden geçirir. Ban riski gerçek ve upstream'de yaşar, gateway'in seni koruyabileceği bir şey değil.

Kurulum

Bağlanacak dört şey. Sonrasında skill'in sadece API çağrıları yapar.

1. 1

   WhatsApp numaranı bağla

   app.timelines.ai'a giriş yap, iş numaranı taşıyan telefonla QR kodu tara. TimelinesAI bundan sonra geçidi yürütür. Standart personal-number kurulumuyla.

2. 2

   Bir API token'ı al

   Integrations → Public API → Copy. TIMELINES_AI_API_KEY olarak kaydet. Tek token tüm workspace'i kapsar.

3. 3

   Companion repodan bir skill kur

   InitechSoftware/openclaw-whatsapp-skills'i ~/.openclaw/workspace/ altına klonla, sonra her skill dizinini ~/.openclaw/skills/ altına symlinkle. Dört satırlık quickstart companion README’de.

4. 4

   Bir webhook kayıt et

   message:received:new'i bir public HTTPS URL'sine yönlendir. TimelinesAI gelen mesajları oraya pushlar. Receiver'ın OpenClaw'ı çağırır.

Token smoke testi

Herhangi bir şey inşa etmeden önce auth'un çalıştığını onayla:

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

Şunu görmelisin

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

Başka bir şey görüyorsan

• HTTP 401 ve çıplak Unauthorized metni — token geçmemiş. Adım 2'yi tekrar kontrol et, Bearer önekini eklediğinden ve tokenin yapıştırırken satır atlamadığından emin ol. Cevap düz metin, JSON değil — jq'ya pipe edersen hata verir.
• HTTP 404 ile bootstrap stilinde HTML “Page not found” sayfası — sonda slash ya da path'de typo var. API hatalı path'ler için HTML döner (JSON error değil), yani çıktın <!DOCTYPE html> ile başlıyorsa sondaki slash'ı kaldır ve path'i tekrar kontrol et.

Webhook'u bir kez kayıt et

# 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 satır. ?secret= query param'ını doğruluyor, giden echo'ları düşürüyor, 5 saniyelik retry penceresi içinde 2xx döndürüyor, sonra mesajı OpenClaw host'una iletir.

// 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, OpenClaw dağıtımının gelen mesajlar için açtığı endpoint — agent'ı nasıl host ettiğine bağlı. Durability notları olan production-ready bir referans için companion repodaki examples/vercel-webhook-receiver'a bak.

OpenClaw workspace'inin içinde ne var

Bir TimelinesAI token'ı bağladın ve companion repodan skill'leri symlink ettin. İşte gerçekte ne kurduğun ve agent'ının nasıl düşündüğünü, neyi bildiğini ve nasıl davrandığını değiştirmek istediğinde hangi dosyaları düzenleyeceğin. Burada sihir yok — iki dizinde basit markdown ve env dosyaları hepsi bu.

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

Symlink'lediğin her skill, bir zorunlu dosya (SKILL.md) ve o dosyanın referans verdiği kaynakları olan bir dizindir. FAQ handler'ının tonunu değiştirmek veya lead qualifier'ın sorularını yeniden sıralamak istiyorsan, düzenleme o skill'in SKILL.md'sinde yaşar. Derlenecek kod yok, build step yok.

Dört WhatsApp skill'i için — whatsapp-autoresponder, whatsapp-lead-qualifier, whatsapp-send, whatsapp-delivery-check — her SKILL.md'nin üst kısmında role ve izin verilen tool'lar var; body'de agent'ının çalıştığı gerçek prompt var. Düzenlemeden önce birini baştan sona oku; pattern'ler tekrar ediyor.

Workspace — ~/.openclaw/workspace/

Workspace dizini OpenClaw'un skill olmayan her şey için evidir: agent'ının kim olduğu, hakkında neyi bildiği, hangi tool'lara sahip olduğu, nasıl boot ettiği. OpenClaw'un kendi dokümanları “bu klasör evdir. Öyle davran” der. Bu dosyalar install ile gelir — zamanla doldurursun:

Entegrasyon başına env dosyaları

Yukarıdaki canonical dosyaların yanında, bağladığın her entegrasyon için bir env dosyası eklersin. Bunlar OpenClaw install'ın PARÇASI DEĞİL — bunlar senin, ve public bir repoya asla commit edilmemesi gereken secret'ları tutar:

Personal numaralar vs WhatsApp Business API

Giden akışları inşa etmeden önce kullanım durumunun hangi WhatsApp kanalına ait olduğunu anla. Yanlış seçmek numaraları banlattırır.

Bu rehberdeki skill'lerle güvenli (personal numara)

• •Gelen konuşmalar. Müşteri sana önce yazar, sen yanıtlarsın. Risk yok.
• •Transactional gönderimler. Sipariş onayları, kargo güncellemeleri, teslimat bildirimleri, ödeme makbuzları, randevu hatırlatmaları — müşterinin işinle az önce bir şey yaptığı için beklediği her mesaj.
• •Diğer araçlardaki olaylardan tetiklenen bildirimler. HubSpot deal → demo onayı, Stripe başarısız ödeme → recovery notu, Calendly rezervasyonu → toplantı öncesi hatırlatma. Müşteri upstream aracı kullandığında opt-in vermiş olur.
• •WhatsApp'ın 24 saatlik müşteri hizmetleri penceresinde yanıtlamak. Bir müşteri sana yazdığında, serbestçe yanıtlamak için 24 saatin var. Autoresponder, FAQ yöneticisi ve lead qualifier skill'leri bu pencere içinde çalışır.

Personal numaralarda GÜVENLİ DEĞİL

• •Satın aldığın veya scrap'ledığin listelere cold outreach — WhatsApp bunun için numaraları saatler içinde banlar.
• •Açıkça opt-in vermemiş müşterilere marketing broadcast'leri.
• •Promosyon kampanyaları, satış teklifleri, mevsimsel pushlar, ürün lansmanları.
• •Bir marketing blast'a benzeyen her şey. “Ne kadar throughput alabilirim” diye sorduysan, yanlış kanaldasın.

Hangi kanala ihtiyacın olduğunu nasıl anlarsın

1. 1.Müşteri sana önce yazdı mı, ya da aktif bir 24 saatlik oturum içinde mi yanıtlıyorsun? → Personal numara, bu rehber.
2. 2.Müşteri açıkça beklediği bir şey almak üzere mi (sipariş, randevu, ödeme, teslimat)? → Personal numara, transactional gönderim.
3. 3.CRM'in veya billing aracındaki bir müşteri-opt-in olayı tarafından mı tetiklendi? → Personal numara, olay tetikli gönderim.
4. 4.Broadcast, cold outreach veya promosyon kampanyası mı? → Business API, TimelinesAI dashboard'u kullan.
5. 5.Emin değil misin? → Gönderme. Promosyon olarak kabul et ve Business API yoluna yönlendir.

Aşağıdaki her giden yeteneği bu testi geçtiğini varsayar. Emin değilsen, shipping yapmadan önce bu bölümü tekrar oku. TimelinesAI seni WhatsApp katmanındaki ban'dan koruyamaz — ban upstream'de, WhatsApp'ın altyapısında uygulanır, geçitte değil.

API referansı

Aşağıdaki her yeteneği inşa etmek için ihtiyaç duyacağın her endpoint. Base URL https://app.timelines.ai/integrations/api. Auth Authorization: Bearer $TIMELINES_AI_API_KEY.

Bilmen gerekenler

Referansta gözden kaçırması kolay olan ve bilmediğin her biri sana bir saat mal olacak birkaç detay.

API çağrıları başarısız olduğunda

Beş hata modu sonunda skill'ine çarpacak. Her biri yanıtta farklı görünür ve her birinin farklı bir doğru yanıtı vardır.

Her status koduna göre dallanan küçük bir shell pattern'ı:

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

Üretimde güvenli çalıştırma

Hata olmayan, ama daha sonra kötü bir gününden seni kurtaracak iki şey daha.

Konuşma bağlamı

Webhook skill'ine tek bir mesaj verir — yeni gelen mesajı. Önceki turlar yok, sohbet geçmişi yok, akışta bir transkript yok. Durumsuz bir SSS veya mesai dışı yanıtlayıcı için bu yeterli. Müşterinin üç tur önce ne dediğini hatırlaması gereken bir konuşma ajanı içinse bağlamı skill'in kendisi çekmek zorunda. Üç desen tüm yelpazeyi kapsar — mümkün olan en ucuz döngüden gerçekten hatırlayanına kadar.

Pencereyi çekmek tek bir GET. Yanıt sohbetin düz bir mesaj dizisidir, en yenisi sonda, müşterinin gelen turları, kendi giden yanıtların ve skill'inin yazdığı her not karışık gelir:

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

Prod'da ısıran tuzaklar

Durum kalıcılığı

OpenClaw skill'leri invocation'lar arası hafızada durum tutmaz. WhatsApp konuşmaları çok turludur. Çözüm, durumu sohbete kaydetmektir:

• •Etiketler ayrık aşamayı tutar — discovery/q1, qualified, escalate. POST /chats/{id}/labels ile ekle, GET /chats/{id}/labels ile oku.
• •Notlar yapılandırılmış veriyi tutar — team_size=8, yanıt taslakları, lead skorları. POST /chats/{id}/notes ile ekle. GET /chats/{id}/messages üzerinde iterate ederek ve message_type == "note" ile filtreleyerek oku.

Avantaj: crash güvenliği, insan ekip arkadaşlarına görünürlük, temiz handoff — bir insan akışı geri sarmak için bir etiketi temizleyebilir veya devralmak için escalate ekleyebilir. Trade-off: her durum geçişi bir HTTP çağrısıdır. Müşteri yüzüne dönük akışlar için bu sorun değil.

Doğru numaradan gönder

Workspace'ine birden fazla WhatsApp numarası bağlıysa, skill'inin amaca uygun olandan gönderdiğinden emin olması gerekir. Her sohbette sahibi olan numaranın tam JID'ini (TELEFON@s.whatsapp.net gibi) tutan whatsapp_account_id alanı vardır. POST /chats/{id}/messages yaptığında, gönderici her zaman o JID'dir — sen seçmezsin, sohbet seçer.

Pattern:

1. 1Her skill'in environment'ında izin verilen gönderici JID'i hardcode et (örn. ALLOWED_SENDER_JID).
2. 2Göndermeden önce GET /chats/{id} ile whatsapp_account_id'i izin verilen JID'inle karşılaştır.
3. 3Eşleşmiyorlarsa, gönderimi atla — bir insana eskalasyon yap veya olayı bırak.

Tur başına iki ek HTTP çağrısı, yanlış persona'dan gönderme şansı sıfır. Tek numaralı workspace'ler için geçerli değil.

Gelen mesajlar — ajanın neyi yönetebilir

Bir müşteri WhatsApp numarana her mesaj attığında, TimelinesAI webhook'una sohbet id'si, metin, gönderici telefonu ve eklerle bir message:received:new olayı tetikler. Skill'in olayı okur, ne yapacağına karar verir ve POST /chats/{chat_id}/messages ile yanıtlar. Aşağıdaki her şey bu döngünün bir varyasyonudur.

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

Giden — ajanın başlattığı mesajlar

Ajanın başlattığı mesajlar, yanıt değil. Diğer araçlarındaki bir olay (yeni bir sipariş, başarısız bir ödeme, planlanmış bir toplantı) veya belirli bir kişi hakkında doğrudan bir insan talimatı tarafından tetiklenir.

Bu bölümdeki her yetenekten önce: müşteri ya thread'i yakın zamanda açtı (WhatsApp'ın 24 saatlik oturum penceresi içinde) ya da bu mesajı açıkça bekliyor. Hiçbiri doğru değilse, personal numaradan gönderme — o Business API bölgesidir.

$ 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 ve analiz

Okuma endpoint'leri ajanına analitik sorulara yanıt verecek ve doğal dilde CRM'inle durumu senkronize edecek kadar veri verir.

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

Ölçekleme ve handoff

Human-in-the-loop iş akışları, multi-agent yönlendirme ve konuşma hafızası için pattern'lar. Aşağıdaki dört yeteneğin tamamı, TimelinesAI paylaşılan inbox'ından aynı sohbetler üzerinde çalışan insanlarla bir arada var olacak şekilde tasarlanmıştır.

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

Agent'ını ikinci bir WhatsApp numarasıyla uçtan uca test et

Setup'tan sonra burada listelenen capability'leri görebilirsin, ama gerçek bir müşteri agent'ına yazana kadar onu gerçekten çalışırken göremezsin. Bu, iterasyon için kötü bir loop. İşte daha iyisi: aynı TimelinesAI workspace'ine ikinci bir WhatsApp numarası bağla, onu scripted bir müşteri olarak kullan ve gerçek skill'inin konuşmayı uçtan uca yönettiğini izle. Mock yok, sahte webhook yok — gerçek agent'ın, gerçek API'ın, sadece diğer tarafta insan rolünü oynayan ikinci bir numarayla.

Pattern

TimelinesAI birden fazla WhatsApp numarasının tek bir workspace'te yaşamasına izin verir ve onların gelen webhook'larını aynı receiver'dan yönlendirir. İşin püf noktası her webhook payload'ındaki whatsapp_account_id alanı — mesajı alan numaranın JID'ini taşır. Onu oku, üzerinde switch yap ve ya persona adımına (agent müşteriye yeni cevap verdiğinde) ya da agent adımına (müşteri agent'a yeni mesaj yazdığında) yönlendir. Her iki taraf da diğer tarafın perspektifinden normal POST /messages veya POST /chats/{id}/messages ile gönderir.

Mimari

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

Persona tarafı scripted bir müşteri: sıradaki söylenecek cümlelerin listesi. Sıradaki tur zamanı geldiğinde, alıcı olarak agent'ın telefon numarasıyla /messages'a POST et. Her iki numara tek workspace'te olduğu için TimelinesAI routing'i halleder.

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

JID-switch'li receiver

Bir receiver, taraf başına bir branch. Setup'tan zaten bildiğin geri kalan her şey — ?secret= auth'u, from_me echo filtresi, düz-vs-iç içe payload fallback'i — burada değişmeden uygulanır.

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

Bu iki snippet işin özü. Tam harness — persona script'leri, scenario loader, CLI kickoff, renkli split-pane logger, Vercel config — companion repoda examples/test-harness/ altında yaşar, kendi README'sinde deploy, env var'lar, webhook kaydı ve ilk scenarionu uçtan uca çalıştırma rehberi var.

Olduğu gibi izle

Harness otonom çalışır — her yanıtı onaylaman gerekmez. Gözetimin TimelinesAI dashboard'da olur: persona numaran ile agent numaran arasındaki sohbeti başka bir browser sekmesinde aç ve her tur canlı görünür. Agent aptalca bir şey söylerse, konuşmayı yönlendirmek için agent'ın inbox'ından manuel bir yanıt gönder. Bir run'ın ortasında davranışı değiştirmen gerekirse, sohbete label ekle veya not yaz — her ikisi de agent'ın bir sonraki turda skill'ine görünür. Kayıtlı webhook'u silerek veya Vercel fonksiyonunu kapatarak run'ı durdur; scenario anında durur.

Örnek: tam bir tur

Pratikte API'nin nasıl göründüğünü gösteren beş adımlık somut bir döngü — ajanın bir outbound gönderir, teslimatı onaylar, müşterinin yanıtını işler ve bir follow-up gönderir. Aşağıdaki telefon numaraları, sohbet ID'leri ve message UID'leri placeholder — kendininkilerle değiştir.

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

Sınırlar ve uyarılar

Bu rehberin kapsamadığı şeyler ve nedenleri.

İlgili rehberler

Bunu gerçek bir müşteri kanalı için inşa ediyorsan, bu üç sayfa er ya da geç dokunacağın bitişik araziyi kaplıyor.