Tin nhắn SpeechCall

SpeechCall là loại tin nhắn phản hồi bằng giọng nói tương tác (IVR) cho phép bạn thực hiện các cuộc gọi thoại tự động với các tùy chọn menu và tương tác DTMF (đa tần số hai âm).

Tổng quan

SpeechCall cho phép các doanh nghiệp: - Thực hiện cuộc gọi thoại tự động tới khách hàng - Phát tin nhắn âm thanh giới thiệu - Trình bày các tùy chọn menu tương tác - Xử lý các phản hồi nhấn phím DTMF (0-9, *, #) - Xác định hành vi tùy chỉnh cho đầu vào không hợp lệ/hết thời gian - Kích hoạt webhooks với nội dung và tiêu đề tùy chỉnh dựa trên lựa chọn của người dùng - Quản lý luồng cuộc gọi linh hoạt (điều hướng giữa các menu)

Trường hợp sử dụng

Khảo sát khách hàng - Thu thập phản hồi qua các tùy chọn menu điện thoại
Nhắc nhở cuộc hẹn - Xác nhận hoặc lên lịch lại bằng tương tác bằng giọng nói
Theo dõi đơn hàng - Cung cấp thông tin cập nhật trạng thái đơn hàng
Thông báo tương tác - Cung cấp thông tin quan trọng với các tùy chọn hành động
Xác minh bằng giọng nói - Xác thực đa yếu tố qua cuộc gọi thoại

Định dạng yêu cầu

Cấu trúc cơ bản

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

Mô tả tham số

Tham số	Loại	Bắt buộc	Mô tả
`từ`	chuỗi	Có	Mã định danh người gửi (tên alpha hoặc ID)
`đến`	chuỗi	Có	Số điện thoại người nhận ở định dạng quốc tế
`văn bản`	chuỗi	Có	Giá trị văn bản, thường là "ivr" cho SpeechCall
`loại`	chuỗi	Có	Phải là `"lời nói"`
`thực đơn`	mảng	Có	Mảng cấu hình menu cho cuộc gọi

Mỗi đối tượng menu chứa:

Tham số	Loại	Bắt buộc	Mô tả
`giới thiệu`	chuỗi	Có	URL hoặc mã nhận dạng của tệp âm thanh giới thiệu
`nhàn rỗiTimeoutMsec`	số nguyên	Không	Thời gian chờ tính bằng mili giây để chờ nhấn phím (ví dụ: `10000`). Nếu người dùng không phản hồi, các hành động được định cấu hình dưới phím `sai` sẽ được thực thi
`dtmfActions`	đối tượng	Có	Bản đồ các phím DTMF tới các hành động

Hành động DTMF

Đối tượng dtmfActions ánh xạ các khóa DTMF hoặc các điều kiện đặc biệt vào mảng hành động:

Khóa DTMF	Mô tả
`d0`	Nhấn 0
`d1`	Nhấn 1
`d2`	Nhấn phím 2
...	...
`d9`	Nhấn phím 9
`d*`	Nhấn *
`d#`	Nhấn #
`sai`	Kích hoạt khi nhấn một phím không hợp lệ hoặc khi đạt tới `idleTimeoutMsec` mà không có bất kỳ đầu vào nào

Mỗi khóa/điều kiện DTMF ánh xạ tới một mảng hành động sẽ được thực hiện theo trình tự.

Hành động được hỗ trợ

Hành động	Thông số	Mô tả
`webhook`	`url` (chuỗi, bắt buộc) `body` (đối tượng, tùy chọn) `headers` (đối tượng, tùy chọn)	Gửi yêu cầu HTTP POST ở định dạng JSON tới URL được chỉ định. Đối tượng `body` sẽ được lồng trong trường `action` trong yêu cầu webhook. Tiêu đề tùy chỉnh được bao gồm dưới dạng tiêu đề HTTP.
`cúp máy`	Không có	Kết thúc cuộc gọi
`gotoMenu`	`menu` (chuỗi hoặc số nguyên)	Điều hướng cuộc gọi đến một menu khác trong mảng `menu` bằng cách sử dụng chỉ mục dựa trên 0 của nó (ví dụ: `"1"`)

Định dạng phân phối Webhook

Khi hành động webhook được kích hoạt, hệ thống sẽ gửi yêu cầu HTTP POST đến url đã được định cấu hình với Content-Type: application/json.

Tiêu đề yêu cầu Webhook

Nếu hành động được định cấu hình bằng tham số headers thì các cặp khóa-giá trị đó sẽ được đưa vào dưới dạng tiêu đề HTTP trong yêu cầu.

Nội dung yêu cầu Webhook

Tải trọng JSON được gửi tới URL webhook của bạn có cấu trúc sau:

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

Lĩnh vực	Loại	Mô tả
`từ`	chuỗi	Số điện thoại người gọi / ID người gửi
`đến`	chuỗi	Số điện thoại người nhận
`giữa`	chuỗi	ID tin nhắn
`hành động`	đối tượng	Đối tượng JSON tùy chỉnh được xác định trong trường `body` của hành động

Ví dụ hoàn chỉnh

IVR đơn giản với xác thực thời gian chờ và đầu vào

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

Ví dụ này minh họa cách xác định nhiều menu và điều hướng giữa chúng bằng hành động gotoMenu khi người dùng nhập khóa không hợp lệ hoặc khi cuộc gọi hết thời gian chờ. Nó cũng hiển thị nội dung tùy chỉnh và tiêu đề HTTP tùy chỉnh được gửi bằng trình kích hoạt 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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Định dạng phản hồi

Phản hồi thành công

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

Xử lý lỗi

Trạng thái HTTP	Mô tả
200	Yêu cầu thành công
400	Định dạng yêu cầu không hợp lệ
401	Xác thực không thành công
429	Đã vượt quá giới hạn tỷ lệ
500	Lỗi máy chủ nội bộ

cURL Ví dụ

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

Các phương pháp hay nhất

Tệp âm thanh - Đảm bảo URL giới thiệu có thể truy cập được và tệp âm thanh ở định dạng được hỗ trợ
Độ tin cậy của Webhook - Thiết kế webhook để phản hồi nhanh chóng (trong vòng 2 giây)
Tùy chọn DTMF - Giới hạn tùy chọn menu ở 4-6 lựa chọn để có trải nghiệm người dùng tốt hơn
Xử lý thời gian chờ - Sử dụng idleTimeoutMsec để chỉ định giới hạn không hoạt động tùy chỉnh (ví dụ: 10000 mili giây) và định cấu hình dự phòng duyên dáng dưới phím DTMF sai (như lặp lại menu hoặc gác máy)
Luồng cuộc gọi đa menu - Sử dụng gotoMenu một cách cẩn thận để ngăn chặn các vòng lặp vô hạn khi định tuyến người dùng quay lại các menu trước đó
Chiến lược dự phòng - Sử dụng tin nhắn dự phòng cho những người dùng không trả lời hoặc ngắt kết nối

Chủ đề liên quan

Gửi tin nhắn - Hướng dẫn gửi tin nhắn chung
Flash Call - Cuộc gọi xác minh bằng giọng nói đơn giản
Kiểm tra trạng thái - Theo dõi trạng thái gửi tin nhắn
Loại tin nhắn - Tổng quan về tất cả các loại tin nhắn được hỗ trợ