API Điểm truy cập (Entry Points) #

Một Điểm truy cập là một quy tắc định tuyến: “khi điều này xảy ra trên kênh này, hãy chuyển cuộc trò chuyện cho Tác nhân (Agent) này”. Việc kết nối một kênh sẽ đưa tin nhắn vào tài khoản và việc tạo một Tác nhân sẽ cung cấp cho bạn một thực thể có thể trả lời, nhưng không bên nào quyết định ai sẽ trả lời tin nhắn đầu tiên của người lạ. Điểm truy cập sẽ làm điều đó. Để biết thông tin về chính sản phẩm, hãy xem hướng dẫn về Điểm truy cập.

• URL cơ sở — https://api.youraiconnector.com/v1
• Xác thực — khóa API của bạn (xem Xác thực)
• Lỗi & phân trang — xem Lỗi & Phân trang

Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn ?apiKey= trong cURL và tiêu đề X-API-Key trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.

Trong trình khám phá API. Mọi endpoint trên trang này đều nằm 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 nó và chạy các yêu cầu trực tiếp trong trình khám phá API.

Lệnh gọi duy nhất mà hầu hết các tích hợp cần #

Kết nối một kênh, tạo một Tác nhân, sau đó trỏ kênh đó vào Tác nhân:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Đó là toàn bộ thiết lập cho “Tác nhân này trả lời WhatsApp”. Mọi thứ khác trên trang này dành cho các quy tắc hẹp hơn (từ khóa, bình luận, người theo dõi mới), nhiều số trên một kênh và đọc lại những gì đã được cấu hình.

Cách quyết định định tuyến #

Khi một tin nhắn đến, nền tảng sẽ đi theo một bậc thang cố định và bước đầu tiên quyết định sẽ thắng:

1. Con người đã tiếp quản cuộc trò chuyện — không có AI.
2. Liên hệ đã được chỉ định cho một Tác nhân, theo cách thủ công hoặc vì cuộc trò chuyện với Tác nhân đó đang diễn ra — cùng một Tác nhân đó sẽ tiếp tục. Điểm truy cập không bao giờ di chuyển một cuộc trò chuyện hiện có; để chuyển cuộc trò chuyện cho một Tác nhân khác, hãy chỉ định nó (trong ứng dụng hoặc bằng hành động Tự động hóa).
3. Liên hệ đang trả lời một chương trình phát sóng — Tác nhân của chương trình phát sóng đó sẽ trả lời, hoặc không ai cả nếu chương trình phát sóng không có Tác nhân nào.
4. Một Điểm truy cập hẹp khớp. Các quy tắc từ khóa thắng các quy tắc bình luận, vốn thắng các quy tắc người theo dõi. Giữa hai quy tắc cùng loại, quy tắc được cập nhật gần đây nhất sẽ thắng.
5. Mặc định của kênh cho kênh mà tin nhắn đã đến. Mặc định được giới hạn cho số cụ thể mà liên hệ đã viết tới sẽ thắng mặc định toàn kênh.
6. Không có gì khớp — tin nhắn sẽ nằm trong hộp thư đến cho nhóm của bạn và không có trợ lý nào trả lời.

Hai điều làm giảm bớt bước 6. Một tài khoản có chính xác một Tác nhân đang hoạt động và không có mặc định nào được cấu hình cho kênh vẫn nhận được Tác nhân đó làm người trả lời, vì vậy một tài khoản mới kết nối WhatsApp và gửi tin nhắn thử nghiệm sẽ không bị im lặng. Mức sàn đó không bao giờ áp dụng cho một kênh có quy tắc từ khóa (ở đó, một tin nhắn không khớp với bất kỳ từ khóa nào sẽ được để lại cho con người một cách có chủ ý) và không bao giờ ghi đè lên một kênh mà bạn đã đặt thành không ai cả (xem Để một kênh không có ai trả lời).

Việc bậc thang có hoạt động cho một tài khoản hay không được báo cáo bởi GET /entry-points/routing-status. Hiện tại, nó được bật cho mọi tài khoản; lệnh gọi tồn tại để một tích hợp có thể kiểm tra thay vì giả định.

Đối tượng Điểm truy cập #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Các loại quy tắc #

Một quy tắc từ khóa trên một kênh không có mặc định kênh cũng hoạt động như một cổng: các tin nhắn không khớp với bất kỳ từ khóa nào sẽ không nhận được trả lời tự động và chỉ đơn giản là nằm trong hộp thư đến của bạn, ngay cả trên một tài khoản chỉ có một Tác nhân.

Trỏ một kênh vào một Tác nhân #

PUT /entry-points/channel-defaults — chỉ định một Tác nhân làm người trả lời cho các liên hệ mới trên một kênh. Bất kỳ Tác nhân nào khác hiện đang được đặt làm mặc định của kênh đó sẽ bị loại bỏ trong cùng một lệnh gọi, vì vậy một kênh luôn có chính xác một người trả lời. Việc đặt Tác nhân vốn đã là mặc định sẽ không thay đổi bất cứ điều gì.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id là quy tắc hiện đang có hiệu lực; disabled_entry_point_ids liệt kê bất kỳ quy tắc nào đã bị loại bỏ để nhường chỗ cho nó (trống nếu không có gì để thay thế). Chỉ những liên hệ mà bạn chưa từng trò chuyện mới bị ảnh hưởng — bất kỳ ai đã có cuộc trò chuyện với một Tác nhân sẽ vẫn giữ Tác nhân đó.

400 có nghĩa là channel hoặc agent_id bị thiếu, Tác nhân thuộc về một tài khoản khác, hoặc phone_number không phải là một trong các số đã kết nối của bạn.

Xem ai trả lời từng kênh #

GET /entry-points/channel-defaults — mọi mặc định kênh trên tài khoản, mới nhất trước, bao gồm cả những mặc định đã bị loại bỏ (enabled: false) và một kênh được cố tình đặt thành không ai cả (agent_id: ""). Tự lọc theo enabled để có cái nhìn hiện tại.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Đây là thông tin đọc trên toàn tài khoản. Việc liệt kê các quy tắc của một Tác nhân với GET /agents/{agentId}/entry-points không thể hiển thị một kênh được đặt thành không ai cả, vì quy tắc đó không thuộc về Tác nhân nào.

Để một kênh không có ai trả lời #

DELETE /entry-points/channel-defaults?channel=instagram — loại bỏ mặc định toàn kênh cho một kênh. Kênh được đặt tên dưới dạng tham số truy vấn, không phải trong phần thân. Thêm &phone_number=%2B31685101091 để chỉ xóa mặc định của số đó và để số đó quay lại cho bất kỳ ai trả lời kênh.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

An toàn để lặp lại: việc xóa một kênh không có mặc định là một 200 với danh sách trống. Xóa có nghĩa là hủy đặt, không phải im lặng — trên một tài khoản chỉ có chính xác một Tác nhân đang hoạt động, một kênh chưa được cấu hình vẫn sẽ quay lại Tác nhân đó. Để giữ cho AI không hoạt động hoàn toàn trên một kênh, hãy chọn Không ai trả lời cho kênh đó trong bảng Ai trả lời các cuộc trò chuyện mới của ứng dụng (điều đó ghi một mặc định “không ai cả” rõ ràng mà cơ chế dự phòng không bao giờ ghi đè), hoặc tạm dừng Tác nhân với PATCH /agents/{agentId}/active.

Một Tác nhân cho mỗi số WhatsApp #

Định tuyến theo mặc định là theo từng kênh: tất cả các số WhatsApp của bạn chia sẻ một người trả lời. Với hai hoặc nhiều số được kết nối trên WhatsApp Business hoặc WhatsApp Web, một mặc định có thể được giới hạn cho một số duy nhất, vì vậy một doanh nghiệp có một số cho mỗi chi nhánh hoặc thương hiệu có thể chỉ định Tác nhân riêng cho từng số trong một tài khoản.

Gửi phone_number cùng với lệnh gọi set:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Số điện thoại phải là một trong các số đã kết nối của bạn trên kênh đó, được viết đúng như hiển thị trong phần số đã kết nối (E.164 với +); bất kỳ định dạng nào khác đều là 400.
• Quy tắc được lưu dưới dạng mặc định của kênh với match_config.phone_numbers: ["+31685101091"]. Một tin nhắn gửi đến số đó sẽ được chuyển đến Đại lý của nó; mọi số khác vẫn tiếp tục tuân theo mặc định của toàn kênh.
• Việc thiết lập hoặc xóa mặc định toàn kênh sẽ không ảnh hưởng đến các quy tắc theo phạm vi số và ngược lại. Xóa quy tắc riêng của một số bằng DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Các phản hồi luôn được gửi đi từ số mà liên hệ đã nhắn tin tới, vì vậy liên hệ sẽ tiếp tục trò chuyện với cùng một số và cùng một Đại lý.

Thêm một quy tắc cụ thể hơn #

POST /agents/{agentId}/entry-points — tạo quy tắc từ khóa, bình luận hoặc người theo dõi (hoặc mặc định kênh, mặc dù PUT /entry-points/channel-defaults là lựa chọn tốt hơn cho việc đó vì nó sẽ thay thế người trả lời trước đó cho bạn). Đại lý trong đường dẫn luôn được ưu tiên: một quy tắc không bao giờ có thể được tạo cho một Đại lý khác với Đại lý trong URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Phản hồi (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Một quy tắc bình luận-sang-tin nhắn trực tiếp (DM) chỉ phản ứng với các bình luận có nội dung “LINK” trên hai bài đăng cụ thể, chờ hai phút và gửi một tin nhắn đầu tiên cố định:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Để trống keywords để gửi DM cho tất cả những người bình luận trên các bài đăng được theo dõi và để trống post_ids để theo dõi mọi bài đăng. 400 sẽ cho biết lỗi là gì: type không xác định, channels trống, quy tắc từ khóa không có từ khóa hoặc quy tắc bình luận không liệt kê kênh của chính nó.

Liệt kê các quy tắc của Đại lý #

GET /agents/{agentId}/entry-points — các quy tắc gửi cuộc hội thoại đến Đại lý này, theo thứ tự mới nhất trước: mặc định kênh, quy tắc từ khóa, quy tắc bình luận và quy tắc người theo dõi của nó. Các quy tắc đã nghỉ cũng sẽ xuất hiện trở lại với enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Thay đổi quy tắc #

PUT /entry-points/{entryPointId} — thay đổi một quy tắc. Chỉ gửi các trường bạn đang thay đổi; các cài đặt lồng nhau có thể được xử lý từng phần với khóa có dấu chấm như "match_config.keywords". Bất cứ khi nào thay đổi ảnh hưởng đến type, channels hoặc match_config, toàn bộ quy tắc sẽ được kiểm tra lại, vì vậy một chỉnh sửa một phần không bao giờ có thể để lại một quy tắc không sử dụng được (chuyển type sang keyword mà không cung cấp từ khóa sẽ bị từ chối). Gửi agent_id sẽ chuyển quy tắc cho một Đại lý khác của bạn; một giá trị trống sẽ bị từ chối. Các trường quyền sở hữu và danh tính sẽ bị bỏ qua.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Phản hồi

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Các chỉnh sửa phổ biến khác: { "enabled": false } cho nghỉ một quy tắc mà không xóa nó và { "agent_id": "agOtherAgent" } di chuyển nó sang một Đại lý khác. Một nội dung trống sẽ trả về 400 với "No fields to update".

Xóa quy tắc #

DELETE /entry-points/{entryPointId} — xóa vĩnh viễn quy tắc. Không có gì khác tham chiếu đến Điểm truy cập, vì vậy không có gì cần phải tách rời trước.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Để dừng một quy tắc hoạt động nhưng vẫn giữ lại, hãy đặt enabled thành false. Đặc biệt, các mặc định kênh thường được cho nghỉ thay vì xóa, đó là những gì DELETE /entry-points/channel-defaults thực hiện.

Kiểm tra xem định tuyến có đang hoạt động không #

GET /entry-points/routing-status — trả về việc liệu thang Điểm truy cập (Entry Points) có quyết định ai là người trả lời trên tài khoản này hay không. Có thể đọc được với quyền xem, vì vậy một đồng đội sẽ thấy cùng một câu trả lời như chủ sở hữu.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Hiện tại, nó là true trên mọi tài khoản. Cuộc gọi được giữ lại để một tích hợp có thể xác minh trước khi thông báo cho ai đó rằng thay đổi định tuyến của họ đã hoạt động thay vì giả định điều đó.

Các cuộc gọi cũ hơn, theo hình thức chiến dịch #

Hai điểm cuối từ trước khi có Tác nhân (Agents) vẫn hoạt động cho các tài khoản được tổ chức theo chiến dịch. Các tích hợp mới nên sử dụng các cuộc gọi mặc định kênh ở trên.

• PUT /channel-routing/{channel} với { "campaignId": "cp5NbV8xQrT2wYzA" } — đặt tên cho một chiến dịch và Tác nhân của chiến dịch đó sẽ trở thành người trả lời của kênh. { "campaignId": null } xóa kênh. Một chiến dịch chỉ gửi đi sẽ bị từ chối vì nó không có hành vi gửi đến nào để cung cấp.
• POST /channel-routing/clear với { "channels": ["whatsapp", "instagram"] } — giải phóng một số kênh khỏi bất kỳ Tác nhân nào trả lời chúng trong một cuộc gọi, thường là trước khi chuyển hướng chúng đến nơi khác. Phản hồi liệt kê released_channels, những kênh thực sự có người trả lời.

Cả hai đều hủy thiết lập thay vì im lặng: trên một tài khoản chỉ có đúng một Tác nhân đang hoạt động, một kênh được giải phóng vẫn sẽ quay lại Tác nhân đó.

Lỗi API Điểm truy cập #

Các điểm cuối Điểm truy cập trả về phong bì lỗi tiêu chuẩn:

{
  "success": false,
  "error": "Entry point not found"
}

Các mã chung mà mọi điểm cuối có thể trả về — 401, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

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

• Điểm truy cập — khái niệm, các loại quy tắc và bảng Ai trả lời các cuộc hội thoại mới trong ứng dụng.
• API Tác nhân AI — tạo và cấu hình các Tác nhân mà các quy tắc này định tuyến đến.
• API Kênh — kết nối chính các kênh.
• Tự động hóa Bình luận sang Tin nhắn trực tiếp — những gì các quy tắc bình luận thực hiện khi chúng được kích hoạt.