Developer cookbook

Çağrı başına değişkenler

Yayındaki istemini, araçlarını veya ayarlarını değiştirmeden kaydedilmiş bir yapay zeka ajanını her çağrı için kişiselleştirin.

Kaydedilmiş ajanınızın istemine yer tutucular ekleyin, ardından bir arama başlatırken bir variables nesnesi sağlayın. Kaydedilmiş yapılandırma ve sürüm geçmişi değişmeden kalır. ThunderPhone, arama yapılandırmasını ses çalışma zamanına göndermeden önce metni işler.

Değer gerekmediğinde variables öğesini atlayın, null göndermeyin (400 ile reddedilir).

Yer tutucular ve varsayılanlar#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Adlar büyük/küçük harfe duyarlıdır ve [A-Za-z_][A-Za-z0-9_]* biçimini izler. Adın çevresindeki boşluklara izin verilir; | sonrasındaki boşluk varsayılanın parçasıdır ve korunur. {{name|Friend}}, name eksik veya null olduğunda Friend değerini kullanır; boş dize açıkça sağlanmış bir değerdir. Varsayılanı olmayan eksik değerler boş dizelere dönüşür ve adları unresolved_variables içinde görünür. Geçerli bir yer tutucu olmayan çift küme parantezler arasındaki metin kaldırılır. Sağlanan her değerin içindeki çift küme parantezli metin bağımsız olarak kaldırılır; bir değer çevresindeki istem metnini veya başka bir değeri kaldıramaz. Eşleşmeyen çift küme parantez ayraçları da kaldırılır. İstemlerdeki JSON örnekleri {{ kullanmamalıdır. Değerler düz metindir; hiçbir zaman kod olarak değerlendirilmez veya şablon olarak özyinelemeli biçimde genişletilmez.

Değişkenler ayrıca onay istemlerinde, giden sesli posta mesajlarında ve telefon araması için bu alan gönderildiğinde onay duyurusu metninde görünebilir. Ajanın ayrı bir first_message alanı yoktur: açılış talimatlarını isteme ekleyin. Mevcut sesli posta {agent_name} ve {org_name} yer tutucuları çalışmaya devam eder.

Değerler dize, sayı, boole veya null olabilir; boole değerleri true ve false olarak işlenir. Yeni satır (\n), sekme (\t) ve satır başı (\r) dışındaki Unicode denetim (Cc) karakterleri, tüm biçim (Cf) karakterleri ve vekil (Cs) kod noktaları kaldırılır; \r\n, \n olarak normalleştirilir. İşlendiğinde her değer 2.000 karakterle sınırlıdır. Sağlanan dizeler depolamadan önce de temizlenir ve kesilir. Özgün nesne 32 KB UTF-8 JSON sınırına uymalıdır; daha büyük nesneler arama/oturum isteklerinde 400 alırken, kampanya içe aktarımları geçersiz satırları ayrı ayrı bildirir. Diziler ve iç içe nesneler değer olarak kabul edilmez. Eşleşmeyen meta veri anahtarları (örneğin boşluk içeren bir CSV başlığı) korunur ve geri yansıtılır, ancak bir yer tutucu tarafından başvurulamaz.

Değerlerin kaynakları#

Giden API#

POST /v1/call üzerinde agent_id ile birlikte variables gönderin:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Bu, telefon numarasının varsayılan giden ajanıyla veya satır içi config.prompt ile de çalışır. Bir idempotency anahtarı farklı değişkenlerle yeniden kullanılamaz.

Kampanya CSV'si#

Telefon numarası dışındaki CSV sütunları zaten kişi değişkenleri olarak saklanır. Her arama artık bunları otomatik olarak kullanır. Yer tutucularınızla eşleştirmek için name, account_id ve appointment_slot gibi başlıklar kullanın. Mevcut ad eşlemesi, ad ve soyadı sütunlarını name değişkeninde birleştirebilir.

Dinamik yapılandırma webhook'u#

Engelleyici yapılandırma webhook yolunda, kuruluşunuzdaki kayıtlı bir ajanı ve arama başına değerleri döndürün:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Yanıtın anahtarları istek düzeyindeki değişkenlerin üzerine yazılırken diğer istek anahtarları korunur. null yanıt değeri, yer tutucunun varsayılanını seçer. Birleştirilmiş nesne de 32 KB sınırına uymalıdır. Kayıtlı ajan yanıtları yalnızca agent_id ve variables kabul eder; istemi veya ayarları değiştirmeniz gerektiğinde satır içi yapılandırma döndürün. prompt içeren bir yanıt her zaman satır içi yapılandırmayı kullanır: bu yanıttaki tüm agent_id değerleri, null veya tamsayı olmayan meta veriler dahil olmak üzere yok sayılır. Satır içi istem yine de normal doğrulamadan geçmelidir. Satır içi webhook yanıtları variables da içerebilir. Kayıtlı ajan webhook yanıtları, hem telefon hem de widget aramalarında ajanın yayındaki A/B dağılımını kullanır; değişkenler varyant seçildikten sonra işlenir. Gelen telefon aramalarında, atanmış gelen ajanı olmayan bir numara kullanın ve telefon numarasının veya kuruluşun webhook'unu yapılandırın; widget anahtarları mode="webhook" kullanır. Uç nokta sistemi gelen bildirimleri, engelleyici yapılandırma yanıtları sağlamaz.

Widget ve Realtime oturum API'leri#

POST /v1/widget/session, üst düzey bir variables nesnesini kabul eder. Yayınlanabilir anahtarı kayıtlı ajanı seçer. Webhook modu anahtarları bu değerleri yapılandırma webhook'una iletir ve yanıtı yukarıda açıklandığı şekilde birleştirir. Tarayıcı tarafından sağlanan widget/realtime variables istemci tarafından kontrol edilir, yukarıda açıklanan doğrulama ve dize temizliğinin ardından olduğu gibi web.incoming içinde iletilir ve tamamlama webhook'larına ve arama geçmişine yansıtılır. Bunları güvenilir kimlik veya yetkilendirme verisi olarak değerlendirmeyin.

POST /v1/realtime/sessions, agent_id (veya satır içi config) ile birlikte variables kabul eder. Bunlar oturum oluşturma API alanlarıdır. Realtime WebSocket köprüsü değişken seçeneğini iletmez; bunu doğrudan oturum oluşturma API'sine sağlayın. Widget istemcileri, gönderilen oturum yükünde variables içermelidir; SDK iletimi bu API değişikliğinin parçası değildir. Builder mikrofonu ve simüle edilmiş test aramaları varsayılanları ve eksik yer tutucuları çözümler, ancak arama başına değişken girdisi yoktur.

Aramadan sonra döndürülen değerler#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete ve web.complete, nihai birleştirilmiş variables ve unresolved_variables değerlerini içerir. data.history içeren eski tamamlama yükleri de bunları içerir:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Tamamlanan aramayı kaynak kaydına yeniden bağlamak için CRM veya görev tanımlayıcınızı değişkenler nesnesinde saklayın. Bu alanlar arama kaydıyla birlikte tutulur; yalnızca arama geçmişinde ve webhook'larda tutulması uygun bilgileri gönderin.

Mevcut istemlerle uyumluluk#

İşleme; mevcut kaydedilmiş ajan ve A/B varyantı istemlerine, satır içi giden ve gerçek zamanlı yapılandırmalara ve yapılandırma web kancaları tarafından döndürülen istemlere de uygulanır. Bilinmeyen {{name}} yer tutucuları, variables sağlanmasa bile boş metne dönüşür. ThunderPhone'un envanterleyemediği, harici olarak sağlanan satır içi/web kancası istemleri dahil olmak üzere mevcut istemleri yayına almadan önce kontrol edin. Builder mikrofonu ve simülasyon aramaları aynı varsayılan/boş davranışı uygular.