API 개요 및 인증

Ody REST API는 https://api.ody.co/v1/api에 있으며, Bearer 토큰으로 전송된 API 키로 모든 요청을 인증합니다. 설정 → 개발자 API에서 키를 생성한 다음 아래 엔드포인트를 호출하세요.

인증

모든 요청에 Authorization 헤더에 키를 전송하세요:

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• 키는 두 가지 모드로 제공됩니다: ody_live_… 키는 라이브이며, ody_test_… 키는 동일하게 작동하지만 메시지 전송은 시뮬레이션됩니다 (deliveryStatus: "simulated"로 기록되며, 전송되지 않습니다). 테스트 모드로 안전하게 구축하기를 참조하세요.
• 누락되었거나, 유효하지 않거나, 취소된 키는 401 unauthenticated를 반환합니다.
• 범위로 제한된 키는 부여된 권한 외의 엔드포인트를 호출할 때 403 permission_denied를 반환하며, 누락된 범위를 명시합니다.
• 모든 호출은 키를 생성한 멤버의 권한으로 해당 워크스페이스 내에서만 실행됩니다.

엔드포인트

메서드 및 경로	기능	필수 범위
GET /v1/api/contacts	연락처 목록 또는 검색 (?q=, 페이지네이션)	contacts:read
POST /v1/api/contacts	연락처 생성	contacts:write
GET /v1/api/contacts/:id	연락처의 전체 세부 정보 가져오기	contacts:read
PATCH /v1/api/contacts/:id	연락처 업데이트 (제공된 필드만 변경)	contacts:write
DELETE /v1/api/contacts/:id	연락처 삭제	contacts:write
GET /v1/api/conversations	대화 목록 (?status=open|done, 페이지네이션)	conversations:read
GET /v1/api/conversations/:id	전체 스레드 가져오기	conversations:read
PATCH /v1/api/conversations/:id	상태 설정 — 본문 {"status":"open"} 또는 {"status":"done"}	conversations:write
POST /v1/api/messages	SMS/MMS 전송 (Idempotency-Key 지원)	messages:send
GET /v1/api/messages/search	메시지 본문 및 스크립트 검색 (?q=)	conversations:read
GET /v1/api/calls	통화 및 음성 메일 기록 목록	conversations:read
POST /v1/api/calls	아웃바운드 AI 통화 걸기 — 게시된 에이전트가 다이얼	calls:place
GET /v1/api/numbers	워크스페이스의 전화번호 목록	numbers:read
GET /v1/api/numbers/available	구매 가능한 전화번호 검색 (?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=)	numbers:manage
POST /v1/api/numbers	전화번호 구매 — 인앱 구매와 동일하게 청구 (Idempotency-Key 지원)	numbers:manage
POST /v1/api/numbers/:e164/connect 및 …/disconnect	AI 에이전트로 또는 AI 에이전트에서 전화번호 라우팅	agent:manage
GET /v1/api/messaging	10DLC 등록 상태 (step, canText)	numbers:manage
POST /v1/api/messaging/registration	10DLC 비즈니스 + 캠페인 제출 (청구됨)	numbers:manage
POST /v1/api/messaging/refresh	10DLC 통신사 검토 재확인 및 진행	numbers:manage
GET/PATCH /v1/api/agent	AI 에이전트 구성 읽기 또는 업데이트 (초안)	agent:manage
POST /v1/api/agent/publish	에이전트 구성을 라이브로 푸시	agent:manage
GET /v1/api/webhook-events	구독 가능한 웹훅 이벤트 유형 목록	webhooks:manage
GET/POST /v1/api/webhooks 및 /v1/api/webhooks/:id…	아웃바운드 웹훅 엔드포인트 관리	webhooks:manage
GET /v1/api/openapi.json	OpenAPI 3.1 사양	none

목록 엔드포인트는 ?limit= 및 ?cursor=로 페이지네이션됩니다 — 페이지네이션, 멱등성 및 오류 처리를 참조하세요.

연락처

POST /v1/api/contacts는 firstName, lastName, company, 전화번호 또는 이메일 중 최소 하나의 식별 필드를 필요로 합니다. 전화번호와 이메일은 단순 문자열 ("phone": "+15125550123") 또는 전체 레이블 배열 ("phones": [{"value": "+15125550123", "label": "work"}])을 허용합니다. PATCH 시에는 제공하는 필드만 변경됩니다; phones, emails, notes, properties, tags는 제공될 때 전체가 교체됩니다.

메시지 전송

POST /v1/api/messages는 기존 conversationId 또는 to 필드의 수신자 전화번호 (E.164 형식)를 허용합니다. to를 사용하면 Ody가 워크스페이스의 발신 번호를 선택하고 (또는 소유한 from을 존중), 필요한 경우 대화를 생성하고 메시지를 스레드합니다. MMS의 경우 최대 10개의 공개적으로 가져올 수 있는 mediaUrls를 추가하세요:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

활성 전화번호가 없는 워크스페이스는 409 failed_precondition을 받습니다. 24시간 이내에 동일한 Idempotency-Key로 재시도하면 이중 전송 대신 첫 번째 응답이 재생됩니다.

전화번호, 문자 메시지, AI 통화 및 AI 에이전트

API는 또한 전화선을 처음부터 끝까지 운영할 수 있습니다: 전화번호 검색 및 구매, 10DLC 문자 메시지 등록, AI 에이전트 구성 및 게시, AI 에이전트로 전화번호 라우팅, 아웃바운드 AI 통화 걸기. 이 엔드포인트들은 자체적인 세 가지 범위 — numbers:manage (전화번호 구매 및 10DLC), calls:place (AI 통화 걸기), agent:manage (AI 에이전트 관리) —를 사용하며, 앱에서 직접 수행한 것과 동일하게 동일한 청구 및 규칙으로 모든 작업이 계정에 반영됩니다. API를 통해 전화번호 구매 및 문자 메시지 등록 및 API를 통해 AI 통화 걸기 및 Astra 관리를 참조하세요.

오류, 요청 ID 및 속도 제한

모든 오류는 균일한 봉투를 사용하며, 모든 응답 (성공 또는 오류)에는 X-Request-Id 헤더가 포함됩니다 — 지원팀에 문의할 때 이 ID를 인용하세요:

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

모든 키는 표준 RateLimit-* 헤더와 함께 분당 600개의 요청을 받습니다. 자세한 내용은 API 속도 제한 및 모범 사례 및 페이지네이션, 멱등성 및 오류 처리를 참조하세요.

관련 문서

• Ody API 키 받기
• 웹훅 수신 및 서명 확인
• 페이지네이션, 멱등성 및 오류 처리
• SDK 빠른 시작: TypeScript 및 Python