Inicio rápido del SDK: TypeScript y Python

Ody ofrece SDK oficiales de TypeScript y Python que cubren la API REST completa: contactos, conversaciones, mensajes (con envíos idempotentes), llamadas de IA salientes, búsqueda y compra de números, registro 10DLC, su agente de IA y gestión de webhooks, además de un verificador de firmas de Standard-Webhooks incorporado.

Antes de empezar

• Necesita una clave API; consulte Obtenga su clave API de Ody. Use una clave ody_test_… durante el desarrollo para que los envíos sean simulados (Construya de forma segura con el modo de prueba).
• Ningún paquete ha sido publicado en un registro todavía. Instale ambos desde el directorio sdks/ del repositorio ody-platform; una vez publicados, serán @ody/sdk (npm) y ody-sdk (PyPI).

TypeScript (@ody/sdk)

Requiere Node 18+ (también funciona en navegadores, Deno y Bun — usa el fetch global y no tiene dependencias en tiempo de ejecución). Compile e instale desde el repositorio:

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)

Requiere Python ≥ 3.9, solo biblioteca estándar. Instale desde el repositorio:

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)

Qué cubren ambos SDK

Grupo	Métodos
Contactos	list, listAll/list_all, create, get, update, delete
Conversaciones	list, listAll/list_all, get, setStatus/set_status
Mensajes	send (con clave de idempotencia), search
Llamadas	list, place (llamada de IA saliente)
Números	list, searchAvailable/search_available, buy (con clave de idempotencia), connectAgent/connect_agent, disconnectAgent/disconnect_agent
Mensajería (10DLC)	status, register, refresh
Agente	get, update, publish
Webhooks	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

Ambos también incluyen un verificador de firmas de webhook — verifyWebhookSignature (TypeScript, solo servidores Node) y verify_webhook_signature (Python) — con comparación de tiempo constante y una protección de repetición de 5 minutos. Pase los bytes del cuerpo sin procesar, no el JSON analizado. Consulte Reciba webhooks y verifique firmas para el flujo completo.

Los métodos de números, mensajería, agente y calls.place (por ejemplo, ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — snake_case en Python) cubren la misma superficie de línea telefónica que la API REST. Consulte Compre números y registre mensajes de texto a través de la API y Realice llamadas de IA y administre Astra a través de la API.

En un 429, ambos SDK muestran el valor Retry-After (err.retryAfter / err.retry_after) — respételo, según Límites de tasa de la API y mejores prácticas.

Artículos relacionados

• Descripción general de la API y autenticación
• Reciba webhooks y verifique firmas
• Paginación, idempotencia y manejo de errores
• Construya de forma segura con el modo de prueba