수신 전화 처리(API)

엔드투엔드: 에이전트를 구성하고, 전화번호에 할당하고, 전화를 받고, 통화를 검토합니다.

터미널에서 수행하는 표준적인 "AI로 전화를 받는" 흐름입니다. 다음을 수행합니다.

1. 프롬프트와 음성이 포함된 에이전트를 생성합니다.
2. 전화번호를 프로비저닝하거나 가져온 뒤, 에이전트를 해당 번호의 인바운드 처리기로 할당합니다.
3. 번호로 전화를 겁니다. 통화 로그, 트랜스크립트, 녹음을 확인합니다.

총 API 호출: 4회. 총 소요 시간: 5분 미만.

1. 에이전트 생성#

에이전트는 통화를 수행하는 프롬프트, 음성, 제품 티어를 묶습니다. 에이전트에서 max_call_duration_seconds 및 ring_duration_seconds와 같은 통화 제한도 설정할 수 있습니다. 에이전트는 또한 에이전트가 말하기 전에 사전 녹음된 인트로와 최대 두 번의 벨소리를 재생하는 intro_clip 및 intro_ring_count를 지원합니다. 새 에이전트에는 시간대도 필요합니다. 모든 구성 필드는 에이전트를 참조하세요. 최소 설정은 다음과 같습니다:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

반환된 id를 저장하세요. 2단계에서 필요합니다.

2. 전화번호 받기#

전화할 번호만 필요하다면 ThunderPhone의 번호 풀에서 ThunderPhone 번호를 받으세요.

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

응답에는 E.164 형식의 id와 number가 포함됩니다. ThunderPhone 번호는 status="provisioning" 상태로 시작하며 몇 초 내에 active 상태가 됩니다. 전환 상태를 확인해야 한다면 GET /v1/phone-numbers/{id}를 폴링하세요.

3. 에이전트 할당#

1단계의 에이전트를 번호의 인바운드 방향에 연결합니다.

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

이제 번호가 활성화되었습니다. 조직의 아웃바운드 통화가 승인된 후에는 동일한 PATCH에서 outbound_agent_id도 설정할 수 있습니다. 승인 전에는 API가 해당 할당을 400으로 거부합니다.

고정된 inbound_agent_id 대신 구성 웹훅을 통해 수신 전화를 라우팅하는 경우, 이제 해당 웹훅은 agent_id 및 variables와 함께 통화별 timezone을 반환할 수 있습니다.

4. 통화 받기#

휴대폰에서 해당 번호로 전화를 거세요. 에이전트가 전화를 받고 프롬프트에 따라 자신을 소개한 후 대화가 시작됩니다.

통화가 진행 중인 동안에는 GET /v1/calls에 status="in_progress"로 표시됩니다. 통화가 종료되면 레코드가 end_reason, duration_seconds, billable_minutes, 그리고 최종적으로 녹음 URL 및 AI 평가로 업데이트됩니다.

수신 전화는 조직의 동시 통화 한도에 포함됩니다(기본적으로 통화 진행 중 20건이며, 발신, 웹 및 테스트 통화와 공유됩니다). 한도에 도달한 상태에서 걸려온 전화는 에이전트가 응답하기 전에 거부되고 종료되며, 요금이 청구되지 않고 종료 사유가 concurrent_call_limit_reached인 실패한 통화로 기록됩니다. 더 높은 한도가 필요하면 support@thunderphone.com으로 이메일을 보내세요.

5. 결과 확인#

최근 통화 목록을 가져옵니다.

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

대화 기록을 가져옵니다.

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

녹음 URL(단기간 유효한 서명 URL)도 가져옵니다.

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

telephony.complete 웹훅을 구독한 경우 동일한 데이터를 서버로 POST 요청으로 받습니다. 자세한 내용은 call.complete를 참고하세요.

에이전트에 추출 필드가 구성되어 있으면 완료된 통화 페이로드에 구조화된 추출 데이터도 포함될 수 있습니다.

다음 단계#