入口点 API

入口点 (Entry Point) 是一条路由规则：“当此渠道发生这种情况时，将对话交给此智能体 (Agent)”。连接渠道可以将消息引入账户，创建智能体可以让你拥有回复的对象，但两者都无法决定谁来回答陌生人的第一条消息。入口点则可以。关于产品本身，请参阅入口点指南。

基础 URL — https://api.youraiconnector.com/v1
身份验证 — 您的 API 密钥（请参阅身份验证）
错误与分页 — 请参阅错误与分页

以下所有示例均展示了 cURL 中的 ?apiKey= 查询形式，以及 JavaScript 和 Python 中的 X-API-Key 标头——两者均适用于所有端点。

在 API 探索器中。 本页面上的每个端点都包含在已发布的 OpenAPI 规范中，因此您可以在 API 探索器中浏览其确切字段并运行实时请求。

大多数集成所需的唯一调用

连接一个渠道，创建一个智能体，然后将该渠道指向该智能体：

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" }'

这就是“此智能体回答 WhatsApp”的全部设置。本页面上的其他所有内容都是针对更具体的规则（关键词、评论、新粉丝）、同一渠道上的多个号码以及读取已配置内容。

路由决策方式

当消息到达时，平台会按照固定的阶梯进行判断，第一个决定结果的步骤即为胜出：

人工已接管对话 — 无 AI 介入。
联系人已被分配给某个智能体，无论是手动分配还是因为正在与该智能体进行对话 — 同一智能体将继续处理。入口点永远不会移动现有的对话；要将聊天交给不同的智能体，请分配它（在应用中，或使用自动化操作）。
联系人正在回复广播 — 由广播的智能体回答，如果广播没有指定智能体，则无人回答。
匹配到具体的入口点。关键词规则优于评论规则，评论规则优于粉丝规则。在同类规则中，最近更新的规则胜出。
渠道默认设置，即消息到达的渠道所对应的默认设置。针对联系人所写特定号码的默认设置优于整个渠道的默认设置。
无匹配项 — 消息进入团队收件箱，且没有助手回复。

两件事可以缓解第 6 步的情况。对于只有一个活跃智能体且未为渠道配置默认设置的账户，该智能体仍会被视为回答者，因此刚连接 WhatsApp 并发送测试消息的新账户不会收到沉默。此底线规则不适用于已设置关键词规则的渠道（在这种情况下，未匹配任何关键词的消息会特意留给人工处理），也不会覆盖你设置为无人回答的渠道（请参阅让渠道无人回答）。

账户的阶梯规则是否生效由 GET /entry-points/routing-status 报告。目前它对所有账户都是开启的；提供此调用是为了让集成可以进行检查，而不是进行假设。

入口点对象

{
  "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
}

字段	描述
`id`	规则的 ID。
`type`	`channel_default`、`keyword`、`instagram_comment`、`facebook_comment`、`instagram_follower` 之一。请参阅规则类型。
`channels`	规则覆盖的渠道：`whatsapp`、`whatsapp_web`、`instagram`、`instagram_private`、`messenger`、`telegram`、`sms`、`email`、`chat_widget`、`custom_channel`、`line`、`viber`、`tiktok`、`imessage`、`linkedin`、`skool`。评论规则使用 `instagram` 或 `facebook`。
`agent_id`	规则路由到的智能体。如果渠道默认设置被特意设为无人回答，则此项为空。
`enabled`	对于已停用的规则为 `false`。已停用的规则属于历史记录，而非实时设置，两者都会从列表端点返回。
`match_config`	类型特定的设置 — 请参阅规则类型。普通渠道默认设置此项为空。
`first_response_mode`	`ai`（默认）允许智能体编写第一条回复；`exact_text` 原样发送 `first_response_exact_text`。目前在评论规则中生效；在关键词规则中被接受并存储，但尚未启用。
`first_response_exact_text`	当 `first_response_mode` 为 `exact_text` 时的固定首条私信。 `{{first_name}}` 会被替换为对方的名字，如果未知则替换为“there”。
`public_comment_reply_exact_text`	仅限评论规则：评论下方的固定公开回复。留空则跳过公开回复；私信仍会发送。
`created_at`, `last_modified_at`	纪元毫秒数。

规则类型

`type`	触发条件	`match_config`
`channel_default`	一个新的、未知的联系人在 `channels` 之一上发来消息。	`phone_numbers`（可选）— 将默认设置的作用域限定为某个已连接的号码，而不是整个渠道。请参阅每个 WhatsApp 号码一个智能体。
`keyword`	新联系人的第一条消息是 `keywords` 之一。匹配时忽略大小写和空格，且除非你设置了 `fuzzy_match: false`，否则 AI 仍会解析近似匹配（例如“info pls”匹配 `INFO`）— 对于促销代码和 SKU，如果必须精确匹配，请务必设置此项。不适用于 `sms` 或 `imessage`。	`keywords`（至少一个，必填），`fuzzy_match`（默认 `true`）。
`instagram_comment` / `facebook_comment`	有人在你的帖子下评论。 `channels` 必须分别包含 `instagram` 或 `facebook`。	`keywords`（留空表示关注帖子下的每条评论），`post_ids`（留空表示所有帖子），`delay_minutes`（私信发送前的等待时间），`reply_instructions`（智能体回复的措辞方式）。
`instagram_follower`	有新用户关注了你的 Instagram 账户。需要 Instagram (个人) 连接 — 官方 Instagram 私信连接无法查看粉丝。	`reply_instructions`（可选）。

在没有设置频道默认值的频道上，关键字规则也可以作为一种门控机制使用：不匹配任何关键字的消息不会获得自动回复，而是直接进入您的收件箱，即使是在只有一个坐席的账户中也是如此。

将频道指向某个坐席

PUT /entry-points/channel-defaults — 将一名坐席设为该频道新联系人的应答者。任何当前被设为该频道默认值的其他坐席将在同一次调用中被停用，因此一个频道始终只有一个应答者。将已是默认值的坐席再次设为默认值不会有任何改变。

字段	必填	描述
`channel`	是	频道，例如 `whatsapp`、`whatsapp_web`、`instagram`、`messenger`、`telegram`、`sms`、`email`、`chat_widget` 或 `custom_channel`。
`agent_id`	是	应答的坐席。必须属于您的账户。
`phone_number`	否	将默认值范围限定为此频道上您已连接的号码之一（E.164 格式，带有前导 `+`，与已连接号码下显示的完全一致）。不会更改频道范围内的默认值。请参阅每个 WhatsApp 号码对应一名坐席。

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()

响应

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

entry_point_id 是当前生效的规则；disabled_entry_point_ids 列出了为使其生效而停用的任何规则（如果没有需要替换的规则，则为空）。仅影响您从未联系过的联系人——任何已经与坐席进行对话的人员将保留该坐席。

400 表示缺少 channel 或 agent_id，该坐席属于另一个账户，或者 phone_number 不是您已连接的号码之一。

查看每个频道的应答者

GET /entry-points/channel-defaults — 账户中所有频道的默认设置，按最新排序，包括已停用的频道（enabled: false）以及特意设置为“无人”的频道（agent_id: ""）。在 enabled 上自行筛选以获取当前概览。

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()

响应

{
  "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
    }
  ]
}

这是账户范围内的读取操作。使用 GET /agents/{agentId}/entry-points 列出单个代理的规则无法显示设置为“无人”的频道，因为该规则不属于任何代理。

离开一个无人应答的频道

DELETE /entry-points/channel-defaults?channel=instagram — 停用某个频道的全频道默认设置。频道名称作为查询参数提供，而非在正文中。添加 &phone_number=%2B31685101091 可仅清除该号码的默认设置，并让该号码恢复为由任何应答该频道的人处理。

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()

响应

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

重复操作是安全的：清除一个没有默认设置的频道会返回一个 200 和一个空列表。清除意味着取消设置，而非静音 — 在只有一个活跃代理的账户中，未配置的频道仍会回退到该代理。若要完全禁止 AI 处理某个频道，请在应用程序的“谁来回答新对话”面板中为该频道选择“无人应答”（这会写入一个明确的“无人”默认值，回退机制永远不会覆盖此值），或者使用 PATCH /agents/{agentId}/active 暂停该代理。

每个 WhatsApp 号码对应一个代理

默认情况下，路由是按频道进行的：您所有的 WhatsApp 号码共享一个应答者。当在 WhatsApp Business 或 WhatsApp Web 上连接了两个或更多号码时，默认设置可以限定在单个号码上，因此拥有多个分店或品牌号码的企业可以在同一个账户内为每个号码分配各自的代理。

在设置调用中发送 phone_number：

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"
  }'

该号码必须是您在该渠道上已连接的号码之一，书写格式需与“已连接号码”下方显示的一致（E.164 格式，带有 +）；其他任何格式均为 400。
该规则作为渠道默认设置存储在 match_config.phone_numbers: ["+31685101091"] 中。发送到该号码的消息将转至其对应的坐席；其他所有号码继续遵循渠道范围内的默认设置。
设置或清除渠道范围内的默认设置不会影响号码范围内的规则，反之亦然。使用 DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091 清除某个号码自身的规则。
回复始终通过联系人发送消息的号码发出，因此联系人始终与同一个号码和同一个坐席进行对话。

添加更具体的规则

POST /agents/{agentId}/entry-points — 创建关键字、评论或关注者规则（或渠道默认规则，尽管 PUT /entry-points/channel-defaults 是更好的选择，因为它会为您自动停用之前的应答者）。路径中的坐席始终具有最高优先级：规则永远不能为 URL 中指定的坐席以外的其他坐席创建。

字段	必填	说明
`type`	是	`keyword`、`instagram_comment`、`facebook_comment`、`instagram_follower` 或 `channel_default`。
`channels`	是	规则所涵盖渠道的非空列表。评论规则必须列出其所属的渠道（`instagram` 或 `facebook`）。
`match_config`	取决于类型	请参阅规则类型。关键字规则在 `keywords` 中至少需要一个条目。
`enabled`	否	默认为 `true`。
`first_response_mode`, `first_response_exact_text`, `public_comment_reply_exact_text`	否	入口点对象中描述的首条回复设置。

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()

响应 (201)

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

一个仅对两条特定帖子中包含“LINK”字样的评论做出反应的“评论转私信”规则，等待两分钟后发送固定的第一条消息：

{
  "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!"
}

将 keywords 留空以私信所有评论了受监控帖子的人，将 post_ids 留空以监控所有帖子。400 会指出错误所在：未知的 type、空的 channels、没有关键字的关键字规则，或未列出其所属渠道的评论规则。

列出坐席的规则

GET /agents/{agentId}/entry-points — 将对话发送给此坐席的规则，按最新排序：其渠道默认规则、关键字规则、评论规则和关注者规则。已停用的规则也会通过 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()

响应

{
  "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
    }
  ]
}

修改规则

PUT /entry-points/{entryPointId} — 修改一条规则。仅发送您要更改的字段；嵌套设置可以使用点号键（例如 "match_config.keywords"）逐个叶节点进行寻址。每当更改涉及 type、channels 或 match_config 时，整个规则都会被重新检查，因此部分编辑永远不会导致规则不可用（例如，在未提供关键字的情况下将 type 切换为 keyword 会被拒绝）。发送 agent_id 会将规则移交给您的其他坐席；发送空值会被拒绝。所有权和身份字段将被忽略。

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()

响应

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

其他常见编辑：{ "enabled": false } 可停用规则而不删除它，{ "agent_id": "agOtherAgent" } 可将其移动到不同的坐席。空请求体将返回 400 和 "No fields to update"。

删除规则

DELETE /entry-points/{entryPointId} — 永久删除该规则。没有其他内容引用入口点，因此无需先进行解绑。

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()

响应

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

若要停止规则触发但保留该规则，请将 enabled 设置为 false。特别是渠道默认规则通常是停用而不是删除，这正是 DELETE /entry-points/channel-defaults 所做的。

检查路由是否生效

GET /entry-points/routing-status — 返回“入口点”阶梯是否决定了此账户的应答者。具有查看权限即可读取，因此团队成员看到的应答者与所有者相同。

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

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

目前在每个账户上均为 true。保留此调用是为了让集成在告知某人其路由更改已生效之前进行验证，而不是直接假设其已生效。

较旧的、以营销活动为中心的调用

在“智能体”功能出现之前，有两个端点适用于以营销活动组织的账户。新的集成应使用上述的“渠道默认值”调用。

PUT /channel-routing/{channel} 配合 { "campaignId": "cp5NbV8xQrT2wYzA" } — 指定一个营销活动，该营销活动的智能体将成为渠道的应答者。{ "campaignId": null } 可清除该渠道。仅限外呼的营销活动会被拒绝，因为它无法提供任何入站行为。
POST /channel-routing/clear 配合 { "channels": ["whatsapp", "instagram"] } — 在一次调用中将多个渠道从其当前的应答智能体中释放，通常用于在将它们指向其他位置之前。响应会列出 released_channels，即那些实际拥有应答者的渠道。

两者均为取消设置而非静默：在只有一个活跃智能体的账户上，被释放的渠道仍会回退到该智能体。

入口点 API 错误

入口点端点返回标准的错误封装：

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

状态	在入口点端点上发生的情况
`400`	缺少字段或规则不可用：设置调用时缺少 `channel` 或 `agent_id`、未知的 `type`、空的 `channels`、没有关键字的关键字规则、未列出自身渠道的评论规则、更新时出现空白的 `agent_id`、空的更新主体，或不是您已连接号码之一的 `phone_number`。
`403`	密钥或团队成员可能无法编辑路由。写入操作需要营销活动的编辑权限；列表和状态读取需要查看权限。
`404`	未找到入口点或智能体 — 它们不存在或属于另一个账户。

每个端点都可能返回的共享代码 — 401, 403（您的套餐不包含 API 访问权限）, 429（速率限制）和 500 — 及其重试指南列在错误与分页中。

后续步骤

入口点 — 概念、规则类型以及应用中的 谁来回答新对话 面板。
AI 智能体 API — 创建并配置这些规则所路由到的智能体。
渠道 API — 连接渠道本身。
评论转私信自动化 — 评论规则触发后的执行内容。

入口点 API #

大多数集成所需的唯一调用 #

路由决策方式 #

入口点对象 #

规则类型 #

将频道指向某个坐席 #

查看每个频道的应答者 #

离开一个无人应答的频道 #

每个 WhatsApp 号码对应一个代理 #

添加更具体的规则 #

列出坐席的规则 #

修改规则 #

删除规则 #

检查路由是否生效 #

较旧的、以营销活动为中心的调用 #

入口点 API 错误 #

后续步骤 #

入口点 API

大多数集成所需的唯一调用

路由决策方式

入口点对象

规则类型

将频道指向某个坐席

查看每个频道的应答者

离开一个无人应答的频道

每个 WhatsApp 号码对应一个代理

添加更具体的规则

列出坐席的规则

修改规则

删除规则

检查路由是否生效

较旧的、以营销活动为中心的调用

入口点 API 错误

后续步骤