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

Paglalarawan ng Parameter

Parameter	Uri	Kinakailangan	Paglalarawan
`mula sa`	string	Oo	Identifier ng nagpadala (alpha name o ID)
`sa`	string	Oo	Numero ng telepono ng tatanggap sa internasyonal na format
`teksto`	string	Oo	Halaga ng teksto, karaniwang "ivr" para sa SpeechCall
`uri`	string	Oo	Dapat ay `"speechcall"`
`menu`	array	Oo	Array ng mga configuration ng menu para sa tawag

Ang bawat bagay sa menu ay naglalaman ng:

Parameter	Uri	Kinakailangan	Paglalarawan
`introUrl`	string	Oo	URL o identifier ng panimulang audio file
`idleTimeoutMsec`	integer	Hindi	Mag-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
`dtmfActions`	bagay	Oo	Mapa 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 Key	Paglalarawan
`d0`	Pindutin ang 0
`d1`	Pindutin ang 1
`d2`	Pindutin ang 2
...	...
`d9`	Pindutin ang 9
`d*`	Pindutin ang *
`d#`	Pindutin ang #
`mali`	Nagti-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

Aksyon	Mga Parameter	Paglalarawan
`webhook`	`url` (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.
`hangup`	Wala	Tinatapos ang tawag
`gotoMenu`	`menu` (string o integer)	Nagna-navigate sa tawag sa isa pang menu sa hanay ng `menu` gamit ang 0-based na index nito (hal., `"1"`)

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

Patlang	Uri	Paglalarawan
`mula sa`	string	Numero ng telepono ng tumatawag / Sender ID
`sa`	string	Numero ng telepono ng tatanggap
`kalagitnaan`	string	ID ng Mensahe
`aksyon`	bagay	Ang custom na JSON object na tinukoy sa field ng `body` ng aksyon

Kumpletong Halimbawa

Simple IVR na may Timeout at Input Validation

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

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

Format ng Tugon

Tagumpay na Tugon

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

Error sa Paghawak

Katayuan ng HTTP	Paglalarawan
200	Matagumpay ang kahilingan
400	Di-wastong format ng kahilingan
401	Nabigo ang pagpapatotoo
429	Lumampas sa limitasyon ng rate
500	Error 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_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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Pinakamahuhusay na Kasanayan

Mga Audio File - Tiyaking naa-access ang mga intro URL at ang mga audio file ay nasa mga sinusuportahang format
Webhook Reliability - Idisenyo ang mga webhook upang mabilis na tumugon (sa loob ng 2 segundo)
DTMF Options - Limitahan ang mga opsyon sa menu sa 4-6 na pagpipilian para sa mas magandang karanasan ng user
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)
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
Fallback Strategy - Gumamit ng mga fallback na mensahe para sa mga user na hindi sumasagot o nagdiskonekta

Mga Kaugnay na Paksa

Send Message - Pangkalahatang gabay sa pagpapadala ng mensahe
Flash Call - Mga simpleng voice verification call
Suriin ang Katayuan - Subaybayan ang katayuan ng paghahatid ng mensahe
Mga Uri ng Mensahe - Pangkalahatang-ideya ng lahat ng sinusuportahang uri ng mensahe