REST 빠른 시작

번호 API 키를 발급해 POST 한 번으로 전화를 걸고 결과를 확인하기까지.

기본 설정 그대로면 통화는 내장 Agent가 담당합니다. 별도 서버를 띄우지 않아도 임무 한 줄만 넘기면 AI가 전화를 걸어 대화합니다. 이 문서는 그 통화를 REST로 거는 길입니다.

코드를 쓰지 않을 거라면 이 문서를 건너뛰어도 됩니다. Claude 같은 MCP 클라이언트에 번호를 붙이면 대화로 전화를 걸고 결과까지 확인할 수 있습니다 — MCP 커넥터로 가세요. 콘솔에서 바로 걸어보려면 체험 콜이 가장 빠릅니다.

준비물

  • 워크스페이스에 배정된 전화번호 하나 — 번호 관리에서 확인합니다.
  • 그 워크스페이스의 admin 권한 — API 키 발급에 필요합니다.
  • 받을 사람의 번호. 통화료가 실제로 발생합니다.

번호를 아직 못 받았다면 체험 콜에서 플랫폼 대표번호로 먼저 걸어볼 수 있습니다.

  1. 1

    번호 API 키 발급

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

    아웃바운드 탭의 API 키 생성 안내 카드

    키는 tg_live_로 시작하며, 서버에는 해시만 저장되므로 생성 직후 화면에서만 전문을 볼 수 있습니다.

    export VOX_API_KEY="tg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    키 하나 = 번호 하나입니다. 발신 번호는 키가 결정하므로 요청 본문에 발신자를 넣지 않습니다. 키를 잃어버렸으면 재발급하세요 — 재발급하면 이전 키는 즉시 무효가 됩니다.

  2. 2

    전화 걸기

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

    curl -X POST https://vox-gateway-prod.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 금지). 하이픈·공백은 넣어도 되고 저장 시 제거됩니다.

  3. 3

    결과 확인

    call_id로 상태를 조회합니다. 응답은 네 개 키뿐이라 폴링에 가볍습니다.

    curl https://vox-gateway-prod.fly.dev/api/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $VOX_API_KEY"
    status뜻
    ringing아직 벨이 울리는 중
    active상대가 받아 대화 중
    completed정상 종료
    no_answer받지 않음
    failed연결 실패 또는 오류

    폴링 대신 Webhook으로 시작·종료를 받을 수도 있습니다. 대화 전문과 녹음은 콘솔의 통화 이력에서 확인합니다.

다음 단계