빠른 시작 (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 헤더를 검증합니다(웹훅 개요 참조).

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"