REST 빠른 시작

번호 API 키 발급

번호 관리에서 번호를 열고 아웃바운드 탭으로 갑니다. 키가 아직 없으면 이 화면이 먼저 뜹니다 — [키 생성]을 누르면 됩니다.

키는 tg_live_로 시작합니다. 인증용 해시와 함께 복구용 암호화본을 저장하며, 워크스페이스 관리자는 아웃바운드 탭에서 복사를 눌러 키 전문을 다시 가져올 수 있습니다. 다시 조회해도 키가 바뀌지 않으며 조회 기록이 남습니다. 암호화본이 없는 이전 발급 키는 다시 조회할 수 없습니다.

export VOX_API_KEY="tg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

키 하나 = 번호 하나입니다. 발신 번호는 키가 결정하므로 요청 본문에 발신자를 넣지 않습니다. 키를 잃어버렸다면 먼저 복사로 다시 가져오세요. 다시 조회할 수 없는 키이거나 키를 교체해야 한다면 재발급합니다. 재발급하면 이전 키는 즉시 무효가 되므로 기존 연동의 키도 교체해야 합니다.

전화 걸기

착신번호 to만 있으면 발신되고, instruction에 이번 통화의 임무를 적습니다. 상대가 받는 즉시 AI가 먼저 말을 겁니다.

curl -X POST https://vox-gateway-dev.fly.dev/api/v1/calls \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "010-1234-5678",
    "instruction": "김민수 님에게 8월 3일 오후 2시 예약이 확정됐다고 알리고, 변경이 필요한지 물어본다."
  }'

성공하면 201과 함께 다음이 돌아옵니다.

{ "call_id": "9f1c…", "status": "ringing", "from": "07079193558" }

번호는 국내형으로 넘깁니다(+82 금지). 하이픈·공백은 넣어도 되고 저장 시 제거됩니다.

이 통화만 짧게 제한하려면 요청 본문에 max_duration_sec를 추가합니다. 예를 들어 "max_duration_sec": 120은 상대가 받은 뒤 최대 120초로 제한합니다. 값은 60~1800초 정수이며, 해당 번호에 적용되는 통화 정책의 최대 시간 이하여야 합니다. 생략하면 저장된 정책을 따릅니다. 번호나 워크스페이스의 저장 설정은 바뀌지 않습니다.

범위를 벗어나면 400 invalid_max_duration_sec, 번호의 유효 정책보다 길면 400 max_duration_exceeds_policy가 돌아옵니다. 후자는 maximum에 허용 상한을 함께 줍니다.

발신 경로와 응답 예시는 발신 레퍼런스에서 확인할 수 있습니다.

결과 확인

call_id로 상태를 조회합니다. status와 end_reason으로 진행 상태와 종료 사유를 확인하고, options와 options_pending으로 통화 옵션의 적용 상태를 확인할 수 있습니다.

curl https://vox-gateway-dev.fly.dev/api/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $VOX_API_KEY"

실제 연결 시간은 duration_sec입니다. 상대가 받은 시점부터 연결 종료까지 측정하며, 벨이 울리는 시간은 포함하지 않습니다. 진행 중이거나 측정값이 아직 보고되지 않았으면 null, 받지 않은 통화(no_answer)는 0입니다. null을 0초로 처리하지 마세요. ended_at - started_at은 벨 울리는 시간을 포함하므로 실제 연결 시간과 다릅니다.

대화 전문은 전사본 조회, 녹음은 아래 REST 경로 또는 콘솔의 통화 이력에서 확인합니다.