# 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. ::: note **Lưu ý:** Các trang này được viết dành cho nhà phát triển. Nếu bạn không phải là nhà phát triển, hãy chia sẻ phần này với đội ngũ kỹ thuật của bạ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: ```json { "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](../integrations/api-access.md) — 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. | Phương thức | Cách thực hiện | Phù hợp nhất cho | |---|---|---| | Tham số truy vấn | `?apiKey=YOUR_API_KEY` | Kiểm tra nhanh, URL trình duyệt, thiết lập cũ | | Header | `X-API-Key: YOUR_API_KEY` | Tích hợp trong môi trường sản xuất | | Bearer header | `Authorization: Bearer YOUR_API_KEY` | Tích hợp trong môi trường sản xuất | | Mã thông báo ID Firebase | `Authorization: Bearer ` | Chỉ dành cho các phiên ứng dụng bên thứ nhất | Đố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](authentication.md) để 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** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```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** ```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: ```json { "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.): ```json { "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: ```json { "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](errors-and-pagination.md) để 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`: ```json { "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](api-keys.md). --- ## 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ài nguyên | Nội dung bao gồm | |---|---| | [AI Agents](agents.md) | Tạo và cấu hình AI Agents: cài đặt, giờ hoạt động, kiến thức, quy tắc gắn thẻ, công cụ, phương tiện và bản nháp | | [Entry Points](entry-points.md) | Quyết định AI Agent nào sẽ trả lời một cuộc hội thoại mới: mặc định kênh, một Agent cho mỗi số WhatsApp, từ khóa, bình luận và quy tắc người theo dõi | | [Broadcasts](broadcasts.md) | Tạo, định giá, khởi chạy, tạm dừng và sao chép các tin nhắn gửi một lần tới danh sách liên hệ | | [Campaigns](campaigns.md) | Tạo, cập nhật, sao chép, kích hoạt, lưu trữ và kiểm tra các chiến dịch cùng cấu hình bot của chúng | | [Contacts](contacts.md) | Tạo, tra cứu, liệt kê, cập nhật, nhập, gắn thẻ và xóa liên hệ | | [FAQs](faqs.md) | Quản lý các mục hỏi đáp mà trợ lý AI của bạn sử dụng và liên kết chúng với các chiến dịch | | [Knowledge Base](knowledge-base.md) | Nhập trang web và tài liệu vào kiến thức của AI và nhóm các FAQ thành các danh mục | | [Tasks](tasks.md) | Tạo và quản lý các tác vụ CRM, giai đoạn trên bảng và loại tác vụ | | [Messages](messages.md) | Gửi tin nhắn đi và đọc lịch sử hội thoại | | [Appointments](appointments.md) | Đặt lịch, đổi lịch, hủy và xóa các cuộc hẹn | | [Channels](channels.md) | Kết nối và ngắt kết nối các kênh nhắn tin, mua số điện thoại và thiết lập AI Agent nào sẽ trả lời các cuộc hội thoại mới trên mỗi kênh | | [Templates](templates.md) | Tạo, gửi và kiểm tra trạng thái phê duyệt của các mẫu tin nhắn WhatsApp | | [Analytics](analytics.md) | Đọc số liệu thống kê sự kiện tin nhắn hàng ngày, mức sử dụng tín dụng và tổng hợp chi phí AI | | [Webhooks](webhooks.md) | Đăng ký các điểm cuối để nhận thông báo sự kiện theo thời gian thực | | [Team](team.md) | Quản lý thành viên nhóm, lời mời, vai trò, quyền hạn và phòng ban | | [API Keys](api-keys.md) | Kiểm tra, xoay vòng và thu hồi khóa API của bạn, kiểm tra mức sử dụng giới hạn tốc độ và tạo các khóa bổ sung với quyền truy cập hạn chế | ### 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](reference.md). Mỗi mục đều có hướng dẫn riêng: [AI Agents](agents.md), [Entry Points](entry-points.md) và [Broadcasts](broadcasts.md). --- ## Đọ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](authentication.md) — 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](errors-and-pagination.md) — xử lý lỗi và phân trang kết quả. - [Truy cập API](../integrations/api-access.md) — tạo khóa của bạn và xem các ví dụ thực tế.