상담사 그룹에 속한 상담원에게 전화 연결을 요청하는 API입니다.
1. API 개요
지정한 상담사 그룹에 속한 상담원들에게 전화 연결 요청을 전송합니다.요청 처리 과정은 다음과 같습니다.
1.
그룹 ID 유효성 검증
2.
그룹에 속한 상담원 목록 조회
3.
PBX 서버로 전화 연결 요청 전송
4.
연결 요청 결과 반환
2. 사전 조건 / 권한
이 API를 사용하기 위해 다음 조건이 필요합니다.
•
콜브릿지(Call Bridge) 계정 생성
•
API Access Token 발급
3. 연관 API
상담사 그룹 조회 API
4. API 정보
Method / Endpoint
5. Header
이름 | 타입 | 필수 | 기본값 | 설명 |
Authorization | string | O | Bearer {ACCESS_TOKEN} 형식으로 전달 | |
Content-Type | string | O | application/json |
6. Request
Request Body
이름 | 타입 | 필수 | 기본값 | 설명 |
ivrIp | String | O | - | 콜브릿지 통화 시스템에서 받은 IVR 서버 IP:Port |
id | String | O | - | 콜브릿지 통화 시스템에서 생성된 통화 고유 ID(UUID) |
groupId | integer | O | - | 상담사 그룹 ID (0 입력 시 전체 상담원 대상) |
cdrId | String | O | - | 통화 CDR ID |
arsNo | String | O | - | ARS 번호 (callee) |
callerNo | String | O | - | 발신자 전화번호 (caller) |
actionId | String | O | - | 콜브릿지 통화 시스템에서 생성된 액션 ID |
ment | String | O | - | 상담원 연결 시 재생할 안내 멘트 |
connectionWaitingTime | String | O | - | 상담원 연결 대기 시간 (초 단위) |
Request Example
cURL
curl -X POST "https://bnd.happytalk.io/api/openapi/calls/request" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ivrIp":"192.168.150.103:29034",
"id":"20240411133800001",
"groupId":123,
"cdrId":"10014473",
"arsNo":"114",
"callerNo":"01012341234",
"actionId":"1.758187055878E9",
"ment":"안녕하세요. 콜브릿지 테스트입니다.",
"connectionWaitingTime":50
}'
JavaScript
복사
7. Response
Response 정보
•
Status Code: 200 OK
•
Content-Type: application/json
Response Body Example
json
{
"code": "OK",
"timestamp": 1735437506000,
"message": "상담원 연결 요청이 완료되었습니다",
"data": {
"siteId": "921004322052",
"cdrId": "10015298",
"counselorCount": 2,
"counselors": [
{
"id": 1499,
"number": "01012345678",
"memberId": 12345,
"siteId": 921004322052
},
{
"id": 1500,
"number": "01012341235",
"memberId": 12346,
"siteId": 921004322052
}
],
"requestedAt": "2025-01-28 15:30:00"
}
}
JavaScript
복사
Resonse Field명
이름 | 타입 | 필수 | 기본값 | 설명 |
code | String | O | - | 응답 코드 |
timestamp | Long | O | - | 응답 일시 (Unix timestamp) |
message | String | X | - | 응답 메시지 |
data | Object | O | - | 상담원 연결 요청 결과 |
data
이름 | 타입 | 필수 | 기본값 | 설명 |
siteId | String | O | - | 사이트 ID |
cdrId | String | O | - | CDR ID |
counselorCount | Integer | O | - | 요청된 상담원 수 |
counselors | Array | O | - | 상담원 목록 |
requestedAt | String | O | - | 요청 시각 |
counselors (CounselorInfo)
이름 | 타입 | 필수 | 기본값 | 설명 |
id | Long | O | - | 상담원 ID |
number | String | O | - | 상담원 전화번호 |
memberId | Long | O | - | 상담원 멤버 ID |
siteId | Long | O | - | 사이트 ID |
8. 에러 / 예외처리
오류 응답 본문의 “code"와 "message" 속성에서 오류에 대한 더 구체적인 세부 정보를 확인할 수 있습니다.
HTTP 상태명 | Error Code | Message | 설명 |
400 Bad Request | BAD_REQUEST | CDR ID 형식이 올바르지 않습니다 | CDR ID 형식 오류 |
400 Bad Request | BAD_REQUEST | 이미 종료된 통화입니다 | 종료된 통화에 대한 요청 |
401 Unauthorized | UNAUTHORIZED | Invalid credentials | API Key 미전송 또는 인증 실패 |
404 Not Found | NOT_FOUND | CDR을 찾을 수 없습니다 | 존재하지 않는 CDR |
404 Not Found | NOT_FOUND | 그룹을 찾을 수 없습니다 | 존재하지 않는 그룹 ID |
404 Not Found | NOT_FOUND | 그룹에 등록된 상담원이 없습니다 | 그룹에 상담원이 없는 경우 |
500 Internal Server Error | INTERNAL_SERVER_ERROR | PBX 서버 통신에 실패했습니다 | 콜브릿지 통화시스템 서버 연결 또는 통신 오류 |