Audio Caller
LINE Planet은 앱 서버가 Planet Cloud로 직접 음성 통화를 요청하도록 해 주는 Audio Caller 기능을 제공합니다. 이 기능을 사용하여 서버 측에서 자동으로 통화를 생성하고, 고객에게 사전 녹음된 메시지가 담긴 오디오 파일을 재생하는 등의 용도로 활용할 수 있습니다.
Audio Caller 기능에서는 사전에 LINE Planet Console을 통해 업로드된 오디오 파일만 사용할 수 있습니다. 자세한 내용은 LINE Planet Console 가이드를 참조하세요.
Audio Caller 기능을 위해 기존 API와 함께 다음 서버 API가 추가로 사용됩니다.
아래 다이어그램은 Audio Caller 기능의 작동 순서를 보여줍니다.
- 앱 서버가 Make Agent 1-to-1 Call API를 사용하여 Planet Cloud에 Audio Caller의 시작을 요청합니다.
- Planet Cloud가 Notify 콜백을 사용하여 앱 서버에 수신 통화를 알립니다.
- 앱 서버가 앱 클라이언트에 푸시 알림을 보냅니다.
- Planet Cloud가 Agent Call Status 콜백을 호출하여 Audio Caller의 상태를 앱 서버에 알립니다.
Make Agent 1-to-1 Call API
앱 서버가 Audio Caller를 시작하도록 합니다.
접근 정보
| 환경 | 기준 URL |
|---|---|
| Evaluation | https://vpnx-stn-api.line-apps-rc.com |
메서드와 엔드포인트
- 메서드: POST
- 엔드포인트
/tas/v2/agt_call/audio_caller/{to-serviceId}/{to-userId}
헤더
- Authorization:
Basic {credentials} - Accept: application/json
- Content-Type: application/json
패스 파라미터
| 파라미터 | 설명 |
|---|---|
to-serviceId | 착신자 서비스의 서비스 ID |
to-userId | 착신자의 사용자 ID |
요청 본문
| 파라미터 | 유형 | 필수 | 제한 | 기본값 | 설명 |
|---|---|---|---|---|---|
requestContext | AgentCallRequestContext 객체 | Y | Audio Caller 요청의 컨텍스트 | ||
mediaSourceType | String | Y | UTF-8 48바이트 | 오디오 소스의 유형
| |
storedSource | StoredAudioSourceInfo 객체 | Y | 미디어 소스 정보 | ||
appSvrData | String | N | UTF-8 4095바이트 | NULL | 앱 서버 데이터 |
callStartMessage | String | N | UTF-8 199바이트 | NULL | 통화 시작 메시지 |
recordOnCloud | Boolean | N | false | 발신자의 클라우드 녹음 설정을 착신자에게 알리기 위해 사용하며,
| |
useResponderPreparation | Boolean | N | false | 응답자 준비 상태를 사용할지 여부 |
AgentCallRequestContext 객체
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
userId | String | Y | 발신자의 사용자 ID |
serviceId | String | Y | 발신자의 서비스 ID |
StoredAudioSourceInfo 객체
| 속성 | 유형 | 필수 | 제한 | 기본값 | 설명 |
|---|---|---|---|---|---|
storedAudioSources | ObjectList | Y | 저장된 오디오 소스의 정보. 재생할 하나 이상의 오디오 소스 정보를 설정할 수 있습니다. 오디오 소스가 여러 개일 경우 순차적으로 재생하며, 최대 5개까지 설정할 수 있습니다. | ||
> | String | Y | 고정 길이 12자 hex 문자열 | LINE Planet Console에 오디오 파일을 업로드할 때 발급되는 오디오 소스 ID | |
playCount | Int | N | 1~3 | 2 | 모든 오디오 소스의 순차 재생을 반복할 횟수 |
playWaitTime | Int | N | 1000~4000 | 1000 | 통화 연결과 미디어 재생 시작 사이의 시간(밀리초) |
응답
| 속성 | 유형 | Null 허용 | 제한 | 설명 |
|---|---|---|---|---|
sid | String | N | 고정 길이 36바이트 | 통화 세션 ID 예: |
예제
curl --location --request POST 'https://vpnx-stn-api.line-apps-rc.com/tas/v2/agt_call/audio_caller/${service-id}/${user-id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ${credentials}' \
--data '{
"requestContext": {
"userId": "${user-id}",
"serviceId": "${service-id}"
},
"mediaSourceType": "STORED_SOURCE",
"storedSource": {
"storedAudioSources": [
{
"contentId": "5498f04048fa"
},
{
"contentId": "c17d343002a9"
}
],
"playWaitTime": 1500,
"playCount": 2
},
"recordOnCloud": false,
"useResponderPreparation": false
}'
{
"status": "success",
"data": {
"sid": "2b53fe1d-5057-4265-ad76-96b2fc6f4961"
},
"timestamp": 1743055021284
}
Agent Call Status 콜백
Agent Call Status 콜백은 에이전트 통화 API 요청에서 성공적인 응답을 받을 때 항상 호출됩니다. 이 콜백은 서버가 착신자에게 통화를 성공적으로 시작했는지(WAITANSWER) 여부를 나타냅니다.
착신자가 전화를 수락하거나 거절하는 등 WAITANSWER 이후의 통화 이벤트에 대해서는 sid 값으로 1대1 통화 이벤트 콜백을 조회하세요.
메서드와 엔드포인트
- 메서드: GET
- 엔드포인트:
${agent_call_status_cb_url}
쿼리 파라미터
| 파라미터 | 유형 | Null 허용 | 설명 | 예시 |
|---|---|---|---|---|
sid | String | N | 세션 ID. sid를 사용하여 통화를 식별할 수 있습니다. Null이 없는 36바이트 고정 길이입니다. | 6364e8b3-bdac-436e-9631-0bce2498ce0c |
agent_type | String | N | 에이전트 유형
| AUDIO_CALLER |
media_source_type | String | N | 에이전트 통화의 미디어 유형
| STORED_SOURCE |
result | String | N | 에이전트 통화의 결과
| SUCCESS |
fail_reason | String | N | 실패 이유(성공 시 None) | Invalid peerId |
예제
# Let's suppose agent_call_status_cb_url is
# http://sample.server.com:20200/audio_caller_event
# LINE Planet server will send a request to agent_call_status_cb_url as follows.
GET http://sample.server.com:20200/audio_caller_event?
sid=6364e8b3-bdac-436e-9631-0bce2498ce0c&
agent_type=AUDIO_CALLER&
media_source_type=STORED_SOURCE&
result=Success&
fail_reason=None