Help Center SpeechCall Messages

SpeechCall Messages

Ang SpeechCall ay isang interactive na voice response (IVR) na uri ng mensahe na nagbibigay-daan sa iyong gumawa ng mga awtomatikong voice call na may mga opsyon sa menu at DTMF (dual-tone multi-frequency) na mga pakikipag-ugnayan.

Pangkalahatang-ideya

Binibigyang-daan ng SpeechCall ang mga negosyo na:

  • Gumawa ng mga awtomatikong voice call sa mga customer
  • I-play ang mga panimulang audio na mensahe
  • Ipakita ang mga pagpipilian sa interactive na menu
  • Pangasiwaan ang mga tugon ng DTMF keypress (0-9, *, #)
  • Tukuyin ang custom na gawi para sa mga invalid/timeout na input
  • Mag-trigger ng mga webhook na may mga custom na katawan at header batay sa mga pinili ng user
  • Pamahalaan ang daloy ng tawag nang pabago-bago (mag-navigate sa pagitan ng mga menu)

Mga Kaso ng Paggamit

  • Survey ng Customer - Mangolekta ng feedback sa pamamagitan ng mga opsyon sa menu ng telepono
  • Mga Paalala sa Paghirang - Kumpirmahin o muling iiskedyul gamit ang pakikipag-ugnayan ng boses
  • Pagsubaybay sa Order - Magbigay ng mga update sa status ng order
  • Mga Interactive na Notification - Maghatid ng mahalagang impormasyon na may mga opsyon sa pagkilos
  • Voice Verification - Multi-factor na pagpapatotoo sa pamamagitan ng mga voice call

Format ng Kahilingan

Pangunahing Istruktura

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

Paglalarawan ng Parameter

ParameterUriKinakailanganPaglalarawan
mula sastringOoIdentifier ng nagpadala (alpha name o ID)
sastringOoNumero ng telepono ng tatanggap sa internasyonal na format
tekstostringOoHalaga ng teksto, karaniwang “ivr” para sa SpeechCall
uristringOoDapat ay "speechcall"
menuarrayOoArray ng mga configuration ng menu para sa tawag

Configuration ng Menu

Ang bawat bagay sa menu ay naglalaman ng:

ParameterUriKinakailanganPaglalarawan
introUrlstringOoURL o identifier ng panimulang audio file
idleTimeoutMsecintegerHindiMag-timeout sa millisecond upang maghintay ng keypress (hal., 10000). Kung hindi tumugon ang user, ang mga pagkilos na na-configure sa ilalim ng mali na key ay isasagawa
dtmfActionsbagayOoMapa ng DTMF keys to actions

Mga Pagkilos ng DTMF

Ang object na dtmfActions ay nagmamapa ng mga DTMF key o mga espesyal na kundisyon sa mga array ng mga aksyon:

DTMF KeyPaglalarawan
d0Pindutin ang 0
d1Pindutin ang 1
d2Pindutin ang 2
……
d9Pindutin ang 9
d*Pindutin ang *
d#Pindutin ang #
maliNagti-trigger kapag pinindot ang isang di-wastong key o kapag naabot ang idleTimeoutMsec nang walang anumang input

Ang bawat DTMF key/kondisyon ay nagmamapa sa isang hanay ng mga aksyon na isasagawa nang sunud-sunod.

Mga Sinusuportahang Pagkilos

AksyonMga ParameterPaglalarawan
webhookurl (string, kinakailangan)
body (object, opsyonal)
header (object, opsyonal)		Nagpapadala ng HTTP POST na kahilingan sa JSON na format sa tinukoy na URL. Ang object na body ay ilalagay sa ilalim ng field na action sa kahilingan sa webhook. Ang mga custom na header ay kasama bilang mga header ng HTTP.
hangupWalaTinatapos ang tawag
gotoMenumenu (string o integer)Nagna-navigate sa tawag sa isa pang menu sa hanay ng menu gamit ang 0-based na index nito (hal., "1")

Detalyadong Pag-uugali sa Pagkilos

Webhook Action (webhook)

Ang pagkilos na webhook ay nagpapadala ng HTTP POST na kahilingan sa iyong callback URL na may metadata ng tawag at opsyonal na custom na data:

  • Kung may ibinigay na body, ang mga key-value pairs nito ay ipapadala sa loob ng field ng action ng payload body.
  • Kung ibinigay ang mga header, ipapadala ang mga ito bilang mga custom na header ng HTTP sa kahilingan.

Hangup Action (hangup)

Ang pagkilos na hangup ay agad na tinatapos ang aktibong tawag. Wala nang mga karagdagang pagkilos sa pagkakasunud-sunod o mga menu ang ipoproseso pagkatapos ng pagkilos na hangup.

Pumunta sa Menu Action (gotoMenu)

Ang pagkilos na gotoMenu ay nagre-redirect sa daloy ng tawag sa ibang istraktura ng menu sa loob ng hanay ng menu. Kailangan ng isang parameter na menu na tumutukoy sa 0-based na index ng target na menu (hal., "1" upang pumunta sa pangalawang menu, o "0" upang i-restart ang unang menu).

Hindi Aktibidad at Paghawak ng Error (mali)

Ang wrong key sa loob ng dtmfActions ay isang espesyal na fallthrough handler. Isinasagawa nito ang hanay ng pagkakasunud-sunod ng mga pagkilos nito sa dalawang senaryo:

  1. Invalid Input: Pinindot ng tumatawag ang isang DTMF key na hindi tinukoy sa dtmfActions (halimbawa, pinindot nila ang 3 ngunit ang menu ay tumutukoy lamang sa d1 at d2).
  2. Idle Timeout: Hindi pinindot ng tumatawag ang anumang key sa loob ng tagal na tinukoy ng idleTimeoutMsec.

Kung hindi tinukoy ang mali at pinindot ng tumatawag ang isang di-wastong key o nag-time out, ang daloy ng tawag ay ibababa bilang default. Ang pagtukoy sa mali ay nagbibigay-daan sa iyong bumuo ng mga loop na menu (hal. pagbalik sa parehong menu na may "action": "gotoMenu", "menu": "0") o pag-redirect sa user sa isang help menu.

Format ng Paghahatid ng Webhook

Kapag na-trigger ang pagkilos na webhook, magpapadala ang system ng HTTP POST na kahilingan sa naka-configure na url na may Content-Type: application/json.

Mga Header ng Kahilingan sa Webhook

Kung naka-configure ang pagkilos gamit ang parameter na headers, ang mga pares ng key-value na iyon ay isasama bilang mga header ng HTTP sa kahilingan.

Katawan ng Kahilingan sa Webhook

Ang JSON payload na ipinadala sa iyong webhook URL ay may sumusunod na istraktura:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
PatlangUriPaglalarawan
mula sastringNumero ng telepono ng tumatawag / Sender ID
sastringNumero ng telepono ng tatanggap
kalagitnaanstringID ng Mensahe
aksyonbagayAng custom na JSON object na tinukoy sa field ng body ng aksyon

Kumpletong Halimbawa

Simple IVR na may Timeout at Input Validation

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

Complex IVR na may Maramihang Menu at DTMF Routing

Ipinapakita ng halimbawang ito kung paano tumukoy ng maraming menu at mag-navigate sa pagitan ng mga ito gamit ang pagkilos na gotoMenu kapag nag-input ang user ng di-wastong key o kapag nag-time out ang tawag. Nagpapakita rin ito ng mga custom na katawan at custom na HTTP header na ipinadala kasama ng mga trigger ng 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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Format ng Tugon

Tagumpay na Tugon

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

Error sa Paghawak

Katayuan ng HTTPPaglalarawan
200Matagumpay ang kahilingan
400Di-wastong format ng kahilingan
401Nabigo ang pagpapatotoo
429Lumampas sa limitasyon ng rate
500Error sa panloob na server

cURL Halimbawa

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

Pinakamahuhusay na Kasanayan

  1. Mga Audio File - Tiyaking naa-access ang mga intro URL at ang mga audio file ay nasa mga sinusuportahang format
  2. Webhook Reliability - Idisenyo ang mga webhook upang mabilis na tumugon (sa loob ng 2 segundo)
  3. DTMF Options - Limitahan ang mga opsyon sa menu sa 4-6 na pagpipilian para sa mas magandang karanasan ng user
  4. Timeout Handling - Gamitin ang idleTimeoutMsec upang tukuyin ang mga custom na limitasyon sa kawalan ng aktibidad (hal. 10000 ms), at i-configure ang magandang fallback sa ilalim ng wrong DTMF key (tulad ng pag-uulit ng menu o pagbababa)
  5. Multi-Menu Call Flow - Maingat na gamitin ang gotoMenu upang maiwasan ang mga walang katapusang loop kapag niruruta ang mga user pabalik sa mga nakaraang menu
  6. Fallback Strategy - Gumamit ng mga fallback na mensahe para sa mga user na hindi sumasagot o nagdiskonekta

Mga Kaugnay na Paksa