Xây dựng một tích hợp từ đầu đến cuối
Hướng dẫn này sẽ đi qua mọi thứ bạn cần để chạy Your AI Connector từ mã nguồn của riêng bạn mà không cần phải mở bảng điều khiển. Đến cuối hướng dẫn, bạn sẽ xây dựng được một tích hợp tối giản có thể:
- Xác thực bằng khóa API
- Tạo một AI Agent và định cấu hình hành vi trợ lý của nó
- Kết nối kênh nhắn tin (chúng tôi sử dụng WhatsApp Web làm ví dụ minh họa) và trỏ kênh đó đến Agent
- Nhập danh bạ
- Gửi và đọc tin nhắn
- Đọc phân tích
- Đăng ký webhook cho các sự kiện thời gian thực
Mỗi bước đều có liên kết đến hướng dẫn tài nguyên đầy đủ để bạn có thể tìm hiểu chi tiết khi cần. Trang này là bản đồ; các hướng dẫn tài nguyên là lãnh thổ thực tế.
Trước khi bắt đầu. 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. Xem Truy cập API để xác nhận tính năng đã được bật và Xác thực để biết tất cả các cách truyền khóa của bạn.
Tất cả các đường dẫn bên dưới đều tương đối so với URL cơ sở:
https://api.youraiconnector.com/v1
Bước 1 — Lấy khóa API và thực hiện yêu cầu đầu tiên của bạn
Khóa API của bạn nằm trong ứng dụng tại Cài đặt → Tích hợp → Khóa API — một phần riêng biệt trong mục Tích hợp, tách biệt với Webhooks, chỉ xuất hiện khi gói dịch vụ của bạn đã bật quyền truy cập API. Hãy tạo khóa, sao chép và lưu trữ ở nơi an toàn (kho lưu trữ bí mật phía máy chủ hoặc biến môi trường — tuyệt đối không để trong mã trình duyệt). Hướng dẫn đầy đủ có trong Truy cập API.
Khi đã có khóa, hãy xác nhận nó hoạt động bằng cách gọi điểm cuối kiểm tra trạng thái (health endpoint). Có nhiều cách để gửi khóa; cách đơn giản nhất là tham số truy vấn ?apiKey=, nhưng đối với mã thực tế, hãy ưu tiên tiêu đề X-API-Key để khóa không bao giờ bị lưu vào nhật ký máy chủ hoặc lịch sử trình duyệt.
cURL
curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"
JavaScript
const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }
Python
import requests
BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json()) # { "success": true, ... }
Mỗi phản hồi thành công đều được bao bọc trong cùng một cấu trúc — một trường success: true cộng với dữ liệu kết quả. Các lỗi trả về success: false với thông báo error và error_code. Xem Lỗi & Phân trang để biết danh sách đầy đủ và cách các điểm cuối danh sách phân trang với ?limit và ?cursor.
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 (với mức trần rộng hơn là 1.200 yêu cầu/phút cho mỗi tài khoản). Nếu vượt quá, hệ thống sẽ trả về
429; hãy tạm dừng và thử lại sau.
Bước 2 — Tạo một AI Agent
Một AI Agent là đơn vị chứa hành vi của trợ lý: các hướng dẫn, mục tiêu, giờ hoạt động và cách nó trò chuyện với danh bạ. Đây là thực thể trả lời các cuộc hội thoại, vì vậy đây là bước đầu tiên tự nhiên cần thực hiện.
Tạo một Agent bằng POST /agents. name là trường duy nhất cần gửi ngay từ đầu; mọi thứ khác có thể được thiết lập bằng lệnh gọi bot-config bên dưới.
cURL
curl -X POST "https://api.youraiconnector.com/v1/agents" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Inbound WhatsApp Leads",
"language": "en"
}'
JavaScript
const res = await fetch(`${BASE}/agents`, {
method: "POST",
headers,
body: JSON.stringify({
name: "Inbound WhatsApp Leads",
language: "en",
}),
});
const { agent_id } = await res.json();
Python
res = requests.post(
f"{BASE}/agents",
headers=HEADERS,
json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]
Việc tạo thành công sẽ trả về 201 cùng với ID mới:
{
"success": true,
"agent_id": "abc123agent"
}
Lưu agent_id lại — bạn sẽ cần tham chiếu đến nó khi định tuyến các kênh.
Định cấu hình trợ lý
PUT /agents/{agentId}/bot-config thiết lập hành vi của trợ lý. Nó hợp nhất các trường bạn gửi vào cấu hình hiện có, vì vậy bất kỳ trường nào bạn bỏ qua sẽ được giữ nguyên:
curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
"goal": "Book a discovery call.",
"ai_speed": "balanced"
}'
Thiết lập giờ hoạt động bằng PUT /agents/{agentId}/active-hours để trợ lý chỉ trả lời trong giờ làm việc; ngoài khoảng thời gian đó, nó sẽ không tự động trả lời.
Cơ sở kiến thức. Để trợ lý trả lời dựa trên nội dung của riêng bạn, hãy đính kèm các câu hỏi thường gặp (FAQ). Xem Hướng dẫn về FAQ.
Di sản: các chiến dịch cổ điển. Các tài khoản vẫn còn trang Chiến dịch sẽ tạo hành vi trợ lý tương tự trên một chiến dịch thay thế (
POST /campaignsvới đối tượngtypevàbot, sau đó làPUT /campaigns/{campaignId}/bot-config). Danh sách đầy đủ các trường chiến dịch và các điều khiển vòng đời nằm trong Hướng dẫn về Chiến dịch. Nếu bạn đang xây dựng thứ gì đó mới, hãy tạo một Agent.
Bước 3 — Kết nối kênh
Một Agent cần một cách để gửi và nhận tin nhắn. Bảy luồng kết nối có thể được điều khiển từ API: WhatsApp Business, WhatsApp Web, Instagram và Messenger cùng nhau (một luồng Meta dùng chung), tài khoản cá nhân Instagram, Telegram, LINE và Viber. Các kênh còn lại — bao gồm SMS, email, tiện ích trò chuyện và các kênh tùy chỉnh — được thiết lập trong bảng điều khiển thay vì qua REST, và một khi đã kết nối, các điểm cuối về nhắn tin, danh bạ và định tuyến sẽ hoạt động trên chúng theo cùng một cách. GET /channels là nguồn dữ liệu trực tiếp cho biết những gì một tài khoản nhất định thực sự đã kết nối:
curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"
Bộ quy trình kết nối/ngắt kết nối đầy đủ cho từng kênh được ghi lại trong Hướng dẫn về Kênh. Dưới đây, chúng tôi sẽ hướng dẫn chi tiết về WhatsApp Web từ đầu đến cuối, vì nó thể hiện mô hình thú vị nhất: quy trình ghép nối bằng mã QR mà trình bao (wrapper) của bạn cần hiển thị và thăm dò.
Ví dụ thực tế: ghép nối WhatsApp Web bằng mã QR
Việc ghép nối WhatsApp Web là một quy trình gồm ba bước — bắt đầu, lấy mã QR, thăm dò cho đến khi kết nối.
1. Bắt đầu phiên ghép nối. Truyền số điện thoại bạn muốn kết nối theo định dạng E.164.
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+15551230000" }'
await fetch(`${BASE}/channels/whatsapp-web/connections`, {
method: "POST",
headers,
body: JSON.stringify({ phone_number: "+15551230000" }),
});
requests.post(
f"{BASE}/channels/whatsapp-web/connections",
headers=HEADERS,
json={"phone_number": "+15551230000"},
)
2. Lấy mã QR và hiển thị cho người dùng. Hãy thăm dò mỗi 10–15 giây. Phản hồi bao gồm payload qr_code thô (bạn hãy tự hiển thị nó dưới dạng hình ảnh QR) và một qr_data_url sẵn sàng để hiển thị.
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"
{
"success": true,
"phone_number": "+15551230000",
"status": "qr_pending",
"qr_code": "2@abc...",
"qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}
Trong giao diện người dùng của trình bao, hãy đưa qr_data_url trực tiếp vào một <img src="..."> và yêu cầu người dùng quét mã từ mục WhatsApp → Thiết bị đã liên kết trên điện thoại của họ. Nếu mã QR hết hạn (phản hồi 410), hãy bắt đầu lại từ bước 1 để lấy mã mới.
3. Thăm dò trạng thái cho đến khi kết nối thành công. Sau khi người dùng quét mã, hãy tiếp tục thăm dò endpoint trạng thái cho đến khi nó báo connected (dịch vụ cũng có thể báo open). Hãy coi disconnected và not_initialized là các lỗi kết thúc.
import time
PHONE = "+15551230000"
while True:
res = requests.get(
f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
headers=HEADERS,
)
status = res.json()["status"]
if status in ("connected", "open"):
print("Connected!")
break
if status in ("disconnected", "not_initialized"):
raise RuntimeError(f"Pairing failed: {status}")
time.sleep(5)
async function waitForConnection(phone) {
while (true) {
const res = await fetch(
`${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
{ headers }
);
const { status } = await res.json();
if (status === "connected" || status === "open") return;
if (status === "disconnected" || status === "not_initialized") {
throw new Error(`Pairing failed: ${status}`);
}
await new Promise((r) => setTimeout(r, 5000));
}
}
Lưu ý. Mỗi số WhatsApp Web được kết nối sẽ phải chịu phí duy trì hàng tháng cho đến khi bạn ngắt kết nối (
DELETE /channels/whatsapp-web/connections/{phoneNumber}).
Định tuyến kênh đến Agent của bạn
Kết nối một kênh giúp nó hoạt động; định tuyến kênh đó cho nền tảng biết AI Agent nào sẽ trả lời các cuộc hội thoại mới đến trên kênh đó. Thiết lập Điểm truy cập mặc định cho kênh, đặt tên cho Agent bạn đã tạo ở Bước 2:
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'
Lặp lại lệnh gọi cho mỗi kênh — một mặc định cho mỗi kênh. Để để lại một kênh mà không có Agent nào trả lời, hãy gọi DELETE /entry-points/channel-defaults?channel=whatsapp_web; để kiểm tra xem danh sách Điểm truy cập có đang hoạt động cho tài khoản hay không, hãy gọi GET /entry-points/routing-status. Bản đồ POST /channels/campaign cũ hơn được giữ lại chỉ để khôi phục và không còn được tham chiếu cho việc định tuyến đến. Xem Hướng dẫn về Kênh để biết các loại kênh khác và luồng OAuth của WhatsApp Business.
Bước 4 — Nhập danh bạ của bạn
Khi kênh đã hoạt động, hãy tải lên những người bạn muốn tiếp cận. Điểm cuối nhập dữ liệu chấp nhận tối đa 500 bản ghi mỗi lần gọi. Mỗi bản ghi cần có phone_number ở định dạng quốc tế; mọi thông tin khác đều là tùy chọn. Các bản ghi có số điện thoại không hợp lệ, kênh không được hỗ trợ hoặc số điện thoại đã tồn tại sẽ bị bỏ qua — và mỗi lần bỏ qua đều được báo cáo kèm theo chỉ mục và lý do, vì vậy bạn chỉ cần thử lại các bản ghi thất bại.
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{ "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
{ "phone_number": "+12025551235", "first_name": "Bob" }
],
"defaultChannel": "whatsapp_web"
}'
JavaScript
const res = await fetch(`${BASE}/contacts/import`, {
method: "POST",
headers,
body: JSON.stringify({
contacts: [
{ phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
{ phone_number: "+12025551235", first_name: "Bob" },
],
defaultChannel: "whatsapp_web",
}),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);
Python
res = requests.post(
f"{BASE}/contacts/import",
headers=HEADERS,
json={
"contacts": [
{"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
{"phone_number": "+12025551235", "first_name": "Bob"},
],
"defaultChannel": "whatsapp_web",
},
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")
Phản hồi sẽ cho bạn biết chính xác những gì đã xảy ra:
{
"success": true,
"imported": 2,
"contact_ids": ["contactId1", "contactId2"],
"skipped": []
}
Để tạo từng liên hệ một, liệt kê/tra cứu, danh sách, thẻ và các trường tùy chỉnh, hãy xem Hướng dẫn về danh bạ.
Bước 5 — Gửi và đọc tin nhắn
Gửi tin nhắn
Cách gửi đơn giản nhất là không phụ thuộc vào kênh: cung cấp danh tính của liên hệ và nội dung tin nhắn, nền tảng sẽ gửi tin nhắn đó trên bất kỳ kênh nào mà liên hệ đang sử dụng. Bạn có thể nhắm mục tiêu theo contact_id, hoặc theo channel cộng với trường danh tính khớp (phone_number cho WhatsApp/WhatsApp Web/SMS, instagram_id cho Instagram, v.v.).
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out."
}'
JavaScript
const res = await fetch(`${BASE}/contacts/send`, {
method: "POST",
headers,
body: JSON.stringify({
channel: "whatsapp_web",
phone_number: "+12025551234",
body: "Hi Ann! Thanks for reaching out.",
}),
});
const { message_id } = await res.json();
Python
res = requests.post(
f"{BASE}/contacts/send",
headers=HEADERS,
json={
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out.",
},
)
message_id = res.json()["message_id"]
Việc gửi tin nhắn là bất đồng bộ — mã 201 có nghĩa là tin nhắn đã được chấp nhận và đưa vào hàng đợi, chưa được gửi đi. (Các liên hệ đang bật chế độ không làm phiền hoặc chế độ riêng tư sẽ bị từ chối với mã 422.)
{
"success": true,
"message_id": "aB3dE5fG7hI9jK1lM2nO",
"contact_id": "contact123",
"channel": "whatsapp_web"
}
Đọc cuộc hội thoại
Để đọc lại tin nhắn, hãy liệt kê chúng theo liên hệ, tin nhắn mới nhất trước, với phân trang con trỏ. Chuyển next_cursor từ một phản hồi làm cursor cho phản hồi tiếp theo để xem lại lịch sử.
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"
res = requests.get(
f"{BASE}/contacts/contact123/messages",
headers=HEADERS,
params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
print(msg)
next_cursor = page["next_cursor"] # pass back as ?cursor= for the next page
Bạn cũng có thể lọc theo loại nội dung (?filter=text|media|tool_use) hoặc hướng tin nhắn (?direction=inbound|outbound). Hướng dẫn về tin nhắn bao gồm các tệp đính kèm phương tiện, đánh dấu tin nhắn đã đọc và chế độ xem tin nhắn theo phiên.
Đừng thăm dò (poll) để lấy phản hồi. Việc liệt kê tin nhắn theo bộ hẹn giờ có thể hoạt động, nhưng nó gây lãng phí yêu cầu và tạo độ trễ. Đối với tin nhắn đến, hãy sử dụng webhook thay thế — đó là Bước 7.
Bước 6 — Đọc dữ liệu phân tích
Khi tin nhắn đã được gửi đi, bản tóm tắt phân tích sẽ cung cấp cho bạn số liệu tổng hợp theo phạm vi ngày: đã gửi, đã chuyển phát, đã đọc, đã trả lời, đã đặt lịch, danh bạ được tạo và tín dụng đã chi tiêu/nạp thêm. Bạn sẽ nhận được cả tổng số theo phạm vi và chuỗi dữ liệu theo ngày (với giá trị bằng không nếu không có dữ liệu) — rất phù hợp cho biểu đồ trên bảng điều khiển. Bạn có thể tùy chọn giới hạn phạm vi cho một chiến dịch duy nhất bằng campaign_id (các ví dụ dưới đây sử dụng ID chiến dịch giả định, abc123campaign); hãy bỏ qua tham số này nếu muốn xem tổng số liệu cho toàn bộ tài khoản.
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"
const params = new URLSearchParams({
from: "2026-05-01",
to: "2026-05-31",
campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();
res = requests.get(
f"{BASE}/analytics/summary",
headers=HEADERS,
params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]
Phạm vi mặc định là 30 ngày gần nhất và tối đa là 366 ngày. Để xem hồ sơ sử dụng chi tiết theo từng tín dụng và bảng phân tích chi phí AI, hãy xem Hướng dẫn phân tích.
Bước 7 — Đăng ký webhook cho các sự kiện thời gian thực
Polling (thăm dò) có thể dùng cho các tập lệnh nhanh, nhưng một tích hợp thực thụ nên dựa trên cơ chế push (đẩy). Webhook cho phép nền tảng gọi đến máy chủ của bạn ngay khi có sự kiện xảy ra — một liên hệ mới, một phản hồi, một cuộc hẹn đã đặt, hoặc một cuộc trò chuyện đã kết thúc.
Trước tiên, hãy khám phá các tên sự kiện chính xác mà bạn có thể đăng ký:
curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"
{
"success": true,
"events": [
"Contact Created",
"Human Alerted",
"Appointment Booked",
"Replies",
"New Message",
"Chat Concluded",
"Task Created",
"Daily Summary Created"
]
}
Sau đó, tạo một đăng ký trỏ đến URL HTTPS trên máy chủ của bạn. Sử dụng chính xác các chuỗi sự kiện từ lệnh gọi ở trên.
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook"
}'
JavaScript
const res = await fetch(`${BASE}/webhooks`, {
method: "POST",
headers,
body: JSON.stringify({
url: "https://hooks.example.com/incoming",
subscribed_to: ["Contact Created", "Replies"],
name: "Lead updates hook",
}),
});
const { webhook_id } = await res.json();
Python
res = requests.post(
f"{BASE}/webhooks",
headers=HEADERS,
json={
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook",
},
)
webhook_id = res.json()["webhook_id"]
{
"success": true,
"webhook_id": "1",
"webhook": {
"id": "1",
"name": "Lead updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
URL phải sử dụng HTTPS và có thể truy cập công khai. Từ đây, máy chủ của bạn sẽ nhận được yêu cầu POST cho mỗi sự kiện đã đăng ký. Bạn có thể gửi thử nghiệm, kiểm tra trạng thái hoạt động của đăng ký và kích hoạt lại đăng ký đã bị tự động vô hiệu hóa sau nhiều lần thất bại — hãy xem Hướng dẫn Webhook và trang Webhook ở cấp độ tích hợp để biết cấu trúc payload và cách xác thực.
Tổng kết mọi thứ
Dưới đây là sơ lược toàn bộ quy trình:
| Bước | Mục tiêu | Lệnh gọi chính |
|---|---|---|
| 1 | Xác thực | GET /health |
| 2 | Tạo + tinh chỉnh trợ lý | POST /agents, PUT /agents/{id}/bot-config, PUT /agents/{id}/active-hours |
| 3 | Kết nối kênh và định tuyến | POST /channels/whatsapp-web/connections → quét mã QR + trạng thái → PUT /entry-points/channel-defaults |
| 4 | Tải danh bạ | POST /contacts/import |
| 5 | Gửi & đọc | POST /contacts/send, GET /contacts/{id}/messages |
| 6 | Đo lường | GET /analytics/summary |
| 7 | Phản hồi theo thời gian thực | POST /webhooks |
Một trình bao bọc tối thiểu chỉ cần bảy lệnh gọi này được kết nối vào giao diện của riêng bạn. Từ đó, hãy thêm các hướng dẫn theo từng tài nguyên khi bạn cần nhiều tính năng hơn:
- Chiến dịch · Danh bạ · Câu hỏi thường gặp · Tin nhắn · Cuộc hẹn
- Kênh · Mẫu · Phân tích · Webhook · Khóa API
- Bạn mới bắt đầu? Bắt đầu · Xác thực · Lỗi & Phân trang
Stuck on something this guide does not cover? Email hi@youraiconnector.com.