Gelen aramaları yönetin (API)

Uçtan uca: bir yapay zeka ajanını yapılandırın, bir telefon numarasına atayın, arama alın ve dökümü inceleyin.

Terminalinizden, standart "bir yapay zekanın telefonu yanıtlaması" akışı. Yapacaklarınız:

1. Bir istem ve ses ile ajan oluşturun.
2. Bir telefon numarası sağlayın (veya mevcut numaranızı getirin) ve ajanı bu numaranın gelen arama işleyicisi olarak atayın.
3. Numarayı arayın. Arama günlüğünü, transkripti ve kaydı inceleyin.

Toplam API çağrısı: dört. Toplam süre: beş dakikadan kısa.

1. Ajan oluşturun#

Bir yapay zeka ajanı, aramayı yönlendirecek istemi, sesi ve ürün katmanını bir araya getirir. Yapay zeka ajanında max_call_duration_seconds ve ring_duration_seconds gibi arama sınırlarını da ayarlayabilirsiniz. Ajanlar, yapay zeka ajanı konuşmadan önce önceden kaydedilmiş bir giriş mesajını ve en fazla iki zil sesini çalmak için intro_clip ve intro_ring_count özelliklerini de destekler. Yeni ajanlar için ayrıca bir saat dilimi gerekir. Tüm yapılandırma alanları için Ajanlar bölümüne bakın; minimum gereksinimler şunlardır:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Döndürülen id değerini kaydedin — 2. adımda buna ihtiyacınız olacak.

2. Telefon numarası alın#

Yalnızca arayabileceğiniz bir numaraya ihtiyacınız varsa, ThunderPhone havuzundan bir ThunderPhone numarası alın:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Yanıt, E.164 biçiminde bir id ve number içerir. ThunderPhone numaraları status="provisioning" durumunda başlar ve birkaç saniye içinde active olur — isterseniz geçişi izlemek için GET /v1/phone-numbers/{id} isteğini düzenli olarak sorgulayın.

3. Ajanı atayın#

1. adımdaki ajanı numaranın gelen arama yönüyle ilişkilendirin:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Hepsi bu — numara yayında. Kuruluşunuz için giden arama onaylandıktan sonra, aynı PATCH isteğinde outbound_agent_id değerini de ayarlayabilirsiniz. O zamana kadar API bu atamayı 400 ile reddeder.

Gelen aramaları sabit bir inbound_agent_id yerine bir yapılandırma webhook'u üzerinden yönlendiriyorsanız, bu webhook artık agent_id ve variables ile birlikte her arama için bir timezone döndürebilir.

4. Arama alın#

Telefonunuzdan numarayı arayın. Ajan aramayı yanıtlar, isteminize göre kendini tanıtır ve konuşma başlar.

Arama devam ederken, GET /v1/calls içinde status="in_progress" ile görünür. Arama sona erdiğinde kayıt; end_reason, duration_seconds, billable_minutes ve (zamanla) bir kayıt URL'si ile yapay zeka notuyla güncellenir.

Gelen aramalar, kuruluşunuzun eşzamanlı arama sınırına dahil edilir (varsayılan olarak devam eden 20 arama; giden, web ve test aramalarıyla paylaşılır). Sınıra ulaşıldığında gelen bir arama, yapay zeka ajanı yanıtlamadan önce reddedilir ve kapatılır, ücretlendirilmez ve concurrent_call_limit_reached bitiş nedeni ile başarısız bir arama olarak kaydedilir. Daha yüksek bir sınıra ihtiyacınız varsa support@thunderphone.com adresine e-posta gönderin.

5. Sonuçları inceleyin#

Son aramaların listesini alın:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Transkripti alın:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Ve kayıt URL'sini alın (kısa ömürlü, imzalı):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

telephony.complete webhook'una abone olduysanız aynı verileri sunucunuza POST olarak alırsınız — bkz. call.complete.

Ajanınız için veri çıkarma alanları yapılandırıldıysa, tamamlanan arama yükü yapılandırılmış çıkarılmış verileri de içerebilir.

Sonraki adımlar#