ThunderPhone v3 yayında.Hemen kendiniz kullanmaya başlayın; dakikası 2 sentten başlayan fiyatlarla.Duyuruyu okuyun

Developer cookbook

Slack veya bir sohbet uygulamasından aramaları yürütün

Genel API

Ekibinizin zaten kullandığı sohbet uygulamasından bir ajanı yönlendirebilirsiniz. Bir mesaj aramayı başlatır. Arama bir ileti dizisinde canlı olarak ilerler. İleti dizisindeki bir yanıt ajanı yönlendirir. Ajanın bir karara ihtiyacı olduğunda, size orada sorar ve yanıtınızı bekler.

ThunderPhone bu botu sizin için barındırmaz. Siz (veya kodlama ajanınız), sohbet uygulamanızı genel API'ye bağlayan küçük bir sunucu oluşturursunuz. Bu sayfa bileşenleri gösterir. Slack, Microsoft Teams, Discord veya özel bir web sohbet sayfası için aynıdırlar; örneklerde Slack kullanılır.

Nasıl çalışır

Sohbette bunu yaparsınızBotunuz bunu çağırırOlanlar
"Comcast'i ara ve kesintinin tahmini bitiş saatini öğren" mesajını gönderinMesaj context olarak POST /v1/callAjan arama yapar. Botunuz arama için bir ileti dizisi açar
İleti dizisini izleyintelephony.turn webhook'larını alırAjanın veya diğer kişinin söylediği her satır ileti dizisinde görünür
Arama sırasında ileti dizisinde yanıt verinPOST /v1/calls/{call_id}/whisperAjan notunuzu özel olarak alır ve buna göre hareket eder. Diğer kişi bunu asla duymaz
Ajanın sorusunu yanıtlayınAraç uç noktanız yanıtınızı döndürür veya daha sonra POST /v1/calls/{call_id}/tool-results ile iletirAjan aramaya bununla devam eder; bekletme modunda diğer kişi bu sırada bekletme müziği duyar
Sonucu okuyuntelephony.complete alırBotunuz özeti ve sonucu gönderir

Botunuz tek bir eşleme tutar: hangi sohbet ileti dizisinin hangi call_id değerine ait olduğu.

Başlamadan önce

  • Bir API anahtarı; sunucunuzda saklanmalı, tarayıcıda veya sohbette asla bulunmamalıdır. Entegrasyonlar → API anahtarları altında bir tane oluşturun (bkz. Sunucu API anahtarı oluşturma).
  • Aramalar için giden arama etkin bir numara ve bir yapay zeka ajanı. Mesaj, arama başına context olur; böylece tek bir genel ajan her görevi yönetir.
  • Railway, Fly.io, Render veya kendi barındırıcınız gibi webhook alabilen bir sunucu.
  • Bu sunucuyu işaret eden ve telephony.turn ile telephony.complete aboneliği olan bir webhook uç noktası. Tur olayları yalnızca bunları listeleyen uç noktalara gönderilir. Bkz. Webhook'lar. Tur olayları için ajanın arama kaydının açık olması, arama sonu summary içinse ajanın Arama özeti oluştur ayarının etkin olması gerekir; bunlar olmadan bu alanlar boş kalır.
  • Kendi sohbet uygulamanız. Slack için çalışma alanınızda api.slack.com/apps adresinden bir uygulama oluşturun.

1. Bir mesajdan arama başlatın

Botunuz bir mesaj aldığında (doğrudan mesaj veya @bahsetme), Slack'in isteğini hemen onaylayın (Slack, 3 saniye içinde onaylanmayan her şeyi yeniden dener) ve kalan işlemleri arka planda yapın. Gönderenin arama yapma yetkisi olduğunu kontrol edin, ardından mesajı context olarak kullanarak aramayı başlatın:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

Döndürülen call_id değerini Slack ileti dizisiyle (channel ve mesajın ts değeri) birlikte kaydedin ve ileti dizisinde yanıt verin ("Aranıyor…"). idempotency_key değerini kanal ve mesajın ts değerinden oluşturun (bir ts yalnızca kendi kanalı içinde benzersizdir); böylece yeniden denenen bir Slack etkinliği ikinci bir arama başlatmaz. İstek numara yerine bir kişi belirtiyorsa botunuz önce numarayı bulur. ThunderPhone yalnızca gönderdiğiniz to_number değerini arar.

2. Aramayı ileti dizisinde takip edin

Her telephony.turn webhook'u call_id, konuşmacı (role: ajan için assistant, diğer kişi için user), text ve dönüşün position değerini içerir. İleti dizisini call_id ile bulun ve satırı yayınlayın.

  • İşlem yapmadan önce her webhook'u doğrulayın. Bkz. Webhook imzalarını doğrulama.
  • Zarfın event_id değerine göre yinelenenleri kaldırın ve position değerine göre sıralayın. Teslimat en az bir kez yapılır ve dönüşler sırasız gelebilir.
  • Yoğun bir arama ileti dizisini dolduracaksa satırları toplu gönderin; her satır için bir mesaj yerine birkaç saniyede bir gönderi yapmak daha okunaklıdır.

telephony.complete geldiğinde, aramanın nasıl bittiğini (status ve end_reason), summary değerini ve çıkarılan tüm verileri yayınlayın, ardından ileti dizisini kapatın. Alanlar için bkz. Arama tamamlandı.

3. Aramayı ileti dizisinden yönlendirin

Birisi canlı bir aramanın ileti dizisinde yanıt verdiğinde, sesli AI ajanı bir soru için yanıt beklemiyorsa (4. adım) yanıtı fısıltı olarak gönderin; bu durumda yanıt, sorunun cevabıdır:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

Ajan bunu özel olarak duyar ve sonraki dönüşüne dahil eder; karşı taraf fısıltının kendisini asla duymaz. Fısıltı 1 ila 1000 karakter olabilir. Bir 409, aramanın artık canlı olmadığı anlamına gelir: ileti dizisine aramanın sona erdiğini bildirin.

4. Ajanın size soru sormasını sağlayın

Ajana, sunucunuzu çağıran tek question parametresine sahip ask_owner gibi bir araç verin. Bunu bir API bağlantısı olarak oluşturun ve ajana bağlayın. Her araç isteği, çağrıyı X-ThunderPhone-Call-ID başlığında taşır.

Yanıtı geri almanın üç yolu vardır.

Aramayı bekletin (10 dakikaya kadar). Aracı bekletme moduna ayarlayın: spec.wait_mode "hold" ve spec.timeout en fazla 600 saniye olsun (zaman aşımı olmadan bekletme 20 saniye sürer). Bunu API üzerinden yapabilir veya Zeus'tan ayarlamasını isteyebilirsiniz (uygulamanın düzenleyicilerinde henüz bu alanların hiçbiri yoktur). Uç noktanız soruyu aramanın ileti dizisine gönderir ve hemen beklemede olan bir sonuçla yanıt verir:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

Karşı taraf ajandan bir cümle duyar, ardından bekletme müziği başlar. Telefon menüsünde veya sesli mesajda ajan bunun yerine sesli güncellemeler kullanır ve tam çift yönlü bir ajan bekletmez: bekleyen yanıtı sonuç olarak alır. Yanıt ileti dizisine ulaştığında, şu yöntemle teslim edin: POST /v1/calls/{call_id}/tool-results:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

Müzik yavaşça kesilir ve ajan yanıtınızla devam eder. timeout süresinden önce kimse yanıt vermezse, ajana yanıt gelmediği bildirilir ve karşı tarafa sonraki adımları sunar. Bir çağrı için soru beklemedeyken, ileti dizisindeki sonraki yanıt soruyu yanıtlar: bunu araç sonucu olarak teslim edin ve ayrıca fısıltı olarak göndermeyin (fısıltı, aracı yalnızca araç döndükten sonra ajana ulaşır). Bkz. Uzun beklemeler.

İstekte bekleyin (3 dakikaya kadar). Uç noktanız soruyu gönderir, yanıt bekler ve örneğin {"answer": "Yes, book Tuesday at 10."} şeklinde döndürür. Aracın spec.timeout değerini API üzerinden en fazla 180 saniye olarak ayarlayın (varsayılan değer 20'dir). Uç noktanıza birkaç saniye daha kısa kendi zaman sınırını verin (örneğin 170 saniye); böylece kimse yanıtlamadığında bile ajanın işlem yapabileceği bir şey döndürür, örneğin {"answer": null, "note": "No reply yet. Offer to take a message."}. timeout sınırına ulaşan bir araç ajana hata olarak ulaşır ve barındırıcınızın isteği bu süre boyunca açık tutması gerekir. Beklerken ajan karşı tarafa kontrol ettiğini söyler, yaklaşık 12 saniye sonra hâlâ çalıştığını belirtir ve ardından yaklaşık her 15 saniyede bir kısa güncelleme verir. Bekletme modu burada da çalışır: spec.wait_mode değerini "hold" olarak ayarlayın; böylece karşı taraf güncellemeler yerine müzik duyar.

Fısıltıyla yanıtlayın. Uç noktanız soruyu gönderir ve hemen döner, örneğin {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Yanıt ulaştığında bunu fısıltı olarak gönderin (3. adım) ve ajan hemen buna yanıt verir. Bunu 10 dakikadan uzun sürebilecek yanıtlar için kullanın. Çağrı bekletilmez: isteminiz, bu sırada yapay zeka ajanının ne yapacağını söylemelidir; örneğin karşı tarafa eşlik etmek veya onu geri aramayı teklif etmek.

Her durumda, ajanın isteminde aracı ne zaman kullanacağını ve beklerken karşı tarafa ne söyleyeceğini belirtin:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

Planlama için sınırlar

  • Uç noktanız, aracın timeout süresi içinde ve en fazla 180 saniye içinde yanıt vermelidir. Bekletme modundaki bir araç, bekleyen sonuçla aramayı en fazla 600 saniye bekletebilir.
  • Bir araç beklerken ajan karşı taraftaki kişiye yanıt vermez. Bekletme modunda müzik duyarlar; aksi takdirde kısa sesli güncellemeler duyarlar.
  • Fısıltı en fazla 1000 karakter olabilir.
  • telephony.turn teslimi en az bir kez yapılır ve sırasız olabilir.

Güvenlik kontrol listesi

  • API anahtarını sunucunuzda tutun.
  • Webhook'larda ve araç isteklerinde ThunderPhone imzalarını, Slack isteklerinde ise Slack imzalama gizli anahtarını doğrulayın. İki ThunderPhone imzası farklı gizli anahtarlar kullanır: webhook teslimleri webhook uç noktasının kendi gizli anahtarını, araç istekleri ise kuruluşunuzun GET /v1/webhook içindeki webhook gizli anahtarını kullanır.
  • Aramaları kimlerin başlatabileceğine karar verin: arama başlatmadan önce Slack kullanıcı kimliğini kontrol edin.
  • Giden aramalar diğer tüm aramalarla aynı kurallara tabidir. Bkz. Giden arama yasaları.

Bir kodlama ajanıyla oluşturun

Kodlama ajanınızı dokümanlar MCP sunucusuna ve bu sayfaya yönlendirin; ardından "bu kılavuzu izleyen ThunderPhone ajanım için bir Slack botu" isteyin. ThunderPhone uygulamasındaki yapay zeka ajanı Zeus, ajanın tarafını (webhook uç noktası, araç ve istem satırları) ayarlayabilir ve sohbette bot için başlangıç kodu yazabilir.