SpeechCall 메시지
SpeechCall은 메뉴 옵션 및 DTMF(이중 톤 다중 주파수) 상호 작용을 통해 자동 음성 통화를 할 수 있는 대화형 음성 응답(IVR) 메시지 유형입니다.
개요
SpeechCall을 통해 기업은 다음을 수행할 수 있습니다. - 고객에게 자동 음성 통화를 걸 수 있습니다. - 소개 오디오 메시지 재생 - 대화형 메뉴 옵션 제공 - DTMF 키 누르기 응답 처리(0-9, *, #) - 유효하지 않은/시간 초과 입력에 대한 사용자 정의 동작 정의 - 사용자 선택에 따라 사용자 정의 본문 및 헤더로 웹후크를 트리거합니다. - 통화 흐름을 동적으로 관리합니다(메뉴 간 이동).
사용 사례
- 고객 설문조사 - 전화 메뉴 옵션을 통해 피드백 수집
- 약속 알림 - 음성 상호작용으로 확인 또는 일정 변경
- 주문 추적 - 주문 상태 업데이트 제공
- 대화형 알림 - 작업 옵션을 통해 중요한 정보 전달
- 음성인증 - 음성통화를 통한 다단계 인증
요청 형식
기본 구조
{
"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"
}
]
}
}
]
}
]
}
매개변수 설명
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
| '에서' | 문자열 | 예 | 발신자 식별자(알파벳 이름 또는 ID) |
| '에' | 문자열 | 예 | 국제 형식의 수신자 전화번호 |
텍스트 |
문자열 | 예 | SpeechCall의 경우 일반적으로 "ivr"인 텍스트 값 |
| '유형' | 문자열 | 예 | ``음성통화''여야 합니다 |
| '메뉴' | 배열 | 예 | 통화에 대한 메뉴 구성 배열 |
메뉴 구성
각 메뉴 개체에는 다음이 포함됩니다.
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
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(객체, 선택) |
JSON 형식의 HTTP POST 요청을 지정된 URL로 보냅니다. 'body' 개체는 웹훅 요청의 'action' 필드 아래에 중첩됩니다. 사용자 정의 헤더는 HTTP 헤더로 포함됩니다. |
| '전화 끊기' | 없음 | 통화 종료 |
고토메뉴 |
메뉴(문자열 또는 정수) |
0 기반 인덱스(예: "1")를 사용하여 menu 배열의 다른 메뉴에 대한 호출을 탐색합니다 |
웹훅 전달 형식
webhook 작업이 트리거되면 시스템은 Content-Type: application/json을 사용하여 구성된 url에 HTTP POST 요청을 보냅니다.
웹훅 요청 헤더
작업이 headers 매개변수로 구성된 경우 해당 키-값 쌍은 요청에 HTTP 헤더로 포함됩니다.
웹훅 요청 본문
웹훅 URL로 전송된 JSON 페이로드의 구조는 다음과 같습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| '에서' | 문자열 | 발신자 전화번호 / 발신자 ID |
| '에' | 문자열 | 수신자 전화번호 |
| '중간' | 문자열 | 메시지 ID |
| '액션' | 개체 | 작업의 body 필드에 정의된 사용자 정의 JSON 개체 |
완전한 예
시간 초과 및 입력 검증 기능을 갖춘 간단한 IVR
{
"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"
}
]
}
}
]
}
]
}
여러 메뉴와 DTMF 라우팅을 갖춘 복잡한 IVR
이 예에서는 사용자가 잘못된 키를 입력하거나 호출 시간이 초과될 때 gotoMenu 작업을 사용하여 여러 메뉴를 정의하고 메뉴 간을 탐색하는 방법을 보여줍니다. 또한 웹훅 트리거와 함께 전송된 사용자 정의 본문 및 사용자 정의 HTTP 헤더도 표시됩니다.
{
"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"
}
]
}
}
]
}
]
}
응답 형식
성공 응답
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_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"
}
]
}
}
]
}
]
}'
모범 사례
- 오디오 파일 - 소개 URL에 액세스할 수 있고 오디오 파일이 지원되는 형식인지 확인하세요.
- 웹훅 신뢰성 - 신속하게(2초 이내) 응답하도록 웹훅을 설계합니다.
- DTMF 옵션 - 더 나은 사용자 경험을 위해 메뉴 옵션을 4~6개로 제한합니다.
- 시간 초과 처리 - 'idleTimeoutMsec'을 사용하여 사용자 지정 비활성 제한(예: 10000ms)을 지정하고 '잘못된' DTMF 키(예: 메뉴 반복 또는 끊기) 아래에 적절한 대체를 구성합니다.
- 다중 메뉴 통화 흐름 - 사용자를 이전 메뉴로 다시 라우팅할 때 무한 루프를 방지하려면 'gotoMenu'를 주의 깊게 사용하세요.
- 대체 전략 - 응답하지 않거나 연결이 끊기는 사용자에 대해 대체 메시지를 사용합니다.