Démarrage rapide du SDK : TypeScript et Python

Ody propose des SDK officiels TypeScript et Python couvrant l'intégralité de l'API REST — contacts, conversations, messages (avec envois idempotents), appels IA sortants, recherche et achat de numéros, enregistrement 10DLC, votre agent IA et gestion des webhooks, ainsi qu'un vérificateur de signature Standard-Webhooks intégré.

Avant de commencer

• Vous avez besoin d'une clé API — voir Obtenir votre clé API Ody. Utilisez une clé ody_test_… pendant le développement afin que les envois soient simulés (Développer en toute sécurité avec le mode test).
• Aucun des deux packages n'est encore publié sur un registre. Installez-les tous les deux depuis le répertoire sdks/ du dépôt ody-platform ; une fois publiés, ils seront @ody/sdk (npm) et ody-sdk (PyPI).

TypeScript (@ody/sdk)

Nécessite Node 18+ (fonctionne également dans les navigateurs, Deno et Bun — il utilise le fetch global et n'a aucune dépendance d'exécution). Construisez et installez depuis le dépôt :

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)

Nécessite Python ≥ 3.9, bibliothèque standard uniquement. Installez depuis le dépôt :

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)

Ce que les deux SDK couvrent

Groupe	Méthodes
Contacts	list, listAll/list_all, create, get, update, delete
Conversations	list, listAll/list_all, get, setStatus/set_status
Messages	send (avec clé d'idempotence), search
Appels	list, place (appel IA sortant)
Numéros	list, searchAvailable/search_available, buy (avec clé d'idempotence), connectAgent/connect_agent, disconnectAgent/disconnect_agent
Messagerie (10DLC)	status, register, refresh
Agent	get, update, publish
Webhooks	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

Les deux incluent également un vérificateur de signature de webhook — verifyWebhookSignature (TypeScript, serveurs Node uniquement) et verify_webhook_signature (Python) — avec une comparaison à temps constant et une protection contre la relecture de 5 minutes. Passez les octets bruts du corps, pas le JSON analysé. Voir Recevoir des webhooks et vérifier les signatures pour le flux complet.

Les méthodes de numéros, de messagerie, d'agent et calls.place (par exemple ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — snake_case en Python) couvrent la même surface de ligne téléphonique que l'API REST. Voir Acheter des numéros et enregistrer la messagerie via l'API et Passer des appels IA et gérer Astra via l'API.

En cas de 429, les deux SDK exposent la valeur Retry-After (err.retryAfter / err.retry_after) — respectez-la, conformément aux Limites de débit de l'API et bonnes pratiques.

Articles connexes

• Présentation de l'API et authentification
• Recevoir des webhooks et vérifier les signatures
• Pagination, idempotence et gestion des erreurs
• Développer en toute sécurité avec le mode test