SDK 빠른 시작: TypeScript 및 Python

Ody는 전체 REST API를 다루는 공식 TypeScript 및 Python SDK를 제공합니다. 여기에는 연락처, 대화, 메시지(멱등성 전송 포함), 아웃바운드 AI 통화, 번호 검색 및 구매, 10DLC 등록, AI 에이전트 및 웹훅 관리가 포함되며, 내장된 Standard-Webhooks 서명 검증기도 함께 제공됩니다.

시작하기 전에

• API 키가 필요합니다. Ody API 키 받기를 참조하세요. 개발 중에는 ody_test_… 키를 사용하여 전송이 시뮬레이션되도록 하세요 (테스트 모드로 안전하게 구축).
• 아직 어떤 패키지도 레지스트리에 게시되지 않았습니다. ody-platform 저장소의 sdks/ 디렉토리에서 둘 다 설치하세요. 게시되면 npm에서는 @ody/sdk, PyPI에서는 ody-sdk가 될 것입니다.

TypeScript (@ody/sdk)

Node 18+가 필요합니다 (브라우저, Deno, Bun에서도 작동하며, 전역 fetch를 사용하고 런타임 종속성이 없습니다). 저장소에서 빌드 및 설치:

cd ody-platform/sdks/typescript
npm run build   # emits dist/
npm install /path/to/ody-platform/sdks/typescript   # from your project

import { Ody, OdyError } from "@ody/sdk";

const ody = new Ody(process.env.ODY_API_KEY!);

// 연락처 — 생성, 검색 및 자동 페이지 매김 (nextCursor를 자동으로 따름)
const contact = await ody.contacts.create({ firstName: "Ada", phone: "+15125550123" });
for await (const c of ody.contacts.listAll()) console.log(c.id, c.firstName);

// 대화
const open = await ody.conversations.list({ status: "open" });
await ody.conversations.setStatus(open.conversations[0].id, "done");

// SMS 전송 — 멱등성이며, 동일한 키로 24시간 동안 안전하게 재시도 가능
const sent = await ody.messages.send({
  to: "+15125550123",
  body: "Your order shipped!",
  idempotencyKey: "order-1042-shipped",
});

// 오류는 타입이 지정됨
try {
  await ody.contacts.get("00000000-0000-0000-0000-000000000000");
} catch (err) {
  if (err instanceof OdyError) console.error(err.code, err.status, err.requestId);
}

Python (ody-sdk)

Python ≥ 3.9가 필요하며, 표준 라이브러리만 사용합니다. 저장소에서 설치:

pip install /path/to/ody-platform/sdks/python
# or for development: pip install -e sdks/python

from ody import Ody, OdyError

client = Ody("ody_live_...")

# 연락처 — 생성, 검색 및 자동 페이지 매김
contact = client.contacts.create(first_name="Ada", phone="+15125550123")
for c in client.contacts.list_all():
    print(c["id"], c["firstName"])

# SMS 전송 — 멱등성이며, 동일한 키로 24시간 동안 안전하게 재시도 가능
sent = client.messages.send(
    to="+15125550123",
    body="Your order shipped!",
    idempotency_key="order-1042-shipped",
)

# 오류는 타입이 지정됨
try:
    client.contacts.get("00000000-0000-0000-0000-000000000000")
except OdyError as err:
    print(err.code, err.status, err.request_id)

두 SDK가 다루는 내용

그룹	메서드
연락처	list, listAll/list_all, create, get, update, delete
대화	list, listAll/list_all, get, setStatus/set_status
메시지	send (멱등성 키 포함), search
통화	list, place (아웃바운드 AI 통화)
번호	list, searchAvailable/search_available, buy (멱등성 키 포함), connectAgent/connect_agent, disconnectAgent/disconnect_agent
메시징 (10DLC)	status, register, refresh
에이전트	get, update, publish
웹훅	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

두 SDK 모두 웹훅 서명 검증기 — verifyWebhookSignature (TypeScript, Node 서버 전용) 및 verify_webhook_signature (Python) — 를 제공하며, 상수 시간 비교 및 5분 재생 방지 기능을 갖추고 있습니다. 파싱된 JSON이 아닌 원시 본문 바이트를 전달하세요. 전체 흐름은 웹훅 수신 및 서명 확인을 참조하세요.

번호, 메시징, 에이전트 및 calls.place 메서드 (예: ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — Python에서는 snake_case)는 REST API와 동일한 전화선 기능을 다룹니다. API를 통해 번호 구매 및 문자 메시지 등록 및 API를 통해 AI 통화 걸기 및 Astra 관리를 참조하세요.

429 오류 발생 시, 두 SDK 모두 Retry-After 값 (err.retryAfter / err.retry_after)을 표시합니다. API 속도 제한 및 모범 사례에 따라 이를 준수해야 합니다.

관련 문서

• API 개요 및 인증
• 웹훅 수신 및 서명 확인
• 페이지 매김, 멱등성 및 오류 처리
• 테스트 모드로 안전하게 구축