Tổng quan về API và xác thực

Ody REST API nằm tại https://api.ody.co/v1/api và xác thực mọi yêu cầu bằng khóa API được gửi dưới dạng mã thông báo Bearer — hãy tạo một khóa trong Cài đặt → API nhà phát triển, sau đó gọi các điểm cuối bên dưới.

Xác thực

Gửi khóa của bạn trong tiêu đề Authorization trên mỗi yêu cầu:

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• Khóa có hai chế độ: khóa ody_live_… là khóa trực tiếp, khóa ody_test_… hoạt động giống hệt nhưng việc gửi tin nhắn được mô phỏng (được ghi lại với deliveryStatus: "simulated", không bao giờ được truyền đi). Xem Xây dựng an toàn với chế độ thử nghiệm.
• Khóa bị thiếu, không hợp lệ hoặc bị thu hồi sẽ trả về 401 unauthenticated.
• Khóa bị giới hạn bởi phạm vi sẽ trả về 403 permission_denied — nêu tên phạm vi bị thiếu — khi nó gọi một điểm cuối nằm ngoài quyền được cấp.
• Mọi cuộc gọi đều chạy với quyền của thành viên đã tạo khóa, chỉ trong không gian làm việc đó.

Điểm cuối

Phương thức & đường dẫn	Chức năng	Phạm vi yêu cầu
GET /v1/api/contacts	Liệt kê hoặc tìm kiếm danh bạ (?q=, phân trang)	contacts:read
POST /v1/api/contacts	Tạo danh bạ	contacts:write
GET /v1/api/contacts/:id	Lấy chi tiết đầy đủ của danh bạ	contacts:read
PATCH /v1/api/contacts/:id	Cập nhật danh bạ (chỉ các trường được cung cấp thay đổi)	contacts:write
DELETE /v1/api/contacts/:id	Xóa danh bạ	contacts:write
GET /v1/api/conversations	Liệt kê cuộc trò chuyện (?status=open|done, phân trang)	conversations:read
GET /v1/api/conversations/:id	Lấy toàn bộ chuỗi tin nhắn	conversations:read
PATCH /v1/api/conversations/:id	Đặt trạng thái — nội dung {"status":"open"} hoặc {"status":"done"}	conversations:write
POST /v1/api/messages	Gửi SMS/MMS (hỗ trợ Idempotency-Key)	messages:send
GET /v1/api/messages/search	Tìm kiếm nội dung tin nhắn và bản ghi (?q=)	conversations:read
GET /v1/api/calls	Liệt kê lịch sử cuộc gọi & thư thoại	conversations:read
POST /v1/api/calls	Thực hiện cuộc gọi AI đi — trợ lý đã xuất bản của bạn gọi	calls:place
GET /v1/api/numbers	Liệt kê các số điện thoại của không gian làm việc của bạn	numbers:read
GET /v1/api/numbers/available	Tìm kiếm số điện thoại bạn có thể mua (?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=)	numbers:manage
POST /v1/api/numbers	Mua số điện thoại — được tính phí như mua hàng trong ứng dụng (hỗ trợ Idempotency-Key)	numbers:manage
POST /v1/api/numbers/:e164/connect và …/disconnect	Định tuyến số điện thoại đến hoặc đi khỏi trợ lý AI của bạn	agent:manage
GET /v1/api/messaging	Trạng thái đăng ký 10DLC (step, canText)	numbers:manage
POST /v1/api/messaging/registration	Gửi doanh nghiệp + chiến dịch 10DLC của bạn (có tính phí)	numbers:manage
POST /v1/api/messaging/refresh	Kiểm tra lại và đẩy nhanh quá trình xem xét 10DLC của nhà mạng	numbers:manage
GET/PATCH /v1/api/agent	Đọc hoặc cập nhật cấu hình trợ lý AI của bạn (bản nháp)	agent:manage
POST /v1/api/agent/publish	Đẩy cấu hình trợ lý của bạn lên trực tiếp	agent:manage
GET /v1/api/webhook-events	Liệt kê các loại sự kiện webhook có thể đăng ký	webhooks:manage
GET/POST /v1/api/webhooks và /v1/api/webhooks/:id…	Quản lý các điểm cuối webhook đi	webhooks:manage
GET /v1/api/openapi.json	Thông số kỹ thuật OpenAPI 3.1	none

Các điểm cuối liệt kê được phân trang bằng ?limit= và ?cursor= — xem Phân trang, tính bất biến và xử lý lỗi.

Danh bạ

POST /v1/api/contacts cần ít nhất một trường nhận dạng: firstName, lastName, company, số điện thoại hoặc email. Số điện thoại và email chấp nhận một chuỗi đơn giản ("phone": "+15125550123") hoặc các mảng được gắn nhãn đầy đủ ("phones": [{"value": "+15125550123", "label": "work"}]). Khi PATCH, chỉ các trường bạn cung cấp thay đổi; phones, emails, notes, properties và tags được thay thế hoàn toàn khi được cung cấp.

Gửi tin nhắn

POST /v1/api/messages chấp nhận conversationId hiện có hoặc số điện thoại người nhận trong to (định dạng E.164). Với to, Ody chọn số gửi của không gian làm việc của bạn (hoặc tôn trọng from mà bạn sở hữu), tạo cuộc trò chuyện nếu cần và xâu chuỗi tin nhắn. Thêm tối đa 10 mediaUrls có thể truy xuất công khai cho MMS:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

Một không gian làm việc không có số điện thoại đang hoạt động sẽ nhận được 409 failed_precondition. Các lần thử lại với cùng Idempotency-Key trong vòng 24 giờ sẽ phát lại phản hồi đầu tiên thay vì gửi hai lần.

Số điện thoại, nhắn tin, cuộc gọi AI và trợ lý của bạn

API cũng có thể vận hành một đường dây điện thoại từ đầu đến cuối: tìm kiếm và mua số điện thoại, đăng ký nhắn tin 10DLC, cấu hình và xuất bản trợ lý AI của bạn, định tuyến số điện thoại đến đó và thực hiện cuộc gọi AI đi. Các điểm cuối này sử dụng ba phạm vi riêng — numbers:manage (Mua số điện thoại & 10DLC), calls:place (Thực hiện cuộc gọi AI), và agent:manage (Quản lý trợ lý AI) — và mọi thứ chúng làm đều được ghi vào tài khoản của bạn chính xác như thể bạn đã thực hiện trong ứng dụng, với cùng các quy tắc và cách tính phí. 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.

Lỗi, ID yêu cầu và giới hạn tốc độ

Mọi lỗi đều sử dụng một cấu trúc đồng nhất, và mọi phản hồi (thành công hoặc lỗi) đều mang tiêu đề X-Request-Id — hãy trích dẫn nó khi bạn liên hệ hỗ trợ:

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

Mỗi khóa nhận được 600 yêu cầu/phút với các tiêu đề RateLimit-* tiêu chuẩn. Chi tiết trong Giới hạn tốc độ API và các phương pháp hay nhất và Phân trang, tính bất biến và xử lý lỗi.

Bài viết liên quan

• Lấy khóa API Ody của bạn
• Nhận webhook và xác minh chữ ký
• Phân trang, tính bất biến và xử lý lỗi
• Bắt đầu nhanh SDK: TypeScript và Python