SDK快速入门：TypeScript和Python

Ody提供官方的TypeScript和Python SDK，涵盖完整的REST API — 联系人、对话、消息（带幂等发送）、出站AI电话、号码搜索和购买、10DLC注册、您的AI代理以及Webhook管理，此外还内置了标准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
Webhooks	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

两者都附带一个Webhook签名验证器 — verifyWebhookSignature（TypeScript，仅限Node服务器）和verify_webhook_signature（Python）— 具有常数时间比较和5分钟重放保护。传递原始请求体字节，而不是解析后的JSON。请参阅接收Webhooks并验证签名以了解完整流程。

号码、消息、代理和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概述和认证
• 接收Webhooks并验证签名
• 分页、幂等性和错误处理
• 使用测试模式安全构建