Help Center Tin nhắn SpeechCall

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

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"`)

Hành vi hành động chi tiết

Hành động Webhook (`webhook`)

Hành động webhook gửi yêu cầu HTTP POST tới URL gọi lại của bạn cùng với siêu dữ liệu cuộc gọi và dữ liệu tùy chỉnh tùy chọn:

Nếu một nội dung được cung cấp, các cặp khóa-giá trị của nó sẽ được gửi bên trong trường action của nội dung tải trọng.
Nếu tiêu đề được cung cấp, chúng sẽ được gửi dưới dạng tiêu đề HTTP tùy chỉnh trong yêu cầu.

Hành động gác máy (`gác máy`)

Hành động gác máy sẽ kết thúc cuộc gọi đang hoạt động ngay lập tức. Không có hành động nào khác trong trình tự hoặc menu sẽ được xử lý sau hành động gác máy.

Vào Menu Hành động (`gotoMenu`)

Hành động gotoMenu chuyển hướng luồng lệnh gọi đến một cấu trúc menu khác trong mảng menu. Nó nhận một tham số duy nhất menu chỉ định chỉ mục dựa trên 0 của menu đích (ví dụ: "1" để chuyển đến menu thứ hai hoặc "0" để khởi động lại menu đầu tiên).

Không hoạt động & Xử lý lỗi (`sai`)

Khóa sai bên trong dtmfActions là một trình xử lý dự phòng đặc biệt. Nó thực thi chuỗi hành động của mình theo hai tình huống:

Đầu vào không hợp lệ: Người gọi nhấn phím DTMF không được xác định trong dtmfActions (ví dụ: họ nhấn 3 nhưng menu chỉ xác định d1 và d2).
Idle Timeout: Người gọi không nhấn bất kỳ phím nào trong khoảng thời gian được chỉ định bởi idleTimeoutMsec.

Nếu sai không được xác định và người gọi nhấn phím không hợp lệ hoặc hết thời gian chờ, luồng cuộc gọi sẽ bị treo theo mặc định. Việc xác định sai cho phép bạn xây dựng các menu lặp (ví dụ: quay lại cùng một menu với "action": "gotoMenu", "menu": "0") hoặc chuyển hướng người dùng đến menu trợ giúp.

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

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

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

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

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380XXXXXXXXX",
      "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_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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

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ợ

Search Results

Tin nhắn SpeechCall

Tổng quan

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

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

Mô tả tham số

Cấu hình menu

Hành động DTMF

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

Hành vi hành động chi tiết

Hành động Webhook (`webhook`)

Hành động gác máy (`gác máy`)

Vào Menu Hành động (`gotoMenu`)

Không hoạt động & Xử lý lỗi (`sai`)

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

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

Nội dung yêu cầu Webhook

Ví dụ hoàn chỉnh

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

IVR phức tạp với nhiều menu và định tuyến DTMF

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

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

Xử lý lỗi

cURL Ví dụ

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

Chủ đề liên quan

Search Results

Tin nhắn SpeechCall

Tổng quan

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

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

Mô tả tham số

Cấu hình menu

Hành động DTMF

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

Hành vi hành động chi tiết

Hành động Webhook (webhook)

Hành động gác máy (gác máy)

Vào Menu Hành động (gotoMenu)

Không hoạt động & Xử lý lỗi (sai)

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

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

Nội dung yêu cầu Webhook

Ví dụ hoàn chỉnh

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

IVR phức tạp với nhiều menu và định tuyến DTMF

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

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

Xử lý lỗi

cURL Ví dụ

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

Chủ đề liên quan

Hành động Webhook (`webhook`)

Hành động gác máy (`gác máy`)

Vào Menu Hành động (`gotoMenu`)

Không hoạt động & Xử lý lỗi (`sai`)