SDK quickstart: TypeScript and Python

Ody ships official TypeScript and Python SDKs covering the full REST API — contacts, conversations, messages (with idempotent sends), outbound AI calls, number search and purchase, 10DLC registration, your AI agent, and webhook management, plus a built-in Standard-Webhooks signature verifier.

Before you start

• You need an API key — see Get your Ody API key. Use an ody_test_… key while developing so sends are simulated (Build safely with test mode).
• Neither package is published to a registry yet. Install both from the ody-platform repo's sdks/ directory; once published they'll be @ody/sdk (npm) and ody-sdk (PyPI).

TypeScript (@ody/sdk)

Requires Node 18+ (also works in browsers, Deno, and Bun — it uses the global fetch and has zero runtime dependencies). Build and install from the repo:

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!);

// Contacts — create, search, and auto-paginate (follows nextCursor for you)
const contact = await ody.contacts.create({ firstName: "Ada", phone: "+15125550123" });
for await (const c of ody.contacts.listAll()) console.log(c.id, c.firstName);

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

// Send an SMS — idempotent, safe to retry with the same key for 24h
const sent = await ody.messages.send({
  to: "+15125550123",
  body: "Your order shipped!",
  idempotencyKey: "order-1042-shipped",
});

// Errors are typed
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)

Requires Python ≥ 3.9, standard library only. Install from the repo:

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_...")

# Contacts — create, search, and auto-paginate
contact = client.contacts.create(first_name="Ada", phone="+15125550123")
for c in client.contacts.list_all():
    print(c["id"], c["firstName"])

# Send an SMS — idempotent, safe to retry with the same key for 24h
sent = client.messages.send(
    to="+15125550123",
    body="Your order shipped!",
    idempotency_key="order-1042-shipped",
)

# Errors are typed
try:
    client.contacts.get("00000000-0000-0000-0000-000000000000")
except OdyError as err:
    print(err.code, err.status, err.request_id)

What both SDKs cover

Group	Methods
Contacts	list, listAll/list_all, create, get, update, delete
Conversations	list, listAll/list_all, get, setStatus/set_status
Messages	send (with idempotency key), search
Calls	list, place (outbound AI call)
Numbers	list, searchAvailable/search_available, buy (with idempotency key), connectAgent/connect_agent, disconnectAgent/disconnect_agent
Messaging (10DLC)	status, register, refresh
Agent	get, update, publish
Webhooks	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

Both also ship a webhook signature verifier — verifyWebhookSignature (TypeScript, Node servers only) and verify_webhook_signature (Python) — with constant-time comparison and a 5-minute replay guard. Pass the raw body bytes, not parsed JSON. See Receive webhooks and verify signatures for the full flow.

The numbers, messaging, agent, and calls.place methods (for example ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — snake_case in Python) cover the same phone-line surface as the REST API. See Buy numbers and register texting via the API and Place AI calls and manage Astra via the API.

On a 429, both SDKs surface the Retry-After value (err.retryAfter / err.retry_after) — respect it, per API rate limits and best practices.

Related articles

• API overview and authentication
• Receive webhooks and verify signatures
• Pagination, idempotency, and error handling
• Build safely with test mode