빠른 시작 (API)

AI 에이전트로 첫 전화를 응대합니다. API 키를 발급하고, 에이전트를 생성하고, 전화번호를 개통한 다음, REST API만으로 실시간 테스트 전화를 걸 수 있습니다.

이 가이드에서는 AI 에이전트로 첫 전화를 받기 위해 필요한 네 번의 REST 호출을 안내합니다.

1단계: API 키 가져오기

로그인
app.thunderphone.com을 엽니다.
키로 이동
대시보드에서 조직 → 키로 이동합니다.
키 만들기
키 만들기를 클릭하고 이름을 지정한 다음 sk_live_... 값을 복사합니다. 원본 키는 한 번만 표시되므로 즉시 시크릿 관리자에 저장합니다.

이 가이드 전체에서 sk_live_YOUR_API_KEY를 방금 복사한 값으로 바꿉니다. 키가 조직을 자동으로 식별하므로 URL에 조직 ID를 입력할 필요가 없습니다.

2단계: 에이전트 만들기

에이전트는 AI가 대화를 처리하는 방식을 정의합니다. 여기에는 프롬프트, 음성, 제품 티어, 도구 및 위젯 사용 가능 여부가 포함됩니다.

cURL

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

Python

import os, requests
 
agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={
        "name":   "Customer Support",
        "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
        "voice":  "john",
        "product": "spark",
    },
).json()
print("Agent id:", agent["id"])

Node.js

const agent = await fetch("https://api.thunderphone.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name:    "Customer Support",
    prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    voice:   "john",
    product: "spark",
  }),
}).then((r) => r.json());
console.log("Agent id:", agent.id);

3단계: 전화번호 프로비저닝

이 호출은 ThunderPhone에 전화번호를 요청하고 새 에이전트를 수신 처리기로 할당합니다. (VoIP 제공업체에서 자체 전화번호를 가져오려면 대신 VoIP 연결을 참조합니다.)

cURL

# First provision
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"}'
 
# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Python

number = requests.post(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"area_code": "415"},
).json()
requests.patch(
    f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])

새 전화번호는 status="provisioning" 상태로 시작하며 몇 초 내에 active 상태로 전환됩니다. 브라우저를 닫을 때쯤이면 전화번호가 전화를 받을 준비를 마칩니다.

4단계(선택 사항): 웹훅 설정

실시간 이벤트(동적 통화 라우팅, 통화 후 처리)를 위해 웹훅 엔드포인트를 추가합니다. 필요한 이벤트만 구독합니다.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

응답에는 일회성 secret이 포함되어 있습니다. 이를 시크릿 관리자에 복사합니다. 해당 시크릿을 사용하여 수신 요청의 X-ThunderPhone-Signature-V2 헤더를 검증합니다(Webhook 개요 참조).

5단계: 에이전트 테스트

방금 프로비저닝한 전화번호로 전화를 겁니다. 에이전트가 전화를 받고 자신을 소개한 뒤 프롬프트를 따릅니다.

통화가 종료된 후 통화를 확인합니다.

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

특정 통화의 상세 정보를 확인하여 대화 기록과 녹음 URL을 가져옵니다.

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