API Kết nối Kênh #

Hướng dẫn này chỉ cho bạn cách kết nối các kênh nhắn tin với một tài khoản bằng cách sử dụng API. Tài liệu này được viết cho các nhà phát triển đang xây dựng một tích hợp hoặc wrapper, vì vậy nó tập trung vào các yêu cầu chính xác, thứ tự thực hiện và các phản hồi mà bạn nhận được.

Có một mô hình bạn cần hiểu ngay từ đầu, vì nó áp dụng cho hầu hết mọi kênh ở đây.

Mô hình kết nối rồi thăm dò (connect-then-poll) #

Hầu hết các kênh không thể được kết nối chỉ bằng một lệnh gọi API duy nhất. Việc kết nối WhatsApp, Instagram hoặc Messenger đồng nghĩa với việc chủ tài khoản phải đăng nhập vào tài khoản nhà cung cấp của họ và phê duyệt quyền truy cập. Không có con đường headless (tự động hoàn toàn) nào cho việc phê duyệt đó - một người thật phải mở URL trong trình duyệt hoặc quét mã QR bằng điện thoại của họ.

Vì vậy, quy trình luôn là:

1. Bắt đầu kết nối với POST. Phản hồi sẽ cung cấp cho bạn một URL để mở hoặc một mã QR để hiển thị.
2. Chuyển giao cho người dùng cuối - mở URL trong trình duyệt của họ hoặc hiển thị mã QR trên màn hình để họ quét.
3. Thăm dò điểm cuối trạng thái với GET trong một khoảng thời gian ngắn (vài giây một lần) cho đến khi trạng thái đạt đến trạng thái đã kết nối.

Công việc của tích hợp của bạn là điều khiển vòng lặp đó: hiển thị URL hoặc mã QR, sau đó thăm dò cho đến khi hoàn tất. Hãy lên kế hoạch cho giao diện người dùng của bạn xung quanh việc thăm dò - một vòng xoay tải với thông báo “đang chờ bạn hoàn tất trong trình duyệt” sẽ hoạt động hiệu quả.

Instagram + Messenger (Meta) #

Instagram và Messenger được kết nối cùng nhau trong một quy trình, vì cả hai đều chạy trên một Trang Facebook. Chủ tài khoản ủy quyền thông qua Facebook, bạn tìm nạp danh sách các Trang mà họ quản lý và bạn chọn Trang nào để kết nối.

Bước 1 - Bắt đầu kết nối Instagram + Messenger #

POST /channels/meta/connect

Thao tác này trả về một URL đồng ý. Không có thông tin xác thực nào được gửi trong yêu cầu này - kết nối được ủy quyền hoàn toàn trong trình duyệt.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Phản hồi

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Mở oauth_url trong trình duyệt của người dùng cuối để họ có thể đăng nhập vào Facebook và phê duyệt quyền truy cập. Nỗ lực kết nối sẽ hết hạn tại expires_at (khoảng 30 phút) - nếu hết hạn, hãy bắt đầu lại. Hãy coi state_token là một bí mật tồn tại trong thời gian ngắn và không ghi nhật ký nó.

Tùy chọn dễ dàng nhất cho Instagram + Messenger: bàn giao connect_url #

Phản hồi cũng bao gồm một connect_url có sẵn: một trang được lưu trữ chạy toàn bộ quy trình cho chủ tài khoản. Họ mở trang đó, đăng nhập vào Facebook và khi họ có nhiều hơn một Trang, nó sẽ hiển thị danh sách và cho phép họ chọn Trang muốn kết nối - sau đó nó sẽ tự báo cáo thành công. Hãy cung cấp liên kết này cho chủ tài khoản thay vì tự mình mở oauth_url, xây dựng trình chọn Trang và thực hiện thăm dò. Liên kết có hiệu lực trong khoảng 30 phút (connect_url_expires_at); nếu hết hạn, hãy bắt đầu một kết nối mới. Các bước thủ công dưới đây dành cho các tích hợp muốn tự điều khiển quy trình và hiển thị trình chọn Trang.

Bước 2 - Thăm dò trạng thái cho đến khi các trang tải xong #

GET /channels/meta/status

Sau khi người dùng hoàn tất đăng nhập Facebook, hãy thăm dò điểm cuối này vài giây một lần. Trường status sẽ trải qua các bước sau:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Phản hồi (sau khi các trang đã tải xong)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Bước 3 - Liệt kê các trang (tùy chọn) #

Nếu bạn muốn tự lấy danh sách Trang (ví dụ: để hiển thị bộ chọn), hãy sử dụng:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Nó trả về cùng một mảng pages như điểm cuối trạng thái. (Điểm cuối status đã bao gồm các trang, vì vậy lệnh gọi này chỉ mang tính tiện lợi.)

Bước 4 - Chọn trang để kết nối #

POST /channels/meta/select-page

Gửi page_id của Trang mà người dùng đã chọn. Tài khoản Instagram được liên kết với Trang đó sẽ tự động được kết nối; bạn chỉ cần đối tượng instagram nếu muốn ghi đè tài khoản Instagram nào sẽ được sử dụng.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

Kênh hiện đã được kết nối. Một GET /channels/meta/status tiếp theo sẽ báo cáo status: "connected".

Liệt kê các bài đăng của trang đã kết nối #

GET /channels/meta/posts?platform=instagram

Trả về các bài đăng gần đây của trang bạn đã kết nối - phương tiện Instagram hoặc bài đăng trên Facebook. Đây là nội dung bạn dùng để hiển thị trình chọn khi thiết lập Điểm truy cập (Entry Point) phản hồi các bình luận trên một bài đăng cụ thể.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType là nhãn riêng của Instagram (REELS, FEED, STORY, hoặc định dạng - IMAGE, VIDEO, CAROUSEL_ALBUM); đối với Facebook, nó luôn là POST. nextCursor là null trên trang cuối cùng.

Nếu không có gì để liệt kê, lệnh gọi vẫn trả về 200 với connected: false và một mảng posts trống, cùng với reason cho biết lý do:

Ngắt kết nối Instagram + Messenger #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "disconnected": true }

Thao tác này dừng định tuyến đến cho cả Instagram và Messenger. Nó có tính lũy đẳng - việc gọi lệnh này khi chưa có kết nối nào vẫn sẽ thành công.

WhatsApp Business #

Thao tác này kết nối một số điện thoại WhatsApp Business chính thức. Số điện thoại phải tồn tại trên tài khoản trước khi bạn gọi lệnh kết nối. Giống như Meta, chủ tài khoản thực hiện ủy quyền trong trình duyệt của họ, sau đó bạn thực hiện thăm dò cho đến khi số điện thoại báo ONLINE.

Bước 1 - Bắt đầu kết nối WhatsApp Business #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Phản hồi

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Mở oauth_url trong trình duyệt của chủ tài khoản để ủy quyền. Sau khi họ phê duyệt, quá trình đăng ký sẽ hoàn tất ở chế độ nền.

Bước 2 - Thăm dò trạng thái cho đến khi ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Thăm dò trạng thái này cho đến khi status là ONLINE.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Phản hồi

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Trường status có thể là:

live: true nghĩa là trạng thái đã được kiểm tra với nhà cung cấp trong thời gian thực; false nghĩa là trạng thái lấy từ lần lưu bộ nhớ đệm gần nhất.

Ngắt kết nối số điện thoại WhatsApp Business #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

Bản thân số điện thoại vẫn nằm trên tài khoản, vì vậy bạn có thể kết nối lại sau.

WhatsApp Web #

WhatsApp Web liên kết một số điện thoại WhatsApp thông thường bằng cách quét mã QR, giống như việc liên kết thiết bị trong ứng dụng WhatsApp. Quy trình bao gồm: bắt đầu phiên, lấy mã QR và hiển thị mã đó, sau đó thăm dò cho đến khi trạng thái là connected.

Bước 1 - Bắt đầu phiên ghép nối WhatsApp Web #

POST /channels/whatsapp-web/connections

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Tùy chọn dễ dàng nhất cho WhatsApp Web: bàn giao connect_url #

Phản hồi bao gồm một connect_url có sẵn: một trang được lưu trữ hiển thị mã QR, tự động làm mới khi mã xoay vòng và chuyển sang thông báo thành công ngay khi số điện thoại được liên kết. Chỉ cần gửi liên kết này cho chủ tài khoản (mở trong trình duyệt, gửi cho họ hoặc hiển thị dưới dạng mã QR/nút bấm) và yêu cầu họ quét bằng WhatsApp - bạn không cần phải tự lấy mã QR hay thực hiện thăm dò trạng thái. Liên kết có hiệu lực trong khoảng 30 phút (connect_url_expires_at); nếu liên kết hết hạn trước khi họ hoàn tất, hãy bắt đầu một kết nối mới để nhận liên kết mới.

Đây là cách được khuyến nghị khi người dùng có thể mở liên kết. Các bước thủ công bên dưới (tự lấy mã QR, thăm dò trạng thái) dành cho các tích hợp muốn hiển thị mã QR ngay trong giao diện của riêng họ.

Phản hồi cũng cung cấp cho bạn chính xác poll_qr_path và poll_status_path để sử dụng, vì vậy bạn không cần phải tự xây dựng chúng.

Bước 2 - Lấy mã QR và hiển thị mã đó #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Phản hồi

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Hiển thị mã QR để người dùng quét bằng điện thoại của họ (WhatsApp > Thiết bị đã liên kết > Liên kết thiết bị):

• qr_data_url là hình ảnh sẵn sàng sử dụng - hãy chèn trực tiếp vào thẻ <img src>.
• qr_code là dữ liệu thô nếu bạn muốn tự tạo hình ảnh.

Mã QR có thời hạn sử dụng ngắn. Nếu bạn gọi lệnh này ngay sau khi bắt đầu phiên, bạn có thể nhận được 404 với thông báo “QR code not available yet” (Mã QR chưa khả dụng) - chỉ cần đợi một chút và thử lại. Nếu bạn nhận được 410 (“QR code expired” - Mã QR đã hết hạn), hãy bắt đầu lại kết nối để nhận mã mới.

Bước 3 - Thăm dò trạng thái cho đến khi kết nối #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Phản hồi

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Ngắt kết nối phiên WhatsApp Web #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Thao tác này sẽ hủy liên kết thiết bị và xóa kết nối. Nó luôn dọn dẹp trạng thái cục bộ, vì vậy nó có tính lũy đẳng ngay cả khi phiên làm việc cơ sở đã bị xóa.

Telegram #

Tính khả dụng: Telegram kết nối giống như bất kỳ kênh nào khác và mở cho mọi tài khoản — bạn không cần phải bật tính năng này cho mình. Các điểm cuối Telegram bên dưới vẫn có thể trả về 403 nếu Telegram không được bao gồm trong gói của tài khoản, trong trường hợp đó lỗi sẽ hiển thị là "This channel is not included in your current plan. Upgrade to unlock it.".

Telegram kết nối tài khoản cá nhân bằng số điện thoại cộng với mã đăng nhập một lần (và mật khẩu hai yếu tố, nếu tài khoản đã thiết lập). Quy trình là: bắt đầu phiên, gửi mã, tùy chọn gửi mật khẩu, sau đó xác nhận qua trạng thái.

Bước 1 - Bắt đầu phiên kết nối Telegram #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Ở chế độ code, tài khoản sẽ nhận được mã đăng nhập trong Telegram và status là code_required. (Ở chế độ qr, phản hồi cũng bao gồm login_token và qr_url để hiển thị cho việc quét, và status là qr_required.)

Tùy chọn dễ dàng nhất cho Telegram: bàn giao connect_url #

Phản hồi bao gồm một connect_url có sẵn: một trang được lưu trữ tự hoàn tất quá trình kết nối. Ở chế độ code, chủ tài khoản nhập mã đăng nhập - và mật khẩu xác minh hai bước nếu tài khoản của họ có cài đặt. Ở chế độ qr, trang hiển thị mã QR tự làm mới để họ quét từ ứng dụng Telegram. Dù bằng cách nào, trang này sẽ tự báo cáo thành công, vì vậy bạn chỉ cần gửi liên kết này cho chủ tài khoản thay vì tự xây dựng giao diện người dùng và thực hiện polling. Liên kết có hiệu lực trong khoảng 30 phút (connect_url_expires_at); nếu hết hạn, hãy bắt đầu một kết nối mới để nhận liên kết mới.

Các bước thủ công bên dưới (tự thu thập mã, gửi mã, polling trạng thái; hoặc hiển thị qr_url và polling) dành cho các tích hợp muốn tự hiển thị giao diện người dùng.

Bước 2 - Gửi mã đăng nhập #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Nếu status là connected, bạn đã hoàn tất. Nếu tài khoản đã bật xác thực hai yếu tố, status sẽ là password_required thay vào đó - hãy chuyển sang bước 3.

Bước 3 - Gửi mật khẩu hai yếu tố (chỉ khi cần) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Chỉ gọi bước này khi bước 2 trả về password_required.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Kiểm tra trạng thái Telegram #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status có thể là connected, code_required, password_required, initializing, disconnected, not_initialized, hoặc error.

Ngắt kết nối Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotent - các lệnh gọi lặp lại đều thành công.

Instagram (tài khoản cá nhân) #

Bản beta có giới hạn, được bật theo từng tài khoản. Tính năng này kết nối tài khoản Instagram cá nhân bằng cách đăng nhập bằng tên người dùng và mật khẩu (không phải API Doanh nghiệp chính thức). Nếu tài khoản chưa được bật cho bản beta, lệnh gọi kết nối sẽ trả về lỗi quyền.

Vì việc này cần thông tin đăng nhập Instagram của chính chủ tài khoản, cách đơn giản nhất là cung cấp cho họ connect_url được lưu trữ và để họ tự nhập thông tin xác thực của mình ở đó - tích hợp của bạn không bao giờ xử lý mật khẩu.

Bước 1 - Bắt đầu kết nối Instagram (cá nhân) #

POST /channels/instagram-private/connect

Gửi username và password của Instagram.

Phản hồi

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Nếu tài khoản có xác thực hai yếu tố hoặc Instagram yêu cầu kiểm tra (checkpoint), status sẽ trả về two_factor_required hoặc challenge_required - hãy gửi mã đến /connect/{id}/verify-2fa hoặc /connect/{id}/verify-challenge bên dưới, sau đó thăm dò /connect/{id}/status cho đến khi connected. {id} là tên người dùng Instagram đã chuẩn hóa được trả về dưới dạng account_id/username trong phản hồi ở trên - hãy sử dụng nó trong mọi bước bên dưới.

Bước 2 - Gửi mã xác thực hai yếu tố (nếu được yêu cầu) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Chỉ gọi lệnh này khi bước 1 (hoặc bước 3) trả về two_factor_required.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Phản hồi

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status có thể trả về connected (hoàn tất), two_factor_required (sai mã, thử lại), hoặc challenge_required (Instagram cũng yêu cầu mã kiểm tra checkpoint - hãy chuyển sang bước 3).

Bước 3 - Gửi mã xác nhận kiểm tra (checkpoint) (nếu được yêu cầu) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Chỉ gọi lệnh này khi bước trước đó trả về challenge_required. Cấu trúc yêu cầu và phản hồi giống như bước 2 ở trên.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Kiểm tra trạng thái Instagram (cá nhân) #

GET /channels/instagram-private/connect/{id}/status

Thăm dò lệnh này cho đến khi status là connected, hoặc cho đến khi nó báo cáo lỗi nghiêm trọng.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status có thể là connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized, hoặc error. live: true có nghĩa là giá trị này được đọc trực tiếp từ trình xử lý kết nối thay vì giá trị đã lưu trong bộ nhớ đệm.

Tùy chọn dễ dàng nhất cho Instagram (cá nhân): bàn giao connect_url #

Phản hồi bao gồm một connect_url: một trang được lưu trữ nơi chủ tài khoản nhập tên người dùng và mật khẩu Instagram của họ (và mã 2FA hoặc mã kiểm tra nếu Instagram yêu cầu), và trang này sẽ tự báo cáo thành công. Thông tin xác thực được gửi thẳng đến Instagram và không được lưu trữ. Hãy cung cấp liên kết này cho chủ tài khoản thay vì thu thập mật khẩu của họ trong giao diện người dùng của bạn. Liên kết có hiệu lực trong khoảng 30 phút (connect_url_expires_at).

Ngắt kết nối Instagram (cá nhân) #

DELETE /channels/instagram-private/{id}

Idempotent - các lệnh gọi lặp lại đều thành công.

Đồng bộ người theo dõi #

POST /channels/instagram-private/{id}/sync-followers

Kích hoạt thủ công quá trình đồng bộ người theo dõi cho một tài khoản đã kết nối - đây chính là tác vụ chạy tự động trong nền, được hiển thị tại đây như một hành động “Làm mới người theo dõi” theo yêu cầu. Nó sẽ tìm nạp danh sách người theo dõi hiện tại của tài khoản, ghi lại bất kỳ người mới nào và (khi chiến dịch Trực tiếp có bật tính năng tiếp cận người theo dõi) sẽ gửi tin nhắn trực tiếp (DM) mở đầu cho những người theo dõi mới, tối đa theo hạn mức hàng ngày.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Năm trường này là nơi duy nhất trên trang này trả về camelCase thay vì snake_case - đó là cách điểm cuối này được thiết lập hiện tại, không phải lỗi đánh máy. isBaselineSeed: true có nghĩa đây là lần đồng bộ đầu tiên sau khi kết nối, chỉ ghi lại danh sách người theo dõi ban đầu và không bao giờ gửi DM tiếp cận (vì vậy dmsSent luôn là 0 trong lần chạy đó).

Lần gọi đầu tiên cho một tài khoản có thể mất một chút thời gian (duyệt toàn bộ danh sách người theo dõi); các lần gọi sau sẽ nhanh hơn vì chỉ những người theo dõi mới được so sánh. 404 có nghĩa là tài khoản chưa được kết nối; 412 có nghĩa là kết nối chưa hoàn tất khởi tạo - hãy đợi và thử lại.

LINE #

LINE là kênh kết nối đơn giản nhất vì không cần chuyển hướng trình duyệt hay thăm dò (polling). Khách hàng tạo một kênh Messaging API trong bảng điều khiển LINE Developers, sao chép hai giá trị và bạn gửi chúng trong một lệnh gọi duy nhất. Sau đó, bạn cung cấp lại cho họ một URL webhook để dán vào bảng điều khiển.

Bước 1 - Kết nối bằng thông tin xác thực kênh #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Hai trường quan trọng cho những gì bạn làm tiếp theo:

• webhook_url - khách hàng phải dán giá trị này vào trường Webhook URL của kênh LINE của họ trong bảng điều khiển LINE Developers (và bật “Use webhook”). Cho đến khi họ thực hiện việc này, sẽ không có tin nhắn gửi đến nào được nhận. Hãy hiển thị thông tin này cho họ một cách rõ ràng.
• chat_mode_ok - khi false, Tài khoản Chính thức đang ở chế độ “trò chuyện” (chat) và sẽ không nhận hoặc gửi tin nhắn cho đến khi được chuyển sang chế độ “bot” trong LINE Official Account Manager. Hãy kiểm soát quá trình onboarding của bạn dựa trên cờ này và yêu cầu khách hàng chuyển đổi chế độ.

channel_access_token và channel_secret không bao giờ được trả về bởi bất kỳ endpoint nào. Hãy lưu trữ chúng ở phía bạn nếu bạn cần sử dụng lại; nếu không, hãy dán lại từ bảng điều khiển LINE.

bot_user_id được trả về ở đây là định danh kết nối mà bạn sử dụng trong các lệnh gọi trạng thái, xác minh và ngắt kết nối bên dưới.

Bước 2 - Xác minh lại sau khi thiết lập webhook #

POST /channels/line/{botUserId}/verify-webhook

Sau khi khách hàng hoàn tất cấu hình URL webhook và chuyển sang chế độ bot, hãy gọi lệnh này để xác thực lại token đã lưu và làm mới chế độ trò chuyện được lưu trong bộ nhớ đệm.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Nếu token_valid là false, token truy cập đã lưu không còn xác thực được nữa - hãy yêu cầu khách hàng cấp lại token trong bảng điều khiển và gọi POST /channels/line lần nữa với token mới.

Kiểm tra trạng thái LINE #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINE không có nguồn cấp dữ liệu trạng thái trực tiếp, vì vậy live ở đây luôn là false - các giá trị phản ánh trạng thái được ghi lại tại thời điểm kết nối (hoặc lần xác minh cuối cùng).

Ngắt kết nối LINE #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

Viber kết nối theo cách tương tự như LINE - dán mã thông báo xác thực (auth token) của bot từ Bảng quản trị Viber vào một lệnh gọi - với một điểm khác biệt cần lưu ý: việc kết nối cũng ĐĂNG KÝ webhook của chúng tôi trên bot của bạn ngay lúc đó, vì vậy không cần bước thực hiện riêng biệt trên bảng điều khiển sau đó. Điều đó cũng có nghĩa là một nỗ lực kết nối có thể thất bại nếu cổng vào của chúng tôi không thể phản hồi kiểm tra webhook đồng bộ của Viber, không chỉ khi bản thân mã thông báo bị sai.

Bước 1 - Kết nối bằng mã thông báo xác thực của bot #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Phản hồi

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

Mã thông báo xác thực không bao giờ được trả về bởi bất kỳ điểm cuối nào - hãy lưu trữ nó ở phía bạn nếu bạn cần dán lại. bot_id là định danh kết nối được sử dụng bởi các lệnh gọi trạng thái, xác minh và ngắt kết nối bên dưới.

Kiểm tra trạng thái Viber #

GET /channels/viber/{botId}/status

Báo cáo trạng thái kết nối đã lưu. Thêm ?live=true để kiểm tra lại bot với Viber và làm mới đăng ký webhook đã lưu trong bộ nhớ đệm - hữu ích trước khi cho rằng một bot im lặng thực sự đã bị hỏng.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false có nghĩa là webhook của bot không còn trỏ đến chúng tôi - các tin nhắn gửi đến sẽ bị mất. Điều này thường có nghĩa là một công cụ khác đã kết nối cùng một bot sau đó (đăng ký webhook của Viber ưu tiên lần ghi cuối cùng). Hãy khắc phục bằng lệnh gọi xác minh lại bên dưới, không cần yêu cầu khách hàng dán lại mã thông báo của họ. live là false khi phản hồi là trạng thái được lưu trong bộ nhớ đệm cuối cùng thay vì kiểm tra mới với Viber.

Đăng ký lại webhook #

POST /channels/viber/{botId}/verify-webhook

Hành động sửa lỗi cho webhook_ok: false - đăng ký lại webhook của chúng tôi trên bot bằng mã thông báo xác thực đã được lưu trữ.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false có nghĩa là mã thông báo đã lưu không còn hoạt động - hãy kết nối lại bằng POST /channels/viber và một mã thông báo mới.

Ngắt kết nối Viber #

DELETE /channels/viber/{botId}

Hủy đăng ký webhook của chúng tôi trên phía Viber (nỗ lực tốt nhất) và xóa kết nối.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Tính khả dụng: Bản beta giới hạn, được kích hoạt theo từng tài khoản. Việc kết nối TikTok sẽ trả về lỗi quyền truy cập cho đến khi tài khoản được kích hoạt cho tính năng này.

TikTok Business Messaging là một kênh OAuth đầy đủ giống như Meta, nhưng đơn giản hơn ở phía polling: không có bước polling trạng thái chuyên dụng nào để xây dựng, vì tài khoản được kết nối sẽ tự xuất hiện sau khi TikTok chuyển hướng trở lại và kết nối được ghi lại. Endpoint trạng thái bên dưới tồn tại để xác nhận trạng thái theo yêu cầu (công cụ hỗ trợ, kiểm tra tình trạng), không phải là thứ bạn cần lặp lại trong quá trình kết nối.

Bước 1 - Bắt đầu kết nối TikTok #

POST /channels/tiktok/connect

Không yêu cầu thông tin xác thực - chủ tài khoản ủy quyền hoàn toàn trong trình duyệt của họ.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Mở oauth_url trong trình duyệt của chủ tài khoản để họ có thể đăng nhập vào TikTok và phê duyệt quyền truy cập. Trạng thái sẽ hết hạn sau expires_at (khoảng 30 phút) - nếu quá thời gian này, hãy bắt đầu lại. Không có lối tắt trang được lưu trữ connect_url cho TikTok; tự mở oauth_url là cách duy nhất.

Kiểm tra trạng thái TikTok #

GET /channels/tiktok/{openId}/status

openId là open_id của Tài khoản Doanh nghiệp TikTok, được biết sau khi callback OAuth đã chạy.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTok không có kiểm tra tình trạng trực tiếp giá rẻ, vì vậy live luôn là false ở đây - các trường phản ánh những gì kết nối (hoặc lần làm mới token cuối cùng) đã ghi lại. status: "reauth_required" với status_reason được đặt có nghĩa là tài khoản cần phải thực hiện lại kết nối; token TikTok được làm mới tự động theo chu kỳ hàng năm, và đây là những gì xuất hiện nếu quá trình xoay vòng đó thất bại.

Ngắt kết nối TikTok #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) là một tích hợp CRM, không phải là kênh nhắn tin - việc kết nối nó không chiếm dụng vị trí kênh trong gói dịch vụ, vì nó sử dụng các kênh hiện có của tài khoản thay vì thêm kênh mới. Đây cũng là tích hợp duy nhất trên trang này có thể giữ nhiều hơn một kết nối cùng lúc: mỗi tài khoản phụ GHL (“vị trí”) mà khách hàng cài đặt ứng dụng sẽ có mục nhập riêng.

Bước 1 - Bắt đầu kết nối GHL #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Mở oauth_url trong trình duyệt của chủ tài khoản để họ có thể chọn một vị trí GHL và phê duyệt quyền truy cập. Trạng thái sẽ hết hạn sau expires_at (khoảng 30 phút).

Liệt kê các kết nối GHL #

GET /channels/ghl/status

Không giống như các kênh khác, đây không phải là trạng thái của một kết nối đơn lẻ - nó liệt kê mọi vị trí mà tài khoản đã kết nối.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

Ngắt kết nối vị trí GHL #

DELETE /channels/ghl/{locationId}

Xóa kết nối tại đây, điều này sẽ dừng mọi quá trình đồng bộ và kích hoạt cho vị trí đó. Thao tác này không gỡ cài đặt ứng dụng ở phía GHL - khách hàng sẽ tự gỡ nó khỏi các cài đặt marketplace GHL của họ nếu họ muốn làm điều đó.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Số điện thoại (mua và giải phóng) #

Thay vì kết nối một số điện thoại hiện có, bạn có thể mua trực tiếp một số mới có khả năng sử dụng WhatsApp. Tìm kiếm các số khả dụng, mua một số, sau đó thăm dò cho đến khi quá trình cấp phát hoàn tất.

Bước 1 - Tìm kiếm các số khả dụng #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Mỗi kết quả hiển thị purchase_credits một lần và monthly_credits định kỳ. Một số điện thoại do nền tảng cung cấp có giá ít nhất 50 tín dụng mỗi tháng, tăng dần theo giá hàng tháng của nhà mạng, được tính phí khi mua và mỗi lần gia hạn. Hãy trích dẫn purchase_credits / monthly_credits mà kết quả tìm kiếm trả về; đừng bao giờ tự tính giá. Lần tìm kiếm đầu tiên trên một tài khoản mới sẽ cung cấp một số tài nguyên cơ bản, vì vậy nó có thể chậm hơn một chút so với các lần tìm kiếm sau này.

Bước 2 - Mua số điện thoại #

POST /phone-numbers

Sử dụng phone_number từ kết quả tìm kiếm.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

Số điện thoại bắt đầu ở trạng thái PURCHASED. Sau đó, quá trình đăng ký WhatsApp sẽ diễn ra trong nền: PURCHASED -> PENDING -> ONLINE.

Nếu việc mua hàng thất bại do thiếu địa chỉ doanh nghiệp hoặc chưa thiết lập chi tiết bắt buộc khác, bạn sẽ nhận được 400 kèm theo error mô tả. Hãy thiết lập chi tiết còn thiếu và thử lại.

Bước 3 - Thăm dò cho đến khi ONLINE #

GET /phone-numbers/{phoneNumber}/status

Đây là điểm cuối trạng thái số điện thoại dùng chung - nó hoạt động cho cả số WhatsApp đã mua cũng như các số được kết nối khác của bạn.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Phản hồi

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Bước 4 - Giải phóng số điện thoại #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "phone_number": "+14155551234", "released": true }

Việc này thực hiện điều gì phụ thuộc vào việc đó là số của ai.

Đối với một số điện thoại được thuê thông qua nền tảng, đây là một quá trình giải phóng thực sự: người gửi WhatsApp bị hủy đăng ký, số điện thoại được trả lại cho nhà mạng và xóa khỏi tài khoản, thời gian chờ 7 ngày được áp dụng trong đó số điện thoại không thể được mua lại bởi bất kỳ ai và không có khoản tín dụng nào được hoàn lại.

Đối với một số điện thoại mà tài khoản tự mang đến (tài khoản Twilio riêng, ứng dụng Meta hoặc Tài khoản WhatsApp Business riêng, hoặc cổng SMS Android), lệnh gọi tương tự chỉ xóa số đó khỏi tài khoản. Không có gì bị hủy tại nhà cung cấp thượng nguồn và không có thời gian chờ (cooldown) nào được ghi lại, vì vậy số điện thoại có thể được kết nối lại ngay lập tức. Việc đăng ký người gửi WhatsApp của nó, nếu có, có thể còn hoặc mất: quá trình gỡ bỏ sẽ cố gắng xóa người gửi bằng cách sử dụng thông tin xác thực Twilio do nền tảng quản lý của tài khoản. Trên một tài khoản vẫn đang sử dụng thiết lập được quản lý, các thông tin xác thực đó là hợp lệ và người gửi sẽ bị xóa, vì vậy việc kết nối lại đồng nghĩa với việc phải đăng ký lại. Trên một tài khoản đã chuyển sang sử dụng Twilio riêng, việc xóa không thể xác thực và người gửi vẫn được giữ nguyên trạng thái đăng ký trong tài khoản đó — khi đó, việc kết nối lại chỉ đơn giản là gắn lại người gửi hiện có.

Thêm số điện thoại bạn đã sở hữu (BYO) #

POST /phone-numbers/byo

Bỏ qua hoàn toàn quy trình tìm kiếm và mua ở trên. Sử dụng tùy chọn này khi tài khoản mang theo số điện thoại riêng của họ (Twilio riêng, Tài khoản WhatsApp Business Meta riêng hoặc cổng SMS Android) thay vì thuê số thông qua nền tảng. Tùy chọn này chỉ ghi lại số điện thoại - không có tín dụng nào bị trừ và không có gì được cung cấp với nhà cung cấp tại đây. Số điện thoại vẫn ở trạng thái không hoạt động cho đến khi chủ tài khoản hoàn tất OAuth WhatsApp để đăng ký Người gửi trên đó (quy trình tương tự như nút “Mang theo số điện thoại của riêng bạn” trên bảng điều khiển).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Phản hồi (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

Một phone_number không phải là số E.164 thực (hoặc trông giống như số thử nghiệm WhatsApp của Meta, vốn không bao giờ có thể nhắn tin cho khách hàng thực) sẽ trả về 400. Việc thêm một số đã tồn tại trên tài khoản - ngay cả khi được viết khác một chút, như các dạng +52 so với +521 của Mexico - sẽ trả về 409 thay vì tạo ra một hàng trùng lặp.

Đặt số điện thoại làm số chính #

POST /phone-numbers/{phoneNumber}/set-primary

Chuyển một số thành is_active: true và mọi số khác trên tài khoản thành is_active: false, một cách nguyên tử - tài khoản sẽ không bao giờ kết thúc với hai số hoạt động hoặc không có số nào ở giữa yêu cầu. is_active không thể được đặt thông qua điểm cuối cập nhật chung; lệnh gọi chuyên dụng này là cách duy nhất để thay đổi số nào là số chính.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number ở đây là đối tượng số đầy đủ (cùng hình dạng mà GET /phone-numbers trả về), không chỉ là chuỗi. Một phoneNumber không có trên tài khoản sẽ trả về 404.

Xóa bản ghi của số điện thoại (mà không giải phóng nó) #

DELETE /phone-numbers/{phoneNumber}/record

Một thao tác xóa đơn giản bản ghi của số điện thoại trên tài khoản này - không có việc giải phóng hoặc hủy đăng ký ở phía nhà cung cấp, và không áp dụng thời gian chờ 7 ngày như bước giải phóng ở trên. Sử dụng tùy chọn này để xóa các bản ghi BYO, WhatsApp Web, Telegram hoặc LINE, hoặc một mục nhập cũ mà không cần thông qua quy trình giải phóng được quản lý. Không giống như giải phóng, việc xóa một số không có trên tài khoản là một 404, không phải là một thành công thầm lặng.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Định tuyến kênh đến một chiến dịch #

Kết nối một kênh sẽ đưa tin nhắn vào tài khoản. Nó không quyết định AI Agent nào sẽ trả lời các tin nhắn đó.

Việc định tuyến được xử lý bởi Điểm truy cập (Entry Points) trên một AI Agent, không phải bởi các chiến dịch. Mỗi kênh có một Điểm truy cập mặc định chỉ định Agent sẽ trả lời các liên hệ mới, chưa xác định trên kênh đó:

Cho đến khi một kênh có Điểm truy cập (Entry Point), tin nhắn đầu tiên từ người mà bạn chưa từng trò chuyện vẫn sẽ được lưu trữ, nhưng không có gì nhận tin nhắn đó và không có trợ lý nào trả lời. Đây là bước mà hầu hết các tích hợp đều bỏ lỡ: việc kết nối Instagram và tạo một Tác nhân (Agent) là chưa đủ — bạn cũng phải trỏ kênh đó vào Tác nhân. Tập hợp đầy đủ các lệnh gọi — bao gồm một Tác nhân cho mỗi số WhatsApp, từ khóa và quy tắc bình luận — nằm trong API Điểm truy cập.

POST /channels/campaign vẫn ghi bản đồ định tuyến chiến dịch kế thừa theo từng kênh, được ghi lại bên dưới, nhưng bản đồ đó không còn được tham chiếu để định tuyến tin nhắn đến trên bất kỳ tài khoản nào; nó chỉ được giữ lại để khôi phục (rollback). Đừng xây dựng dựa trên nó.

Định tuyến một hoặc nhiều kênh (bản đồ định tuyến chiến dịch kế thừa) #

POST /channels/campaign

Các trường yêu cầu

Khe định tuyến và danh sách enabled_channels của chiến dịch được cập nhật cùng nhau trong một thao tác nguyên tử, vì vậy chúng không bao giờ bị lệch nhau. Một kênh đã được định tuyến đến một chiến dịch khác sẽ đơn giản là được trỏ lại vào chiến dịch này.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
    "channels": ["instagram", "messenger"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

Các điều kiện để việc định tuyến thực sự hoạt động #

Trên một tài khoản vẫn đọc bản đồ định tuyến chiến dịch kế thừa, việc định tuyến thành công dưới dạng lệnh gọi API nhưng ba yếu tố trên chiến dịch sẽ quyết định liệu một tin nhắn đến thực tế có được trả lời hay không. Hãy kiểm tra cả ba khi một kênh đã định tuyến vẫn im lặng.

Khớp từ khóa hiện nằm trên các Điểm truy cập — hãy tạo một Điểm truy cập loại keyword trên AI Agent cần trả lời.

Một chiến dịch cho mỗi kênh #

Mỗi kênh giữ chính xác một vị trí định tuyến kế thừa. Việc định tuyến chiến dịch thứ hai vào cùng một kênh sẽ âm thầm trỏ lại vị trí đó và trả về 200 — không có lỗi xung đột. Chiến dịch trước đó vẫn tiếp tục xử lý các liên hệ mà nó đã có; nó chỉ ngừng nhận các liên hệ mới.

Xóa định tuyến của kênh #

DELETE /channels/campaign/{channel}

Xóa định tuyến cho một kênh duy nhất, bất kể chiến dịch mà nó đang trỏ tới, và đưa kênh đó ra khỏi enabled_channels của chiến dịch đó. Các liên hệ mới chưa xác định trên kênh sẽ không còn được bất kỳ chiến dịch nào tiếp nhận nữa. Các liên hệ đã có trong chiến dịch vẫn tiếp tục như trước.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Thao tác này có tính lũy đẳng: việc xóa một kênh chưa từng được định tuyến cũng trả về 200, cùng với cleared: false và campaign_id: null. Điểm cuối này yêu cầu tính năng chiến dịch đến (incoming campaigns) trong gói dịch vụ; nếu không có, bạn sẽ nhận được 403.

Sử dụng ứng dụng Meta của riêng bạn (Instagram + Messenger) #

Theo mặc định, kết nối Instagram + Messenger chạy thông qua ứng dụng Meta của nền tảng, vì vậy tên của ứng dụng đó là tên mà chủ tài khoản nhìn thấy trên màn hình đồng ý của Facebook. Nếu bạn muốn màn hình đồng ý hiển thị thương hiệu của bạn thay thế, bạn có thể đăng ký ứng dụng Meta của riêng mình và định tuyến toàn bộ quy trình thông qua đó. Sau khi được định cấu hình, nó sẽ áp dụng cho tài khoản của bạn — không có gì thay đổi trong các lệnh gọi kết nối ở trên ngoại trừ phần thương hiệu.

Điều này chỉ áp dụng cho Instagram + Messenger. Các kết nối WhatsApp, WhatsApp Web, Telegram và LINE không bị ảnh hưởng bởi ứng dụng Meta tùy chỉnh.

Những gì ứng dụng của bạn cần trước tiên #

Đây là phần tốn thời gian và diễn ra hoàn toàn ở phía Meta:

1. Một ứng dụng loại Business, đã thêm các sản phẩm Messenger và Instagram.
2. Quyền truy cập nâng cao (Advanced Access) (thông qua Meta App Review) cho: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Nếu không có Quyền truy cập nâng cao, chỉ những người giữ vai trò trong ứng dụng của bạn mới có thể hoàn tất kết nối — kết nối của khách hàng của bạn sẽ thất bại. Quy trình App Review thường mất vài tuần và yêu cầu Xác minh doanh nghiệp (Business Verification).
3. Cấu hình Facebook Login for Business được tạo bên trong ứng dụng của bạn, cấp các quyền tương tự. ID cấu hình dạng số của nó là dành riêng cho từng ứng dụng, vì vậy bạn phải tạo cấu hình của riêng mình.

Nếu ứng dụng của bạn thiếu bất kỳ quyền bắt buộc nào, kết nối sẽ thất bại tại thời điểm kết nối với thông báo lỗi rõ ràng nêu tên quyền còn thiếu (có thể xem trong /status poll dưới dạng byo_app_missing_permissions) — thay vì có vẻ như hoạt động nhưng lại thất bại ở tin nhắn đầu tiên.

Bước 1 - Lưu ứng dụng của bạn #

PUT /account-config/meta-app

Cả ba đều bắt buộc đối với quy trình Đăng nhập Facebook. Nếu bạn chỉ chạy luồng đẩy mã thông báo Đăng nhập Instagram được mô tả ở phần dưới, bạn có thể bỏ qua hoàn toàn các trường này.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Phản hồi

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Bước 2 - Định cấu hình ứng dụng của bạn để giao tiếp với chúng tôi #

Trong bảng điều khiển ứng dụng Meta của bạn:

1. Webhooks - đối với cả sản phẩm Instagram và Messenger, hãy đặt URL Callback thành giá trị webhook_urls khớp từ phản hồi và Verify token thành verify_token. Đăng ký các trường messages, messaging_postbacks và comments.
2. URI chuyển hướng OAuth hợp lệ (Valid OAuth Redirect URIs) - thêm https://api.youraiconnector.com/v1/auth-meta-callback-handler để luồng đồng ý có thể quay lại.

GET /account-config/meta-app trả về cùng một tài liệu thiết lập bất cứ lúc nào; DELETE /account-config/meta-app xóa ứng dụng (các kết nối trong tương lai sẽ quay lại ứng dụng nền tảng — cũng hãy xóa đăng ký webhook bên trong ứng dụng của bạn).

Bước 3 - Kết nối như bình thường #

Không có gì khác thay đổi. POST /channels/meta/connect (và trang connect_url được lưu trữ) sẽ tự động sử dụng ứng dụng của bạn cho tài khoản của bạn; uses_byo_meta_app: true trong phản hồi sẽ xác nhận ứng dụng nào sẽ được hiển thị trên màn hình đồng ý. Việc gửi tin nhắn, chọn trang và ngắt kết nối vẫn hoạt động giống hệt nhau.

Sử dụng ứng dụng Instagram Login của riêng bạn (đẩy token) #

Phần trên đề cập đến quy trình Đăng nhập Facebook, nơi tài khoản kết nối thông qua Trang Facebook. Meta cũng cung cấp API Instagram với Instagram Login (Đăng nhập doanh nghiệp cho Instagram): chủ tài khoản xác thực trực tiếp trên Instagram, không cần tài khoản hoặc Trang Facebook.

Nếu nền tảng của bạn đã chạy ứng dụng Meta riêng với sản phẩm đó, bạn hoàn toàn không cần bất kỳ quy trình OAuth nào từ phía chúng tôi. Khách hàng của bạn ủy quyền cho ứng dụng của bạn, và bạn đẩy thông tin xác thực đã hoàn tất cho mỗi tài khoản tới chúng tôi:

1. Bạn lưu thông tin xác thực ứng dụng Instagram của mình một lần (để chúng tôi có thể xác minh webhook của bạn).
2. Với mỗi tài khoản, bạn đẩy ID tài khoản chuyên nghiệp Instagram + token người dùng Instagram dài hạn mà ứng dụng của bạn đã lấy được.
3. Bạn trỏ webhook nhắn tin Instagram của ứng dụng về phía chúng tôi. Các sự kiện cho những tài khoản bạn chưa đẩy sẽ được xác nhận và bỏ qua.
4. Bạn quản lý vòng đời của token: làm mới token trong hệ thống của riêng bạn và đẩy mỗi token đã làm mới bằng cùng một lệnh gọi. Chúng tôi không bao giờ tự làm mới token đã được đẩy.

Những gì ứng dụng của bạn cần trước tiên #

• Sản phẩm Instagram (“Thiết lập API với Instagram login”) được thêm vào ứng dụng Meta của bạn. Sản phẩm đó có cặp App ID và App Secret riêng, tách biệt với App ID/Secret của Facebook — bạn có thể tìm thấy chúng trong bảng thiết lập của sản phẩm.
• Quyền truy cập nâng cao (thông qua Đánh giá ứng dụng Meta) cho instagram_business_basic và instagram_business_manage_messages (thêm instagram_business_manage_comments nếu bạn sử dụng tính năng tự động hóa bình luận). Nếu không có quyền này, chỉ những người có vai trò trong ứng dụng của bạn mới có thể ủy quyền cho nó.

Bước 1 - Lưu thông tin xác thực ứng dụng Instagram của bạn #

Sử dụng cùng điểm cuối như trên — gửi cặp Instagram tới PUT /account-config/meta-app. Các trường Facebook không cần thiết cho luồng này: hãy gửi riêng cặp Instagram nếu bạn chỉ chạy Đăng nhập Instagram, hoặc gửi cùng với các trường Facebook nếu bạn chạy cả hai. Một thao tác lưu luôn mô tả toàn bộ cài đặt, vì vậy bất kỳ tập hợp nào bạn bỏ qua sẽ bị xóa.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Phản hồi — chứa URL webhook Đăng nhập Instagram (các URL instagram và messenger chỉ xuất hiện khi các trường Facebook cũng được lưu trữ):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

Trong bảng Webhooks của ứng dụng dành cho sản phẩm Instagram, hãy đặt URL Callback thành webhook_urls.instagram_login, Verify token thành verify_token và đăng ký các trường messages và comments.

Bước 2 - Đẩy token cho mỗi tài khoản #

PUT /channels/instagram-login/token

Hoạt động với sub_account_id giống như mọi lộ trình khác, vì vậy khóa đại lý có thể cung cấp cho toàn bộ hệ thống của mình.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Phản hồi

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Là một phần của quá trình đẩy, chúng tôi đăng ký ứng dụng của bạn với webhook của tài khoản đó (subscribed_apps với token đã đẩy), vì vậy tin nhắn sẽ bắt đầu được gửi mà không cần thêm bất kỳ lệnh gọi nào từ phía bạn.

Làm mới - đẩy token đã làm mới tới cùng một endpoint với cùng một ig_user_id; nó sẽ cập nhật token và thời hạn đã lưu tại chỗ.

Xung đột - một tài khoản Instagram không bao giờ hoạt động trên hai kết nối cùng lúc. Nếu tài khoản đã được kết nối ở nơi khác, hoặc trên chính tài khoản này thông qua luồng Trang Facebook, thao tác đẩy sẽ trả về một 409 cho biết bạn cần ngắt kết nối nào trước. Kết nối theo luồng Facebook không bao giờ được tự động thay thế, vì nó có thể đang phục vụ cả Messenger.

Bước 3 - Ngắt kết nối khi khách hàng rời đi #

DELETE /channels/instagram-login/token (cùng xác thực và sub_account_id) sẽ hủy đăng ký webhook theo cơ chế nỗ lực tốt nhất và xóa thông tin xác thực đã lưu. Thao tác này luôn thành công, ngay cả khi token đã hết hạn — và một khi thông tin xác thực đã bị xóa, các sự kiện webhook của tài khoản đó sẽ bị bỏ qua.

Mẹo xây dựng trình bao bọc đáng tin cậy #

• Thăm dò nhẹ nhàng. Vài giây một lần là đủ. Dừng lại khi bạn đạt đến trạng thái kết thúc (connected / ONLINE, hoặc trạng thái lỗi) và đặt thời gian chờ tổng thể hợp lý cho vòng lặp (các bước trình duyệt/QR sẽ hết hạn, xem từng expires_at).
• Mã hóa URL số điện thoại trong đường dẫn. Dấu + ở đầu nên được gửi dưới dạng %2B. Các điểm cuối cũng khôi phục các chữ số thô, nhưng mã hóa là mặc định an toàn.
• Đừng bao giờ mong đợi nhận lại các thông tin bí mật. Mã truy cập, bí mật kênh và mã trang được chấp nhận hoặc lưu trữ nhưng không bao giờ được trả về trong bất kỳ phản hồi nào.
• Xử lý cổng xác thực. 403 có nghĩa là quyền truy cập API không có trong gói hoặc kênh bạn đang kết nối không được bao gồm trong gói của tài khoản. Xem Quyền truy cập API.
• Lưu ý giới hạn tốc độ. Các yêu cầu đã xác thực được giới hạn ở mức 300 mỗi phút; 429 có nghĩa là hãy dừng lại và thử lại sau. Xem Xác thực.

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

• Xác thực - bốn hình thức xác thực được chấp nhận và định dạng lỗi.
• Quyền truy cập API - tạo và quản lý khóa API của bạn.