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