call.ended 웹훅은 준비 중이에요. 통화는 내 음성 에이전트가 BYE로 끊어요. Telkit은 번호마다 정한 최대 통화 시간에 닿은 통화를 끊고, 그 설정도 여기에 있어요.
통화는 끝난 뒤에 기록돼요. 통화 기록은 통화가 끝나고 30초쯤 뒤에 생겨요. 통화 중인 전화는 통화 기록에 없어요.
Authorization: Bearer <액세스 토큰> 헤더가 필요하고 기준 주소는 https://api.telkit.io예요. 에이전트는 첫 연결을 마치고 받은 워크스페이스 자격을 토큰으로 써요. 오류는 언제나 error.code와 error.message가 들어 있는 JSON으로 돌아와요.
통화 결과 필드
GET /v1/numbers/{id}/calls의 각 항목과 GET /v1/calls/{telkit_call_id}에 아래 필드가 있어요. 기존 필드는 그대로예요.
통화 한 건은 이렇게 보여요.
answered_at이 null이고 duration_sec이 0이에요. 이유는 sip_code와 result_text에 있어요. 관련 필드만 보면 이래요.
사유 표
result_text에 들어가는 문장이에요. Telkit이 보내는 문장을 그대로 옮겼어요.
연결되지 않은 통화
전화가 연결되지 않은 통화는 목적지의 마지막 응답 코드로 설명해요.
표에 없는 코드는 등급으로 설명해요.
1xx, 2xx, 3xx는 연결되지 않은 통화의 실패 코드가 아니라서
result_text가 null이에요.
연결된 통화
통화가 연결됐다가 끝난 경우는ended_by로 설명해요.
reason이 max_duration이면 ended_by와 상관없이 「번호의 최대 통화 시간에 닿아 회선이 끊었어요.」가 나와요.
웹훅 받기
웹훅은 준비 중이에요. 지금은 이 절의 요청이 모두
503 not_available로 돌아와요. 열리기 전에는 위의 통화 결과 필드를 통화 기록 API로 읽어 주세요. 아래는 웹훅이 열린 뒤 쓸 내용이에요.call.ended 웹훅을 보내요. 웹훅 주소는 계정마다 하나예요. 이 웹훅은 Telkit이 보내는 것이라 OpenAI 프로젝트에서 받는 live.transport.incoming 알림과는 다르고, 서명 비밀값도 따로 있어요.
웹훅 주소 만들기
PUT /v1/webhook-endpoint에 주소를 보내면 만들어요.
주소는 아래 규칙을 지켜야 해요. 어긋나면
422로 거절해요.
https://로 시작하는 주소만 받아요. 2048자까지예요.- 도메인 이름만 받아요. IP 주소,
localhost, 내부용 이름, Telkit의 도메인은webhook_host_not_allowed예요. - 사용자 정보
user:pass@와#조각은 넣을 수 없어요. - 쿼리 문자열에 토큰을 넣어도 돼요.
- 그 밖에 주소 모양이 맞지 않으면
invalid_webhook_url이에요.
이벤트
call.ended는 통화가 끝나고 통화 기록이 생긴 뒤에 보내요. 내 번호로 걸려 온 통화와 SIP 트렁크로 내가 건 통화 모두 보내고, direction으로 구분해요. 웹훅 주소를 만든 뒤에 끝난 통화부터 보내요. 그 전 통화는 통화 기록 API로 읽어 주세요.
Telkit은 POST로 Content-Type: application/json 본문을 보내고, 헤더는 Standard Webhooks 규격을 따라요.
본문은 이런 모양이에요.
data에는 아래 열세 개 키가 언제나 들어 있고, 모르는 값은 null이에요.
받는 서버는 이렇게 처리해 주세요.
2xx로 빨리 답해 주세요. 무거운 일은 답한 뒤에 하고, 10초 안에 답하지 않으면 실패로 봐요.- 같은
webhook-id가 다시 오면 한 번만 처리해 주세요. - 모르는 이벤트 종류와 필드는 무시해 주세요. 새 종류와 필드가 예고 없이 늘 수 있어요.
서명 검증
webhook-signature는 v1,에 이어 webhook-id.webhook-timestamp.본문을 HMAC-SHA256으로 서명해 base64로 적은 값이에요. 키는 whsec_ 뒤의 값을 base64로 푼 것이에요. 직접 계산하지 말고 공식 standardwebhooks 라이브러리로 검증해 주세요. 설치는 Node.js에서 npm i standardwebhooks, Python에서 pip install standardwebhooks예요.
검증할 때 지킬 것은 넷이에요.
- 받은 본문을 가공하지 않은 글자 그대로 넘겨 주세요. JSON으로 바꾼 뒤 다시 글자로 만들면 서명이 맞지 않아요.
whsec_로 시작하는 비밀값을 접두사까지 그대로 넘겨 주세요.- 검증이 예외를 내면 이벤트를 처리하지 말고
400으로 거절해 주세요. - 허용하는 시간 차이는 기본값인 5분 그대로 두어 주세요.
다시 보내기
2xx로 답하면 전달이 끝나요. 그 밖의 상태 코드, 10초를 넘긴 응답, 연결 오류와 인증서 오류는 실패로 보고 아래 간격으로 다시 보내요. 3xx도 리다이렉트를 따라가지 않고 실패로 봐요.
- 처음 시도부터 마지막 시도까지 27시간이 조금 넘어요. 여덟 번 시도해도 받지 못하면 그 이벤트는 버려요.
410으로 답하면 그 이벤트는 다시 보내지 않아요.- 다시 보내도
webhook-id와 본문은 같고,webhook-timestamp와 서명만 새로 만들어요. - 버린 이벤트는 다시 보내지 않아요. 놓친 통화는 통화 기록 API에서 언제나 읽을 수 있어요.
비밀값 바꾸기
POST /v1/webhook-endpoint/rotate-secret으로 새 비밀값을 받아요.
- 새
secret은 이 응답에서 한 번만 보여요. - 옛 비밀값도 24시간 동안 함께 서명해서
webhook-signature헤더에 서명이 둘 실려요. 두 서명은 공백으로 나뉘어 있고, 공식 라이브러리는 하나만 맞아도 통과시켜요. 그 사이에 서버를 새 비밀값으로 바꿔 주세요. - 옛 비밀값이 끝나는 시각은
GET /v1/webhook-endpoint의previous_secret_expires_at에 있어요. - 24시간 안에 다시 바꾸면 그보다 오래된 비밀값은 사라져요.
최대 통화 시간
통화를 끝내는 것은 내 음성 에이전트의 일이에요. 내 음성 에이전트가 통화를 끝내면 BYE를 보내고, Telkit은 그 BYE로 양쪽 통화를 정리해요. Telkit이 통화를 끊는 때는 한 가지예요. 통화 하나가 번호의 최대 통화 시간에 닿으면 회선이 양쪽을 모두 끊어요. 음성 에이전트가 통화를 끝내지 못해도 통신비가 길게 이어지지 않게 하는 안전장치예요.- 값은 60 ~ 14400초예요. 4시간까지이고 기본은 3600초예요.
- 바꾼 값은 잠시 후부터 새로 걸리는 통화에 적용돼요. 이미 통화 중인 전화는 그대로예요.
- 번호를 해지하면 값이 3600초로 돌아가요.
- 에이전트에게 최대 통화 시간 변경을 요청하면 아래 API로 저장해요.
max_duration_sec이 저장한 값이에요. GET /v1/numbers/{id}에서도 볼 수 있어요.
한도에 닿아 끊긴 통화는 통화 기록에 ended_by가 system, reason이 max_duration으로 나와요.