API를 통해 AI 통화 걸기 및 Astra 관리

업데이트됨: Mon Aug 17 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

API는 Astra(AI 에이전트)를 구성하고 게시하며, 번호를 연결하고, 아웃바운드 통화를 걸 수 있습니다. POST /v1/api/calls를 사용하면 게시된 에이전트가 번호로 전화를 걸고, 대화를 진행하며, 통화 기록(녹음, 스크립트, 요약 포함)을 연락처의 타임라인에 기록합니다. 이 통화는 인바운드 AI 응답 통화와 동일하게 AI 크레딧으로 청구됩니다.

시작하기 전에

API 키에는 올바른 범위가 필요합니다. 설정 → 개발자 API의 칩: 에이전트 구성 및 번호 라우팅을 위한 AI 에이전트 관리(agent:manage)와 아웃바운드 통화를 위한 AI 통화 걸기(calls:place). 전체 액세스 키에는 둘 다 포함됩니다. Ody API 키 가져오기를 참조하세요.
아웃바운드 통화에는 활성 요금제, 게시되고 활성화된 에이전트, 그리고 작업 공간에 최소 하나의 활성 번호가 필요합니다.
크레딧은 평소와 동일하게 작동합니다: AI 응답 통화당 100 크레딧, 15초 미만 통화는 무료이며, 모든 요금제에는 월 1,000 크레딧이 포함됩니다. Astra 크레딧 및 사용량을 참조하세요.

에이전트 구성 및 게시

GET /v1/api/agent는 에이전트 구성과 현재 주기 크레딧 사용량을 반환합니다. 이는 일괄 통화 전에 예산을 확인하는 데 유용합니다. PATCH /v1/api/agent는 name, greeting, tone, voice, language, timezone, inHoursAction/offHoursAction(agent, voicemail, app 또는 forward), enabled, jobs를 업데이트합니다. jobs는 제공될 때 전체가 교체되는 것을 제외하고, 전송하는 필드만 변경됩니다:

curl -X PATCH https://api.ody.co/v1/api/agent \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "greeting": "Thanks for calling Acme Plumbing!",
    "tone": "Friendly",
    "jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
  }'

변경 사항은 초안으로 저장됩니다. 이는 앱의 AI 에이전트 화면에서 볼 수 있는 초안과 동일합니다. 다음을 사용하여 라이브로 푸시하세요:

curl -X POST https://api.ody.co/v1/api/agent/publish \
  -H "Authorization: Bearer ody_live_…"

에이전트에 번호 연결

POST /v1/api/numbers/{number}/connect는 인바운드 통화에 응답하도록 번호 중 하나를 에이전트로 연결합니다(+는 %2B로 URL 인코딩):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
  -H "Authorization: Bearer ody_live_…"

팀으로 다시 연결하려면 mode를 app(팀에게 전화 걸기 — 기본값), voicemail 또는 forward(forwardTo 번호와 함께)로 설정하여 …/disconnect를 사용하세요:

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"app"}'

아웃바운드 AI 통화 걸기

POST /v1/api/calls는 게시된 에이전트가 전화를 걸고 대화를 진행하도록 합니다:

curl https://api.ody.co/v1/api/calls \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550199"}'

to는 필수입니다(E.164). from은 선택 사항입니다. Ody는 에이전트에 연결된 번호를 선호하며, 그 다음으로 첫 번째 활성 번호를 선호합니다. 소유한 특정 회선을 선택하려면 from을 전달하세요.
국제 목적지는 작업 공간의 일반적인 국제 통화 규칙을 따릅니다. 국제 통화 및 제한을 참조하세요.
통화가 종료되면 녹음, 스크립트, 요약과 함께 받은 편지함의 연락처 타임라인에 나타납니다. 이는 인바운드 AI 통화와 동일한 "AI 에이전트가 이 통화를 처리했습니다" 카드입니다.
청구: 통화가 응답되면 100 크레딧이 소모되며, 15초 미만 통화는 무료입니다. 응답되지 않은 통화는 항상 무료입니다.

언제든지 인계받을 수 있습니다

API를 통해 수행되는 모든 작업은 별도의 개발자 샌드박스가 아닌 실제 계정 상태입니다. 코드가 게시하는 에이전트는 AI 에이전트 화면에 있는 에이전트이며, 연결하는 번호는 설정 → 번호에 있습니다. 에이전트가 거는 통화는 공유 받은 편지함에 도착합니다. 즉, 언제든지 개입할 수 있습니다: 앱에서 인사말을 편집하거나, 스레드에 직접 답장하거나, 번호의 라우팅 칩을 클릭하여 통화를 팀으로 다시 보낼 수 있습니다. API는 필요하지 않습니다.

AI 어시스턴트(MCP)에서

연결된 AI 어시스턴트는 MCP 도구와 동일한 기능을 가집니다: get_agent, configure_agent(한 단계로 라이브로 전환하려면 publish: true 전달), connect_agent_to_number, place_call. MCP로 AI 도구 연결을 참조하세요.

테스트 모드

ody_test_… 키를 사용하면 POST /calls는 시뮬레이션된 통화( sim_… ID, 전화 걸기 없음, 크레딧 사용 없음)를 반환하고 POST /agent/publish는 시뮬레이션됩니다(구성은 초안으로 유지). PATCH /agent를 통한 초안 저장은 두 키 유형 모두에서 실제입니다. 테스트 모드로 안전하게 구축을 참조하세요.

자주 묻는 질문

아웃바운드 AI 통화 비용은 얼마인가요?

인바운드 AI 응답 통화와 동일합니다: 응답된 통화당 100 AI 크레딧이 소모되며, 15초 미만 통화는 무료입니다. 응답되지 않은 통화는 비용이 발생하지 않습니다.

전화를 걸기 전에 무엇이 필요한가요?

활성 요금제, 게시되고 활성화된 AI 에이전트, 그리고 최소 하나의 활성 번호가 필요합니다. 소유한 발신 번호를 전달하지 않는 한, Ody는 에이전트에 연결된 번호로 전화를 겁니다.

에이전트로부터 인계받을 수 있나요?

언제든지 가능합니다. API를 통해 변경되는 모든 것은 앱에서 볼 수 있는 동일한 에이전트, 번호, 스레드입니다. 앱을 열어 에이전트를 편집하거나, 스레드에 답장하거나, 번호를 팀으로 다시 연결할 수 있습니다.