Bắt đầu với API #

REST API của Your AI Connector cho phép bạn xây dựng tích hợp riêng trên tài khoản của mình. Bạn có thể tạo và tra cứu liên hệ, quản lý chiến dịch, câu hỏi thường gặp (FAQ), tác vụ và cuộc hẹn, gửi tin nhắn, đăng ký webhook, đọc phân tích và kết nối các kênh nhắn tin — mọi thứ mà bảng điều khiển thực hiện đều có thể được điều khiển bằng mã.

Đây là trang trung tâm cho tài liệu API. Nếu bạn đang kết nối Your AI Connector với một công cụ đã có sẵn tích hợp, có thể bạn sẽ không cần dùng đến API. API dành cho các tích hợp tùy chỉnh và tự động hóa ở quy mô lớn.

URL Cơ sở #

Mọi yêu cầu đều được gửi đến cùng một địa chỉ web cơ sở và tất cả các đường dẫn trong tài liệu này đều tương ứng với địa chỉ đó:

https://api.youraiconnector.com/v1

Vì vậy, điểm cuối (endpoint) chiến dịch là https://api.youraiconnector.com/v1/campaigns, điểm cuối liên hệ là https://api.youraiconnector.com/v1/contacts, v.v.

Tất cả các yêu cầu phải sử dụng kết nối bảo mật (HTTPS). Các yêu cầu HTTP thông thường sẽ bị từ chối.

Nhận khóa API #

Quyền truy cập API là một tính năng trả phí. Nếu gói của bạn không bao gồm tính năng này, mọi yêu cầu sẽ trả về 403 với nội dung sau:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Sau khi quyền truy cập API được bật trên gói của bạn, hãy tạo khóa từ bảng điều khiển. Các bước chi tiết có trong Truy cập API — tóm tắt: đi tới Cài đặt → Tích hợp → Khóa API để tạo hoặc tạo lại khóa của bạn. Khóa API là một phần riêng biệt trong mục Tích hợp, tách biệt với Webhooks, và nó chỉ xuất hiện khi quyền truy cập API đã được bật trên gói của bạn. Hãy bảo mật khóa như mật khẩu: nó cấp toàn quyền truy cập vào tài khoản của bạn.

Xác thực #

Bạn có thể gửi khóa API của mình theo bốn cách. Tất cả đều hoạt động trên mọi điểm cuối chấp nhận xác thực bằng khóa API.

Đối với môi trường sản xuất, hãy ưu tiên sử dụng một trong các dạng header để khóa của bạn không bao giờ bị lưu trong nhật ký máy chủ hoặc lịch sử trình duyệt. Dạng tham số truy vấn luôn hoạt động và là cách đơn giản nhất để kiểm tra nhanh.

Xem Xác thực để biết phân tích đầy đủ về từng phương thức, kèm theo ví dụ và hướng dẫn về thời điểm sử dụng phương thức nào.

Yêu cầu đầu tiên của bạn #

Dưới đây là một lệnh gọi hoàn chỉnh, hoạt động để liệt kê các chiến dịch trong tài khoản của bạn. Nó sử dụng khóa API của bạn và trả về các chiến dịch gần đây nhất trước.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Một phản hồi thành công sẽ trông như thế này:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Phản hồi thành công và lỗi #

Mỗi phản hồi JSON đều chứa một cờ success để bạn có thể phân nhánh dựa trên đó mà không cần phân tích mã trạng thái.

Một phản hồi thành công là success: true cộng với dữ liệu cho điểm cuối đó (tên trường thay đổi — campaigns, contacts, data, v.v.):

{
  "success": true,
  "campaigns": []
}

Một phản hồi thất bại là success: false với thông báo error dễ đọc và mã error_code dạng số khớp với trạng thái HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Luôn kiểm tra success (hoặc trạng thái HTTP) trước khi đọc dữ liệu. Xem Lỗi & Phân trang để biết bảng mã trạng thái đầy đủ và cách phân trang qua các tập kết quả lớn.

Giới hạn tốc độ #

Các yêu cầu đã xác thực được giới hạn ở mức 300 yêu cầu mỗi phút cho mỗi khóa API. Ngoài ra còn có một giới hạn rộng hơn là 1.200 yêu cầu mỗi phút cho mỗi tài khoản, tính trên mọi yêu cầu đã xác thực được thực hiện cho tài khoản đó.

Nếu bạn vượt quá một trong hai giới hạn này, bạn sẽ nhận được phản hồi 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Hãy tạm dừng và thử lại sau một khoảng thời gian ngắn. Bạn cũng có thể kiểm tra mức sử dụng hiện tại của mình bất kỳ lúc nào với GET https://api.youraiconnector.com/v1/api-keys/usage, lệnh này trả về số lượng yêu cầu bạn đã sử dụng trong cửa sổ hiện tại và thời điểm nó đặt lại — rất hữu ích để xây dựng tính năng điều tiết phía máy khách. Xem Khóa API.

Hướng dẫn về tài nguyên #

Các nhóm tài nguyên dưới đây đều có hướng dẫn riêng với các đường dẫn, trường yêu cầu và cấu trúc phản hồi chính xác.

Tác nhân (Agents), Điểm truy cập và Phát sóng #

AI Agents, Entry Points và Broadcasts đều có trong đặc tả OpenAPI đã xuất bản, vì vậy bạn có thể duyệt qua các trường chính xác của chúng và chạy các yêu cầu trực tiếp trong API explorer. Mỗi mục đều có hướng dẫn riêng: AI Agents, Entry Points và Broadcasts.

Đọc các tài liệu này dưới dạng Markdown #

Mỗi trang trong tài liệu này đều có một phiên bản Markdown thuần túy: hãy lấy địa chỉ trang và thêm /index.md vào cuối. Vì vậy, trang này cũng có sẵn tại https://docs.youraiconnector.com/api/getting-started/index.md, và nó sẽ trả về dưới dạng văn bản thuần thay vì một trang web — rất hữu ích khi bạn muốn dán một trang vào trợ lý AI hoặc đưa nó vào một tập lệnh.

Để xem toàn bộ tập hợp, hãy bắt đầu từ https://docs.youraiconnector.com/sitemap.xml, nơi liệt kê mọi trang mà chúng tôi xuất bản. Lưu ý rằng tài liệu này cố tình không được đưa vào các công cụ tìm kiếm, vì vậy việc truy cập trực tiếp vào các địa chỉ này là cách để tiếp cận nó từ mã nguồn.

Hiện chưa có điểm cuối tài liệu được bảo vệ bằng khóa và chưa có tính năng tải xuống hàng loạt — các phiên bản Markdown và sơ đồ trang web là toàn bộ giao diện, và không cái nào trong số đó cần khóa API.

Các bước tiếp theo #

• Xác thực — chọn phương thức xác thực phù hợp cho tích hợp của bạn.
• Lỗi & Phân trang — xử lý lỗi và phân trang kết quả.
• Truy cập API — tạo khóa của bạn và xem các ví dụ thực tế.