개발자를 위한 Call API와 웹훅: 키, 스코프, 이벤트
Call REST API 실무 안내입니다. API 키와 스코프, 요청 한도, 오류 처리, 서명된 웹훅, 엔드포인트를 관리하는 개발자 페이지를 다룹니다.
전화 시스템은 언젠가 다른 시스템과 연결되어야 합니다. 통화가 끝나는 즉시 표시해야 하는 CRM, 누가 전화했는지 알고 싶은 청구 도구, 양식이 제출되면 전화를 거는 스크립트 등입니다. Call에는 바로 이런 용도의 REST API와 아웃바운드 웹훅이 있습니다. 이 가이드에서는 구성 요소가 어떻게 맞물리는지, 코드를 쓰기 전에 무엇을 요청해야 하는지, 개발자의 오후를 가장 자주 날려 버리는 실수를 설명합니다.

연락처를 대량으로 옮기는 것이 목적이라면 먼저 전화 응대 팀 CRM에 연락처 가져오기를 읽어 보십시오. 연동보다 가져오기가 더 쉬운 경우가 많습니다.
시작점: 레퍼런스와 개발자 페이지
알아 둘 곳은 두 군데입니다. API 레퍼런스는 설정 아래에 있으며, 홈페이지의 리소스 메뉴에도 있습니다. 로그인 없이 읽을 수 있어 고객사 작업 범위를 정할 때 편리합니다. 개발자 페이지도 설정 아래에 있으며 내 워크스페이스 전용입니다. 조직 ID와 에이전트 ID, 웹훅 엔드포인트, 읽기 전용 키 목록이 표시됩니다.
각 위치에서 얻을 수 있는 것
- 시작하기기본 URL과 규칙, 스코프 표가 포함된 인증, 상태 코드별 오류.
- 엔드포인트엔드포인트 카드마다 스코프, 파라미터, 요청 본문, 응답, 오류가 나열되고, curl, JavaScript, Python으로 바로 복사할 수 있는 요청 예시가 있습니다.
- 검색/를 누르면 엔드포인트 검색으로 이동해 메서드, 경로, 스코프, 요약으로 필터링할 수 있습니다.
- OpenAPI JSON전체 명세를 자체 도구에서 쓸 수 있도록 파일 하나로 내려받습니다.
- 에이전트 ID / API조직 ID와 슬러그, API 모드(샌드박스 또는 운영), 선택한 AI 에이전트의 ID가 각각 복사 버튼과 함께 표시됩니다.
- 웹훅엔드포인트, 각 엔드포인트가 받는 이벤트, 마지막 HTTP 상태, 실패한 전송이 표시됩니다.
요청 한도와 아웃바운드 웹훅 섹션은 운영 전환 후가 아니라 전에 읽으십시오. 간단한 테스트에서는 놓치기 쉬운 동작이 설명되어 있습니다.
API 키와 스코프
모든 요청은 Authorization 헤더에 Bearer 토큰으로 키를 담습니다. 키는 앱에서 만들지 않습니다. 워크스페이스 운영자가 발급하고 어떤 스코프가 있는지 알려 줍니다. 전체 키는 발급 시점에 한 번만 표시되고 이후에는 앞의 몇 글자만 보이므로, 즉시 자체 시크릿 저장소에 보관하십시오.
| 스코프 | 허용 범위 |
|---|---|
| read | 연락처, 통화, 큐, 팀원, 보고서, 발신 금지 목록 조회. |
| write | 연락처 생성과 수정, 통화 결과 기록, 발신 금지 목록에 번호 추가. |
| calls | 전화 걸기와 끊기. |
| admin | 웹훅 관리. 다른 모든 엔드포인트도 호출할 수 있습니다. |
업무에 필요한 최소한의 스코프만 요청하십시오. 보고 스크립트에는 read만 있으면 되고, 클릭 투 콜 버튼에는 calls가 필요합니다. 요청이 insufficient_scope 코드와 함께 403을 반환하면, 키에 해당 엔드포인트 카드에 표시된 스코프가 없는 것입니다.
샌드박스와 운영
키는 시뮬레이터를 사용해 실제 전화를 걸지 않는 샌드박스용, 또는 운영용으로 발급될 수 있습니다. 키의 접두사는 단지 라벨로만 여기십시오. 테스트 라벨이 붙은 키도 운영 키와 같은 데이터, 같은 전화 연결에서 작동하므로, 접두사에 의존해 실험을 실제 고객과 분리하려 하지 마십시오. 지금 어느 모드인지는 개발자 페이지에 표시된 API 모드로 확인하십시오.
API로 전화 걸기
공개 엔드포인트는 기본 기능을 다룹니다. 헬스 체크, 통화 목록 조회, 단일 통화 조회, 전화 걸기, 끊기, 웹훅 관리, AI 에이전트와의 채팅입니다. API로 건 아웃바운드 전화는 데스크에서 건 전화와 같은 컴플라이언스 검사를 거치므로, 발신 금지 목록에 있는 번호나 허용된 발신 시간 밖의 전화는 상담원이 걸 때와 똑같이 거부됩니다. 이 거부를 버그가 아니라 정상적인 결과로 처리하도록 코드를 작성하십시오.
이는 설계에 중요합니다. 거부된 전화를 성공할 때까지 재시도하는 루프를 쓰지 마십시오. 이유를 읽고, 기록하고, 넘어가십시오. 거부의 근거가 되는 규칙은 Call의 발신 시간 가드와 Call의 발신 금지 목록을 참고하십시오.
요청 한도와 오류
키마다 발급 시 정해진 분당 요청 한도가 있으며 기본값은 120입니다. 키가 1분 한도를 모두 쓰면 API는 rate_limited 코드와 함께 429로 응답하고, X-RateLimit-Reset 헤더로 얼마나 기다려야 하는지 알려 줍니다. 그만큼 기다린 뒤 계속하십시오. 예의 바른 클라이언트는 벽에 부딪히기 전에 스스로 속도를 늦춥니다.
- 429 rate_limited: 재설정 헤더에 표시된 시간만큼 물러나 기다리고, 대량 작업은 시간에 걸쳐 분산합니다.
- 403 insufficient_scope: 키에 해당 엔드포인트 카드의 스코프가 없습니다. 그 스코프가 포함된 키를 요청하십시오.
- 기타 오류: 메시지가 아니라 오류 코드를 기준으로 처리합니다. 코드는 바뀌지 않지만 문구는 바뀔 수 있습니다.
실패한 요청 처리하기
- 상태 읽기고칠 수 있는 클라이언트 오류입니까, 아니면 재시도할 만한 서버 오류입니까?
- 코드 읽기메시지 텍스트가 아니라 코드로 분기합니다.
- 물러나기429는 재설정 헤더만큼 기다리고, 서버 오류는 간격을 늘려 가며 몇 번 재시도합니다.
- 상세 기록지원팀이 추적할 수 있도록 엔드포인트, 코드, 시각을 기록합니다.
- 거부 시 중단컴플라이언스 거부는 오류가 아니라 결정입니다. 반복 시도하지 마십시오.
웹훅: 이벤트 받기
무언가 일어났는지 API에 계속 묻는 대신 Call이 알려 주게 하십시오. 개발자 페이지에서 엔드포인트 추가를 누르고, 공개 https 주소를 입력하고, 원하는 이벤트를 체크하십시오. 아무것도 체크하지 않으면 모든 이벤트를 받습니다. 서명 시크릿은 엔드포인트를 추가할 때 한 번만 표시되므로 그때 복사하십시오. 잃어버렸다면 엔드포인트를 삭제하고 다시 추가해 새 시크릿을 받으십시오.
모든 전송에는 서명이 있습니다. 서명 헤더에는 타임스탬프와 본문을 마침표로 이어 붙인 값을 서명 시크릿으로 계산한 HMAC-SHA256이 담기며, 별도의 헤더에 타임스탬프가 담깁니다. 페이로드를 신뢰하기 전에 직접 다시 계산해 비교하십시오. API 레퍼런스에 Node.js와 Python 예제 코드가 있으며, 오래된 타임스탬프를 거부하면 재전송 공격을 막을 수 있습니다.
좋은 웹훅 수신기와 나쁜 웹훅 수신기
| 좋음 | 나쁨 | |
|---|---|---|
| 서명 | 모든 요청에서 검증 | 확인 없이 신뢰 |
| 응답 | 몇 초 안에 2xx, 작업은 나중에 처리하도록 대기열에 | 응답 전에 느리게 처리 |
| 중복 | 같은 이벤트를 두 번 받아도 안전 | 레코드가 두 개 생성됨 |
| 실패 | 전송 실패 시 알림 | 누군가 알아챌 때까지 조용함 |
엔드포인트는 10초 안에 2xx 상태로 응답해야 합니다. 실패한 전송은 다시 시도되어 총 최대 6회까지 시도되며, 연속 50회 실패한 엔드포인트는 꺼집니다. 개발자 페이지의 각 행에는 마지막 HTTP 상태와 실패한 전송 수가 표시되고, 테스트 발송을 누르면 서명된 테스트 이벤트가 하나 발송되어 서버가 어떻게 응답하는지 확인할 수 있습니다.
운영 전환 체크리스트
연동을 켜기 전에
- 키에 어떤 스코프가 있는지 알고, 필요 이상의 스코프가 없다
- 키가 소스 코드가 아니라 시크릿 저장소에 보관되어 있다
- 웹훅 서명을 검증하고 오래된 타임스탬프를 거부한다
- 수신기가 빠르게 응답하고 중복 이벤트를 처리한다
- 요청 한도 초과와 거부 응답을 촘촘한 재시도 루프 없이 처리한다
- 샌드박스 모드로 테스트했고 엔드포인트에서 테스트 발송을 눌러 봤다
- 전송이 실패하기 시작하면 알림을 받을 담당자가 정해져 있다
Call에서 하기
Call에서 설정 → API 레퍼런스를 열어 엔드포인트를 살펴보고, 설정 → 개발자에서 조직 ID를 복사하고, 키를 확인하고, 웹훅을 추가하십시오. 엔드포인트 추가, 테스트, 삭제는 소유자, 관리자, 매니저가 할 수 있으며, 그 외의 사람은 목록을 볼 수 있습니다. AI 에이전트 기능도 쓴다면 같은 페이지의 에이전트 ID를 채팅 엔드포인트에 사용합니다. 제품의 음성 측면은 Call에서 AI 에이전트 설정하기를 참고하십시오.
자주 묻는 질문
API 키는 어떻게 받습니까?
키는 워크스페이스 운영자가 발급하며, 앱에서 만들 수 없습니다. 필요한 스코프를 말하고 요청하십시오. 전체 키는 발급될 때 한 번만 표시됩니다.
429 응답은 무슨 뜻입니까?
키가 현재 1분 동안의 요청을 모두 썼다는 뜻입니다. X-RateLimit-Reset 헤더의 초만큼 기다린 뒤 다시 시도하고, 대량 작업은 더 긴 시간에 걸쳐 분산하십시오.
웹훅이 정말 Call에서 왔는지 어떻게 확인합니까?
서명 시크릿으로 타임스탬프와 본문의 HMAC-SHA256을 계산해 서명 헤더와 비교하십시오. API 레퍼런스에 Node.js와 Python 예제가 있습니다.
로컬 개발 서버로 웹훅을 받을 수 있습니까?
직접은 안 됩니다. 엔드포인트는 공개 https 주소여야 하므로, 로컬 서버를 공개 주소로 노출하는 터널링 도구를 쓰십시오.
API로 건 전화가 거부된 이유는 무엇입니까?
API로 건 전화는 데스크에서 건 전화와 같은 컴플라이언스 검사를 거칩니다. 발신 금지 목록에 있는 번호나 발신 가능 시간 밖의 전화는 거부됩니다.
웹훅은 누가 보고 바꿀 수 있습니까?
목록은 누구나 볼 수 있지만, 엔드포인트 추가, 테스트, 삭제는 소유자, 관리자, 매니저만 할 수 있습니다.