SpeechCall შეტყობინებები

SpeechCall არის ინტერაქტიული ხმოვანი პასუხის (IVR) შეტყობინებების ტიპი, რომელიც საშუალებას გაძლევთ განახორციელოთ ავტომატური ხმოვანი ზარები მენიუს ოფციებით და DTMF (ორმაგი ტონი მრავალსიხშირული) ურთიერთქმედებით.

მიმოხილვა

SpeechCall საშუალებას აძლევს ბიზნესს:

• განახორციელეთ ავტომატური ხმოვანი ზარები მომხმარებლებთან
• გაცნობითი აუდიო შეტყობინებების დაკვრა
• წარმოადგინეთ ინტერაქტიული მენიუს პარამეტრები
• DTMF კლავიშების დაჭერის პასუხების მართვა (0-9, *, #)
• განსაზღვრეთ მორგებული ქცევა არასწორი/დროის ამოწურვისთვის
• ჩართეთ ვებჰუქები მორგებული ორგანოებით და სათაურებით, მომხმარებლის არჩევანის საფუძველზე
• მართეთ ზარის ნაკადი დინამიურად (მენიუებს შორის ნავიგაცია)

გამოყენების შემთხვევები

• ** მომხმარებელთა გამოკითხვები ** - შეაგროვეთ გამოხმაურება ტელეფონის მენიუს პარამეტრების საშუალებით
• **შეხვედრის შეხსენებები ** - დაადასტურეთ ან გადადით ხმოვანი ურთიერთქმედებით
• ** შეკვეთის თვალყურის დევნება ** - მიაწოდეთ შეკვეთის სტატუსის განახლებები
• ინტერაქტიული შეტყობინებები - მიაწოდეთ მნიშვნელოვანი ინფორმაცია მოქმედების ვარიანტებით
• ხმოვანი გადამოწმება - მრავალფაქტორიანი ავთენტიფიკაცია ხმოვანი ზარების საშუალებით

მოთხოვნის ფორმატი

ძირითადი სტრუქტურა

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        }
      ]
    }
  ]
}

პარამეტრის აღწერა

პარამეტრი	ტიპი	საჭირო	აღწერა
დან	სიმებიანი	დიახ	გამგზავნის იდენტიფიკატორი (ალფა სახელი ან ID)
მდე	სიმებიანი	დიახ	მიმღების ტელეფონის ნომერი საერთაშორისო ფორმატში
ტექსტი	სიმებიანი	დიახ	ტექსტური მნიშვნელობა, როგორც წესი, “ivr” SpeechCall
ტიპი	სიმებიანი	დიახ	უნდა იყოს "სამეტყველო ზარი"
მენიუ	მასივი	დიახ	მენიუს კონფიგურაციების მასივი ზარისთვის

მენიუს კონფიგურაცია

მენიუს თითოეული ობიექტი შეიცავს:

პარამეტრი	ტიპი	საჭირო	აღწერა
introUrl	სიმებიანი	დიახ	შესავალი აუდიო ფაილის URL ან იდენტიფიკატორი
idleTimeoutMsec	მთელი რიცხვი	არა	დრო ამოიწურა მილიწამებში კლავიშის დაჭერის მოლოდინში (მაგ., 10000). თუ მომხმარებელი არ პასუხობს, შესრულდება არასწორი გასაღების ქვეშ კონფიგურირებული მოქმედებები
dtmfActions	ობიექტი	დიახ	DTMF მოქმედებების გასაღებების რუკა

DTMF მოქმედებები

dtmfActions ობიექტი ასახავს DTMF კლავიშებს ან სპეციალურ პირობებს მოქმედებების მასივებზე:

DTMF გასაღები	აღწერა
d0	დააჭირეთ 0
d1	დააჭირეთ 1
d2	დააჭირეთ 2
…	…
d9	დააჭირეთ 9
d*	დააჭირეთ *
d#	დააჭირეთ #
არასწორი	ტრიგერები არასწორი კლავიშის დაჭერისას ან idleTimeoutMsec მიღწეული შეყვანის გარეშე

თითოეული DTMF გასაღები/პირობა ასახავს მოქმედებების მასივს, რომელიც შესრულდება თანმიმდევრობით.

მხარდაჭერილი მოქმედებები

მოქმედება	პარამეტრები	აღწერა
ვებჰუკი	url (სტრიქონი, საჭირო) body (ობიექტი, სურვილისამებრ) headers (ობიექტი, სურვილისამებრ)	აგზავნის HTTP POST მოთხოვნას JSON ფორმატში მითითებულ URL-ზე. body ობიექტი განლაგდება webhook-ის მოთხოვნაში მოქმედების ველის ქვეშ. მორგებული სათაურები შედის HTTP სათაურებში.
დაკიდება	არცერთი	ამთავრებს ზარს
gotoMenu	მენიუ (სტრიქონი ან მთელი რიცხვი)	გადააქვს ზარი სხვა მენიუში მენიუ მასივში მისი 0-ზე დაფუძნებული ინდექსის გამოყენებით (მაგ., „1“)

დეტალური სამოქმედო ქცევა

ვებჰუკის მოქმედება („ვებჰუკი“)

webhook ქმედება აგზავნის HTTP POST მოთხოვნას თქვენს გამოძახების URL-ზე ზარის მეტამონაცემებით და არასავალდებულო მორგებული მონაცემებით:

• თუ “სხეული” არის მოწოდებული, მისი გასაღები-მნიშვნელობის წყვილი იგზავნება დატვირთვის სხეულის “მოქმედების” ველში.
• თუ მოწოდებულია ჰადერები, ისინი იგზავნება როგორც მორგებული HTTP სათაურები მოთხოვნაში.

Hangup Action (“Hangup”)

გათიშვის მოქმედება დაუყოვნებლივ წყვეტს აქტიურ ზარს. შემდგომი ქმედებები თანმიმდევრობაში ან მენიუში არ დამუშავდება “გათიშვის” მოქმედების შემდეგ.

მენიუს მოქმედებაზე გადასვლა (gotoMenu)

gotoMenu ქმედება გადამისამართებს ზარის ნაკადს მენიუს სხვა სტრუქტურაში, მენიუს მასივში. მას სჭირდება ერთი პარამეტრი მენიუ, რომელიც განსაზღვრავს სამიზნე მენიუს 0-ზე დაფუძნებულ ინდექსს (მაგ., „1“ მეორე მენიუში გადასასვლელად, ან „0“ პირველი მენიუს გადატვირთვისთვის).

---

უმოქმედობა და შეცდომების მართვა (“არასწორი”)

dtmfActions-ში არსებული `არასწორი~ კლავიში არის სპეციალური ვარდნის დამმუშავებელი. იგი ახორციელებს მოქმედებების მასივს ორ სცენარში:

1. არასწორი შეყვანა: აბონენტი აჭერს DTMF კლავიშს, რომელიც არ არის განსაზღვრული dtmfActions (მაგალითად, ისინი აჭერენ 3, მაგრამ მენიუ განსაზღვრავს მხოლოდ d1 და d2).
2. Idle Timeout: აბონენტი არ აჭერს არცერთ კლავიშს idleTimeoutMsec-ით განსაზღვრული ხანგრძლივობის განმავლობაში.

თუ „არასწორი“ არ არის განსაზღვრული და აბონენტი დააჭერს არასწორ კლავიშს ან დრო ამოიწურა, ზარის ნაკადი გაითიშება ნაგულისხმევად. არასწორი-ის განსაზღვრა საშუალებას გაძლევთ შექმნათ მარყუჟის მენიუები (მაგ., იმავე მენიუში დაბრუნება „მოქმედებით“: „gotoMenu“, „მენიუ“: „0“) ან მომხმარებლის გადამისამართება დახმარების მენიუში.

---

Webhook მიწოდების ფორმატი

როდესაც “webhook” მოქმედება ამოქმედდება, სისტემა აგზავნის HTTP POST მოთხოვნას კონფიგურირებულ url-ზე Content-Type: application/json.

Webhook მოთხოვნის სათაურები

თუ მოქმედება კონფიგურირებულია headers პარამეტრით, ეს გასაღები-მნიშვნელობის წყვილი შედის მოთხოვნაში HTTP სათაურების სახით.

Webhook მოთხოვნის ძირითადი ნაწილი

თქვენს webhook URL-ზე გაგზავნილ JSON დატვირთვას აქვს შემდეგი სტრუქტურა:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}

ველი	ტიპი	აღწერა
დან	სიმებიანი	აბონენტის ტელეფონის ნომერი / გამგზავნის ID
მდე	სიმებიანი	მიმღების ტელეფონის ნომერი
`შუა~	სიმებიანი	შეტყობინების ID
მოქმედება	ობიექტი	მორგებული JSON ობიექტი, რომელიც განსაზღვრულია მოქმედების body ველში

სრული მაგალითი

მარტივი IVR დროის ამოწურვით და შეყვანის დადასტურებით

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

კომპლექსური IVR მრავალი მენიუთი და DTMF მარშრუტით

ეს მაგალითი გვიჩვენებს, თუ როგორ უნდა განვსაზღვროთ მრავალი მენიუ და გადაადგილდეთ მათ შორის gotoMenu მოქმედების გამოყენებით, როდესაც მომხმარებელი შეაქვს არასწორი გასაღების ან როდესაც ზარის დრო ამოიწურება. ის ასევე აჩვენებს მორგებულ სხეულებს და მორგებულ HTTP სათაურებს, რომლებიც გაგზავნილია webhook ტრიგერებით.

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        },
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

პასუხის ფორმატი

წარმატებული პასუხი

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380XXXXXXXXX",
      "status": "sent"
    }
  ]
}

შეცდომის დამუშავება

HTTP სტატუსი	აღწერა
200	მოთხოვნა წარმატებით
400	არასწორი მოთხოვნის ფორმატი
401	ავტორიზაცია ვერ მოხერხდა
429	განაკვეთის ლიმიტი გადააჭარბა
500	შიდა სერვერის შეცდომა

cURL მაგალითი

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_XXXXX",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/0",
                  "body": {
                    "confirm": true
                  },
                  "headers": {
                    "test-header": "test"
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/1",
                  "body": {
                    "confirm": false
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "wrong": [
                {
                  "action": "gotoMenu",
                  "menu": "1"
                }
              ]
            }
          },
          {
            "introUrl": "ivr_651854",
            "idleTimeoutMsec": 10000,
            "dtmfActions": {
              "d1": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/0",
                  "body": {
                    "confirm": true
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "d2": [
                {
                  "action": "webhook",
                  "url": "https://YourWebhookURL/1",
                  "body": {
                    "confirm": false
                  }
                },
                {
                  "action": "hangup"
                }
              ],
              "wrong": [
                {
                  "action": "hangup"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

საუკეთესო პრაქტიკა

1. აუდიო ფაილები - დარწმუნდით, რომ შესავალი URL-ები ხელმისაწვდომია და აუდიო ფაილები მხარდაჭერილ ფორმატშია
2. ვებჰუკის საიმედოობა - შექმენით ვებჰუკები სწრაფად რეაგირებისთვის (2 წამში)
3. DTMF ოფციები - მენიუს ოფციების შეზღუდვა 4-6 არჩევანზე უკეთესი მომხმარებლის გამოცდილებისთვის
4. Timeout Handling - გამოიყენეთ idleTimeoutMsec უმოქმედობის მორგებული ლიმიტების დასაზუსტებლად (მაგ. 10000 ms) და მოხდენილი სარეზერვო კონფიგურაციის კონფიგურაცია არასწორი DTMF კლავიშის ქვეშ (როგორიცაა მენიუს გამეორება ან გათიშვა)
5. Multi-Menu Call Flow - გამოიყენეთ gotoMenu ფრთხილად, რათა თავიდან აიცილოთ უსასრულო მარყუჟები მომხმარებლების წინა მენიუში დაბრუნებაში.
6. შებრუნების სტრატეგია - გამოიყენეთ სარეზერვო შეტყობინებები მომხმარებლებისთვის, რომლებიც არ პასუხობენ ან არ წყვეტენ კავშირს

დაკავშირებული თემები

• შეტყობინების გაგზავნა - ზოგადი შეტყობინების გაგზავნის სახელმძღვანელო
• Flash Call - მარტივი ხმოვანი დადასტურების ზარები
• სტატუსის შემოწმება - თვალყური ადევნეთ შეტყობინების მიწოდების სტატუსს
• შეტყობინებების ტიპები - მიმოხილვა ყველა მხარდაჭერილი შეტყობინების ტიპების შესახებ