Open in
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ız | Botunuz bunu çağırır | Olanlar |
|---|---|---|
| "Comcast'i ara ve kesintinin tahmini bitiş saatini öğren" mesajını gönderin | Mesaj context olarak POST /v1/call | Ajan arama yapar. Botunuz arama için bir ileti dizisi açar |
| İleti dizisini izleyin | telephony.turn webhook'larını alır | Ajanı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 verin | POST /v1/calls/{call_id}/whisper | Ajan notunuzu özel olarak alır ve buna göre hareket eder. Diğer kişi bunu asla duymaz |
| Ajanın sorusunu yanıtlayın | Araç uç noktanız yanıtınızı döndürür veya daha sonra POST /v1/calls/{call_id}/tool-results ile iletir | Ajan aramaya bununla devam eder; bekletme modunda diğer kişi bu sırada bekletme müziği duyar |
| Sonucu okuyun | telephony.complete alır | Botunuz ö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
contextolur; 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.turniletelephony.completeaboneliğ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 sonusummaryiç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_iddeğerine göre yinelenenleri kaldırın vepositiondeğ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
timeoutsü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.turnteslimi 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/webhookiç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.