Bắt đầu nhanh với SDK: TypeScript và Python

Ody cung cấp các SDK TypeScript và Python chính thức bao gồm toàn bộ REST API — danh bạ, cuộc hội thoại, tin nhắn (với các lần gửi không trùng lặp), cuộc gọi AI đi, tìm kiếm và mua số điện thoại, đăng ký 10DLC, tổng đài viên AI của bạn và quản lý webhook, cùng với trình xác minh chữ ký Standard-Webhooks tích hợp.

Trước khi bạn bắt đầu

• Bạn cần có khóa API — xem Lấy khóa API Ody của bạn. Sử dụng khóa ody_test_… trong quá trình phát triển để các lần gửi được mô phỏng (Xây dựng an toàn với chế độ thử nghiệm).
• Cả hai gói đều chưa được xuất bản lên kho lưu trữ. Cài đặt cả hai từ thư mục sdks/ của kho lưu trữ ody-platform; sau khi được xuất bản, chúng sẽ là @ody/sdk (npm) và ody-sdk (PyPI).

TypeScript (@ody/sdk)

Yêu cầu Node 18+ (cũng hoạt động trong trình duyệt, Deno và Bun — nó sử dụng fetch toàn cục và không có phụ thuộc thời gian chạy nào). Xây dựng và cài đặt từ kho lưu trữ:

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

// Danh bạ — tạo, tìm kiếm và tự động phân trang (tự động theo dõi nextCursor cho bạn)
const contact = await ody.contacts.create({ firstName: "Ada", phone: "+15125550123" });
for await (const c of ody.contacts.listAll()) console.log(c.id, c.firstName);

// Cuộc hội thoại
const open = await ody.conversations.list({ status: "open" });
await ody.conversations.setStatus(open.conversations[0].id, "done");

// Gửi một tin nhắn SMS — không trùng lặp, an toàn để thử lại với cùng một khóa trong 24h
const sent = await ody.messages.send({
  to: "+15125550123",
  body: "Đơn hàng của bạn đã được vận chuyển!",
  idempotencyKey: "order-1042-shipped",
});

// Lỗi được định kiểu
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)

Yêu cầu Python ≥ 3.9, chỉ thư viện chuẩn. Cài đặt từ kho lưu trữ:

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

# Danh bạ — tạo, tìm kiếm và tự động phân trang
contact = client.contacts.create(first_name="Ada", phone="+15125550123")
for c in client.contacts.list_all():
    print(c["id"], c["firstName"])

# Gửi một tin nhắn SMS — không trùng lặp, an toàn để thử lại với cùng một khóa trong 24h
sent = client.messages.send(
    to="+15125550123",
    body="Đơn hàng của bạn đã được vận chuyển!",
    idempotency_key="order-1042-shipped",
)

# Lỗi được định kiểu
try:
    client.contacts.get("00000000-0000-0000-0000-000000000000")
except OdyError as err:
    print(err.code, err.status, err.request_id)

Những gì cả hai SDK bao gồm

Nhóm	Phương thức
Danh bạ	list, listAll/list_all, create, get, update, delete
Cuộc hội thoại	list, listAll/list_all, get, setStatus/set_status
Tin nhắn	send (với khóa không trùng lặp), search
Cuộc gọi	list, place (cuộc gọi AI đi)
Số điện thoại	list, searchAvailable/search_available, buy (với khóa không trùng lặp), connectAgent/connect_agent, disconnectAgent/disconnect_agent
Nhắn tin (10DLC)	status, register, refresh
Tổng đài viên AI	get, update, publish
Webhooks	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

Cả hai cũng cung cấp trình xác minh chữ ký webhook — verifyWebhookSignature (TypeScript, chỉ máy chủ Node) và verify_webhook_signature (Python) — với so sánh thời gian không đổi và bảo vệ chống phát lại 5 phút. Truyền byte nội dung thô, không phải JSON đã phân tích cú pháp. Xem Nhận webhook và xác minh chữ ký để biết quy trình đầy đủ.

Các phương thức số điện thoại, nhắn tin, tổng đài viên AI và calls.place (ví dụ: ody.numbers.searchAvailable, ody.numbers.buy, ody.messaging.register, ody.agent.update, ody.agent.publish, ody.calls.place — snake_case trong Python) bao gồm cùng một bề mặt đường dây điện thoại như REST API. Xem Mua số điện thoại và đăng ký nhắn tin qua API và Thực hiện cuộc gọi AI và quản lý Astra qua API.

Khi gặp lỗi 429, cả hai SDK đều hiển thị giá trị Retry-After (err.retryAfter / err.retry_after) — hãy tuân thủ nó, theo Giới hạn tốc độ API và các phương pháp hay nhất.

Các bài viết liên quan

• Tổng quan API và xác thực
• Nhận webhook và xác minh chữ ký
• Phân trang, tính không trùng lặp và xử lý lỗi
• Xây dựng an toàn với chế độ thử nghiệm