Mabilis na Pagsisimula ng SDK: TypeScript at Python

Nagbibigay ang Ody ng opisyal na TypeScript at Python SDKs na sumasaklaw sa buong REST API — mga contact, pag-uusap, mensahe (na may idempotent na pagpapadala), outbound AI calls, paghahanap at pagbili ng numero, 10DLC registration, iyong AI agent, at pamamahala ng webhook, kasama ang isang built-in na Standard-Webhooks signature verifier.

Bago ka magsimula

• Kailangan mo ng API key — tingnan ang Kunin ang iyong Ody API key. Gumamit ng ody_test_… key habang nagde-develop upang ang mga pagpapadala ay ma-simulate (Bumuo nang ligtas gamit ang test mode).
• Hindi pa na-publish ang alinman sa mga package sa isang registry. I-install ang pareho mula sa sdks/ directory ng ody-platform repo; kapag na-publish na, magiging @ody/sdk (npm) at ody-sdk (PyPI) sila.

TypeScript (@ody/sdk)

Nangangailangan ng Node 18+ (gumagana rin sa mga browser, Deno, at Bun — ginagamit nito ang global fetch at walang runtime dependencies). Buuin at i-install mula sa 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!);

// Mga Contact — gumawa, maghanap, at awtomatikong mag-paginate (sinusundan ang nextCursor para sa iyo)
const contact = await ody.contacts.create({ firstName: "Ada", phone: "+15125550123" });
for await (const c of ody.contacts.listAll()) console.log(c.id, c.firstName);

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

// Magpadala ng SMS — idempotent, ligtas na subukang muli gamit ang parehong key sa loob ng 24h
const sent = await ody.messages.send({
  to: "+15125550123",
  body: "Your order shipped!",
  idempotencyKey: "order-1042-shipped",
});

// Ang mga error ay may type
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)

Nangangailangan ng Python ≥ 3.9, standard library lamang. I-install mula sa 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_...")

# Mga Contact — gumawa, maghanap, at awtomatikong mag-paginate
contact = client.contacts.create(first_name="Ada", phone="+15125550123")
for c in client.contacts.list_all():
    print(c["id"], c["firstName"])

# Magpadala ng SMS — idempotent, ligtas na subukang muli gamit ang parehong key sa loob ng 24h
sent = client.messages.send(
    to="+15125550123",
    body="Your order shipped!",
    idempotency_key="order-1042-shipped",
)

# Ang mga error ay may type
try:
    client.contacts.get("00000000-0000-0000-0000-000000000000")
except OdyError as err:
    print(err.code, err.status, err.request_id)

Ano ang saklaw ng parehong SDK

Group	Methods
Mga Contact	list, listAll/list_all, create, get, update, delete
Mga Pag-uusap	list, listAll/list_all, get, setStatus/set_status
Mga Mensahe	send (with idempotency key), search
Mga Tawag	list, place (outbound AI call)
Mga Numero	list, searchAvailable/search_available, buy (with idempotency key), connectAgent/connect_agent, disconnectAgent/disconnect_agent
Pagmemensahe (10DLC)	status, register, refresh
Ahente	get, update, publish
Mga Webhook	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

Ang pareho ay nagbibigay din ng webhook signature verifier — verifyWebhookSignature (TypeScript, Node servers lamang) at verify_webhook_signature (Python) — na may constant-time comparison at 5-minutong replay guard. Ipasa ang raw body bytes, hindi parsed JSON. Tingnan ang Tumanggap ng mga webhook at i-verify ang mga signature para sa buong daloy.

Ang mga pamamaraan ng numbers, messaging, agent, at calls.place (halimbawa ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — snake_case sa Python) ay sumasaklaw sa parehong phone-line surface gaya ng REST API. Tingnan ang Bumili ng mga numero at magrehistro ng texting sa pamamagitan ng API at Tumawag gamit ang AI at pamahalaan ang Astra sa pamamagitan ng API.

Sa isang 429, ipinapakita ng parehong SDK ang halaga ng Retry-After (err.retryAfter / err.retry_after) — igalang ito, ayon sa Mga limitasyon ng rate ng API at pinakamahusay na kasanayan.

Mga Kaugnay na Artikulo

• Pangkalahatang-ideya ng API at authentication
• Tumanggap ng mga webhook at i-verify ang mga signature
• Pagination, idempotency, at paghawak ng error
• Bumuo nang ligtas gamit ang test mode