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

Developer cookbook

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

Ajanı değiştirmeden, her çağrıya istem için adlandırılmış değişkenler veya serbest biçimli bir özet olarak kendi ayrıntılarını verin.

Her çağrı, çağrı başına iki tür girdi taşıyabilir. Bunlardan birini veya ikisini birlikte kullanın:

  • variables: istemdeki {{placeholders}} yer tutucularını dolduran adlandırılmış değerlerdir. Arayanın adı, hesap numarası veya randevu zamanı gibi istemin adıyla başvurduğu alanlar için kullanın.
  • context: istemden sonra eklenen serbest biçimli metindir. Bu çağrıdaki görevin açıklaması veya daha önce toplanmış notlar gibi bir şablona uymayan kısa bilgiler için kullanın.

Her ikisi de aşağıda açıklanan çağrı başlatma yöntemlerinin tümünde, kaydedilmiş bir yapay zeka ajanı ve satır içi yapılandırmayla çalışır. Hiçbiri kaydedilmiş yapay zeka ajanını, sürüm geçmişini veya diğer ayarlarını değiştirmez.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

Değişkenler

Kaydedilmiş yapay zeka ajanınızın istemine yer tutucular ekleyin, ardından bir çağrı başlatırken variables nesnesini sağlayın. ThunderPhone, çağrı yapılandırmasını ses çalışma zamanına göndermeden önce metni oluşturur.

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 ve sınırlar

Değerler dizeler, sayılar, boole değerleri 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; sıfır genişlikli birleştirici olmayan ve birleştirici karakterler (Hint ve Arap alfabesi kullanan dillerde sözcükleri oluşturan U+200C, U+200D) dışındaki biçim (Cf) karakterleri; ve vekil (Cs) kod noktaları kaldırılır; \r\n, \n olarak normalleştirilir. Her değer işlendiğinde 2.000 karakterle sınırlıdır. Sağlanan dizeler depolanmadan önce de temizlenir ve kısaltılır. Özgün nesne UTF-8 JSON olarak 32 KB içine sığmalıdır; daha büyük nesneler çağrı/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 döndürülür, ancak bir yer tutucuyla başvurulamaz.

Bağlam

context, en fazla 20.000 karakter içeren bir dizedir. ThunderPhone, istemin değişkenleri doldurulduktan sonra bunu sınırlayıcılarla ayrılmış bir blok olarak istemden sonra ekler:

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

Ajan bunu talimatlarıyla birlikte okur; bu nedenle çağrı öncesinde bir çalışma arkadaşınıza bilgi verir gibi yazın. Bağlam bir şablon değildir: İçindeki {{name}} yazıldığı şekilde kalır. Metnin bir değere ihtiyacı varsa, göndermeden önce değeri kendiniz ekleyin.

  • null, boş bir dize veya yalnızca boşluk karakterleri bağlam olmadığı anlamına gelir.
  • Dize olmayan ya da 20.000 karakterden uzun bir değer, arama ve oturum isteklerinde 400 ile reddedilir; yapılandırma webhook'undan gönderildiğinde ise geçersiz variables gibi değişimi başarısız kılar (aşağıya bakın).
  • Baştaki ve sondaki boşluk karakterleri kırpılır ve değişken değerlerinde olduğu gibi aynı denetim ve biçim karakterleri kaldırılır.
  • Bağlam, aramanın isteminin bir parçasıdır; bu nedenle aramanın istem boyutuna dahil edilir.

Adımlar kullanan bir ajanda bağlam, her adımın talimatlarını değil, çağrıdaki her ajanın istemini takip eder.

Değerlerin kaynakları

Giden API

POST /v1/call üzerinde variables ve context gönderin:

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

Her ikisi de telefon numarasının varsayılan giden arama ajanıyla veya satır içi bir config.prompt ile çalışır. Satır içi yapılandırmada context, yapılandırma webhook'unun döndürdüğü alanla aynı olan config içine de yerleştirilebilir; ikisini de gönderirseniz aynı metin olmalıdır. Bir idempotency anahtarı farklı değişkenlerle veya farklı bir bağlamla yeniden kullanılamaz.

Kampanya CSV'si

Telefon dışı 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. Kampanya kişilerinin kişi başına bağlamı yoktur.

Dinamik yapılandırma webhook'u

Engelleyici yapılandırma webhook yolunda, kuruluşunuzda kayıtlı bir ajanı ve çağrı başına değerleri döndürün. Tam çift yönlü bir ajan için, çağrı desteklenen başka bir dilde başlasa bile çağrı ajanın sesini korur: dil başına ses eşlemeleri ve yerel ses değiştirme bu çağrıya uygulanmaz.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

Yanıttaki değişkenler 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. Kaydedilmiş ajan yanıtları yalnızca agent_id, variables, context, language ve çağrı başına timezone kabul eder; istemi veya diğer ayarları değiştirmeniz gerektiğinde satır içi yapılandırma döndürün. Kaydedilmiş ajan webhook yanıtları, hem telefon hem de widget çağrılarında ajanın yayına alınmış A/B dağılımını kullanır; değişkenler, varyant seçildikten sonra oluşturulur. Yanıt, tam çift yönlü olmayan bir ajan için language ayarladığında, ajan için o dilde bir ses ayarlanmışsa çağrı o dilin kendi sesini de kullanır. prompt içeren bir yanıt her zaman satır içi yapılandırma kullanır: bu yanıttaki tüm agent_id değerleri, null veya tam sayı 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 ve context de içerebilir. Dize olmayan veya fazla uzun bir context, işlemi başarısız kılar: telefon çağrısı reddedilir ve widget oturumu isteği 400 ile başarısız olur. Kaydedilmiş ajan webhook yanıtları, hem telefon hem de widget çağrılarında ajanın yayına alınmış A/B dağılımını kullanır; değişkenler, varyant seçildikten sonra oluşturulur. Gelen telefon çağrılarında, atanmış bir gelen arama ajanı olmayan bir numara kullanın ve numaranın veya kuruluşun webhook'unu yapılandırın; widget anahtarları mode="webhook" kullanır. Uç nokta sistemi üzerinden gelen bildirimler engelleyici yapılandırma yanıtları sağlamaz.

Yapay zeka ajanı çağrı kurulum webhook'u

Bir numarayı yapay zeka ajanına atılı tutmak ve yalnızca çağrıya ait değerleri doldurmak için ajana bir çağrı kurulum webhook'u verin. Bir yapay zeka ajanı bir numarada her gelen çağrıyı yanıtlamadan önce, webhook çağrıyı ve ajanın kimliğini, adını ve sürümünü alır; ardından agent_id gerektirmeden yukarıdakiyle aynı variables, context, language ve çağrı başına timezone değerleriyle yanıt verir. Ayarlarında varsayılanı olmayan bir yer tutucu kullanan yapay zeka ajanının bir telefon numarasını yanıtlayabilmesi için bu webhook gerekir: webhook başarısız olursa çağrı başlamaz. {{name|there}} gibi varsayılanı olan yer tutucular, yapay zeka ajanının webhook olmadan çağrıyı yanıtlamasını sağlar.

SIP başlıkları

Bir ajana SIP üzerinden ulaşan çağrılar (bir SIP adresi veya manuel SIP bağlantısındaki bir numara) X-* ve User-to-User başlıklarında bağlam taşıyabilir. Her biri, örneğin {{sip_x_amzn_connectcontactid}} veya {{sip_uui}} gibi, en düşük önceliğe sahip bir sip_ değişkenine dönüşür: API veya webhook'tan gelen aynı adlı bir değer önceliklidir. Bkz. SIP başlıklarında çağrı bağlamı iletme. Başlık değerleri gönderici tarafından ayarlanır; bu nedenle tarayıcı tarafından sağlanan herhangi bir değer gibi güvenilmez kabul edin.

Widget oturum API'si

POST /v1/widget/session, üst düzey variables ve language değerlerini kabul eder. Yayınlanabilir anahtarı, kaydedilmiş ajanı seçer. Webhook modundaki 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 variables değerleri istemci tarafından kontrol edilir, yukarıda açıklanan doğrulama ve dize temizleme işlemlerinden sonra web.incoming içinde aynen iletilir ve tamamlama webhook'larına ve çağrı geçmişine yansıtılır. Bunları güvenilir kimlik veya yetkilendirme verileri olarak değerlendirmeyin.

Widget'ın kendi tarayıcı context alanı farklıdır: ziyaretçinin bulunduğu sayfadaki metni taşır ve ajan bunu web sitesi içeriği olarak ele alır (Web widget'ını yerleştirme bölümüne bakın). Bir widget çağrısının çağrı başına bağlamı, yukarıda açıklandığı gibi webhook modu anahtarının yapılandırma webhook'undan gelir. Bir çağrıda her ikisi de varsa önce çağrı başına bağlam, ardından sayfa içeriği gelir.

Gerçek zamanlı oturum API'si

POST /v1/realtime/sessions, agent_id veya satır içi config ile birlikte üst düzey variables, context ve language alanlarını kabul eder:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context yalnızca üst düzeyde yer alır; satır içi bir config bunu bilinmeyen bir alan olarak reddeder.

Gerçek zamanlı WebSocket

Kaydedilmiş bir ajanla, kaydedilmiş ajanın yayına alınmış istemi kendi istemi olarak kalır. session.instructions çağrının bağlamı olur, session.prompt.variables (veya session.config.variables) değişkenleri olur ve session.language çağrı başına dili olur. İlk session.update içinde ajanı session.prompt.id ile seçin; bu güncelleme ulaştığında oturum başlar:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

Bağlantı URL'sindeki ?agent_id=12, soket bağlanır bağlanmaz, herhangi bir session.update öncesinde yapay zeka ajanını başlatır; bu nedenle çağrı başına girdi taşımaz. İlk session.update için beklemek ve onun yönergelerini ve değişkenlerini kullanmak üzere &wait_for_session_update=1 ekleyin.

Satır içi bir oturumda (kaydedilmiş ajan yoksa) session.instructions, eskiden olduğu gibi istemin kendisidir. Tarayıcı test aramaları ve simülasyonlar, varsayılanları ve eksik yer tutucuları çözümler. Değerlerle test etmek için ajana bir arama kurulumu örneği kaydedin ve testi başlatırken bu örneği seçin; arama, arama kurulumu web kancanız bu örnekle yanıt vermiş gibi çalışır.

Aramadan sonra

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

Aramanın prompt_snapshot öğesi (GET /v1/calls/{call_id}), yapay zeka ajanının değişkenleri doldurulmuş ve bağlam bloğu eklenmiş istemini gösterir.

Tamamlanan aramayı kaynak kaydına bağlamak için CRM veya görev tanımlayıcınızı değişkenler nesnesinde saklayın. Değişkenler ve bağlam, arama kaydıyla birlikte saklanır; yalnızca arama geçmişinde ve web kancalarında saklanması uygun olan bilgileri gönderin.

Bir aramanın doğrulama kümelerindeki, yeniden oynatma çalıştırmalarındaki ve incelemelerdeki yeniden oynatmaları, test edilen istemle birlikte o aramanın değişkenlerini ve bağlamını kullanır. Böylece bir yeniden oynatma, o aramadaki yapay zeka ajanına ne söylenmiş olacağını test eder.

Mevcut istemlerle uyumluluk

İşleme, mevcut kaydedilmiş yapay zeka ajanı ve A/B varyant istemlerine, satır içi giden arama ve gerçek zamanlı yapılandırmalara ve yapılandırma web kancalarının döndürdüğü istemlere de uygulanır. Bilinmeyen {{name}} yer tutucuları, variables sağlanmasa bile boş metne dönüşür. ThunderPhone'un envanterini çıkaramadığı, harici olarak sağlanan satır içi/web kancası istemleri dahil olmak üzere, yayına alma öncesinde mevcut istemleri kontrol edin. Kaydedilmiş bir arama kurulumu örneği seçmediğiniz sürece tarayıcı test aramaları ve simülasyonlar da aynı varsayılan/boş davranışı uygular.