Konuşma Çağrısı Mesajları
SpeechCall, menü seçenekleri ve DTMF (çift tonlu çoklu frekans) etkileşimleriyle otomatik sesli aramalar yapmanızı sağlayan etkileşimli bir sesli yanıt (IVR) mesaj türüdür.
Genel Bakış
SpeechCall işletmelerin şunları yapmasını sağlar: - Müşterilere otomatik sesli aramalar yapın - Tanıtıcı sesli mesajları oynatın - Etkileşimli menü seçeneklerini sunun - DTMF tuşa basma yanıtlarını yönetin (0-9, *, #) - Geçersiz/zaman aşımı girişleri için özel davranış tanımlayın - Kullanıcı seçimlerine göre özel gövdeler ve başlıklarla web kancalarını tetikleyin - Çağrı akışını dinamik olarak yönetin (menüler arasında gezinin)
Kullanım Durumları
- Müşteri Anketleri - Telefon menü seçenekleri aracılığıyla geri bildirim toplayın
- Randevu Hatırlatıcıları - Sesli etkileşimle onaylayın veya yeniden planlayın
- Sipariş Takibi - Sipariş durumu güncellemeleri sağlayın
- Etkileşimli Bildirimler - Önemli bilgileri eylem seçenekleriyle iletin
- Sesli Doğrulama - Sesli aramalarla çok faktörlü kimlik doğrulama
Talep Formatı
Temel Yapı
{
"messages": [
{
"from": "BazarCOM",
"to": "+380936670003",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option1",
"body": {
"confirm": true
},
"headers": {
"X-Custom-Header": "value"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option2",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Parametre Açıklama
| Parametre | Tür | Gerekli | Açıklama |
|---|---|---|---|
| 'dan' | dize | Evet | Gönderenin tanımlayıcısı (alfa adı veya kimliği) |
| 'e' | dize | Evet | Uluslararası formatta alıcının telefon numarası |
| 'metin' | dize | Evet | Metin değeri, SpeechCall için genellikle "ivr" |
| 'tür' | dize | Evet | `"konuşma çağrısı" olmalıdır |
| 'menü' | dizi | Evet | Aramaya ilişkin menü yapılandırmaları dizisi |
Menü Yapılandırması
Her menü nesnesi şunları içerir:
| Parametre | Tür | Gerekli | Açıklama |
|---|---|---|---|
| 'introUrl' | dize | Evet | Giriş ses dosyasının URL'si veya tanımlayıcısı |
| 'idleTimeoutMsec' | tamsayı | Hayır | Bir tuşa basılmasının beklenmesi için milisaniye cinsinden zaman aşımı (ör. "10000"). Kullanıcı yanıt vermezse "yanlış" anahtarı altında yapılandırılan eylemler yürütülür |
| 'dtmfActions' | nesne | Evet | Eylemlerin DTMF anahtarlarının haritası |
DTMF Eylemleri
'dtmfActions' nesnesi DTMF anahtarlarını veya özel koşulları eylem dizileriyle eşler:
| DTMF Anahtarı | Açıklama |
|---|---|
| 'd0' | 0 |
| 'd1' | 1'e basın |
| 'd2' | 2 |
| ... | ... |
| 'd9' | 9 |
| 'd*' | * |
| 'd#' | # |
| 'yanlış' | Geçersiz bir tuşa basıldığında veya herhangi bir giriş olmadan "idleTimeoutMsec"e ulaşıldığında tetiklenir |
Her DTMF anahtarı/koşulu, sırayla yürütülecek bir dizi eylemle eşleşir.
Desteklenen Eylemler
| Eylem | Parametreler | Açıklama |
|---|---|---|
| 'web kancası' | 'url' (dize, gerekli) 'body' (nesne, isteğe bağlı) 'başlıklar' (nesne, isteğe bağlı) |
Belirtilen URL'ye JSON biçiminde bir HTTP POST isteği gönderir. 'Body' nesnesi, webhook isteğindeki 'action' alanının altına yerleştirilecektir. Özel başlıklar HTTP üstbilgileri olarak dahil edilir. |
| 'kapat' | Yok | Aramayı sonlandırır |
| 'menüye git' | 'menü' (dize veya tamsayı) | 0 tabanlı dizinini kullanarak çağrıyı 'menü' dizisindeki başka bir menüye yönlendirir (örneğin, '"1"`) |
Web Kancası Teslim Formatı
'Webhook' eylemi tetiklendiğinde sistem, 'Content-Type: application/json' ile yapılandırılmış 'url'ye bir HTTP POST isteği gönderir.
Web Kancası İsteği Başlıkları
Eylem "headers" parametresiyle yapılandırılmışsa bu anahtar/değer çiftleri isteğe HTTP üstbilgileri olarak dahil edilir.
Web Kancası İsteği Gövdesi
Webhook URL'nize gönderilen JSON verisi aşağıdaki yapıya sahiptir:
| Alan | Tür | Açıklama |
|---|---|---|
| 'dan' | dize | Arayanın telefon numarası / Gönderenin Kimliği |
| 'e' | dize | Alıcının telefon numarası |
| 'orta' | dize | Mesaj Kimliği |
| 'eylem' | nesne | Eylemin "body" alanında tanımlanan özel JSON nesnesi |
Tam Örnek
Zaman Aşımı ve Giriş Doğrulama ile Basit IVR
{
"messages": [
{
"from": "BazarCOM",
"to": "+380936670003",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option1",
"body": {
"confirm": true
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option2",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Çoklu Menü ve DTMF Yönlendirmeli Karmaşık IVR
Bu örnek, kullanıcı geçersiz bir anahtar girdiğinde veya çağrı zaman aşımına uğradığında birden fazla menünün nasıl tanımlanacağını ve "gotoMenu" eylemini kullanarak bunlar arasında nasıl gezinileceğini gösterir. Ayrıca webhook tetikleyicileriyle gönderilen özel gövdeleri ve özel HTTP üstbilgilerini de gösterir.
{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"d2": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Yanıt Formatı
Başarılı Yanıt
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"status": "sent"
}
]
}
Hata İşleme
| HTTP Durumu | Açıklama |
|---|---|
| 200 | İstek başarılı |
| 400 | Geçersiz istek biçimi |
| 401 | Kimlik doğrulama başarısız oldu |
| 429 | Oran sınırı aşıldı |
| 500 | Dahili sunucu hatası |
cURL Örneği
curl -X POST https://restapi.smsbat.com/bat/messagelist \
-u "username:password" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"d2": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}'
En İyi Uygulamalar
- Ses Dosyaları - Giriş URL'lerinin erişilebilir olduğundan ve ses dosyalarının desteklenen formatlarda olduğundan emin olun
- Web Kancası Güvenilirliği - Web kancalarını hızlı yanıt verecek şekilde tasarlayın (2 saniye içinde)
- DTMF Seçenekleri - Daha iyi kullanıcı deneyimi için menü seçeneklerini 4-6 seçenekle sınırlandırın
- Zaman Aşımı İşleme - Özel hareketsizlik sınırlarını (ör. 10.000 ms) belirtmek için "idleTimeoutMsec" seçeneğini kullanın ve "yanlış" DTMF anahtarı altında (menüyü tekrarlamak veya telefonu kapatmak gibi) zarif bir geri dönüş yapılandırmak
- Çoklu Menü Çağrı Akışı - Kullanıcıları önceki menülere yönlendirirken sonsuz döngüleri önlemek için `gotoMenu'yu dikkatli kullanın
- Geri Dönüş Stratejisi - Yanıt vermeyen veya bağlantıyı kesmeyen kullanıcılar için yedek mesajları kullanın
İlgili Konular
- Mesaj Gönder - Genel mesaj gönderme kılavuzu
- Flaş Arama - Basit sesli doğrulama aramaları
- Durumu Kontrol Et - Mesaj teslim durumunu takip et
- Mesaj Türleri - Desteklenen tüm mesaj türlerine genel bakış