# 渠道连接 API

本指南介绍了如何使用 API 将消息渠道连接到账户。本文档专为构建集成或包装器的开发人员编写，因此重点介绍了具体的请求、请求顺序以及您收到的响应。

在开始之前，您需要了解一种模式，因为它适用于此处的几乎每个渠道。

## 连接后轮询模式

大多数渠道无法通过单个 API 调用进行连接。连接 WhatsApp、Instagram 或 Messenger 意味着账户持有人必须登录其自己的提供商账户并批准访问权限。该批准过程**没有无头（完全自动化）路径**——必须由真人通过浏览器打开 URL，或使用手机扫描二维码。

因此，流程始终为：

1. **开始连接**：使用 `POST`。响应会为您提供一个要打开的 URL 或要显示的二维码。
2. **移交给最终用户**：在他们的浏览器中打开 URL，或在屏幕上呈现二维码供他们扫描。
3. **轮询状态端点**：使用 `GET` 以短时间间隔（每隔几秒）进行轮询，直到状态达到已连接状态。

您集成的任务是驱动该循环：显示 URL 或二维码，然后轮询直到完成。围绕轮询规划您的 UI——带有“等待您在浏览器中完成”消息的加载转圈效果很好。

::: note
**注意：** 在开始之前，请确保已在套餐中启用 API 访问权限，并且您拥有 API 密钥。请参阅 [API 访问](../integrations/api-access.md) 了解如何生成密钥。以下所有请求均使用基准 URL `https://api.youraiconnector.com/v1`，并且您必须对每个请求进行身份验证。请参阅 [身份验证](authentication.md) 了解四种接受的形式——此处的示例使用 `X-API-Key` 标头，每页包含一个显示更简单的 `?apiKey=` 查询形式的 cURL 示例。
:::


---

## Instagram + Messenger (Meta)

Instagram 和 Messenger 在一个流程中连接在一起，因为它们都运行在 Facebook 页面上。账户持有人通过 Facebook 进行授权，您获取他们管理的页面列表，然后选择要连接的页面。

### 第 1 步 - 启动 Instagram + Messenger 连接

```
POST /channels/meta/connect
```

这将返回一个同意 URL。此请求中不发送任何凭据——连接完全在浏览器中进行授权。

**cURL**

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

**JavaScript**

```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**

```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.
```

**响应**

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

在最终用户的浏览器中打开 `oauth_url`，以便他们可以登录 Facebook 并批准访问权限。连接尝试在 `expires_at`（约 30 分钟）后过期——如果过期，请重新开始。将 `state_token` 视为短期密钥，请勿记录它。

### Instagram + Messenger 最简单的选项：移交 `connect_url`

响应中还包含一个现成的 `connect_url`：一个托管页面，可为账户持有人运行整个流程。他们打开页面，登录 Facebook，如果有多个主页，页面会显示列表并让他们选择要连接的主页，然后会自动报告成功。将此链接提供给账户持有人，而不是自己打开 `oauth_url`、构建主页选择器并进行轮询。该链接的有效期约为 30 分钟（`connect_url_expires_at`）；如果过期，请重新开始连接。以下手动步骤适用于希望自行驱动流程并渲染主页选择器的集成。

### 第 2 步 - 轮询状态直到页面加载完成

```
GET /channels/meta/status
```

用户完成 Facebook 登录后，每隔几秒轮询此端点。 `status` 字段会经历以下步骤：

| `status` | 含义 |
|---|---|
| `pending` | 尚未完成授权。请继续等待。 |
| `token_received` | 已授权，但主页列表仍在加载中。 |
| `pages_loaded` | 主页可用 - 进入第 3 步。 |
| `connected` | 已选择主页，渠道已上线。 |

**cURL**

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

**JavaScript**

```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**

```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".
```

**响应（页面加载完成后）**

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

### 第 3 步 - 列出主页（可选）

如果您想单独获取主页列表（例如，为了渲染选择器），请使用：

```
GET /channels/meta/pages
```

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

它返回与状态端点相同的 `pages` 数组。（`status` 端点已经包含了主页，因此此调用仅为方便起见。）

### 第 4 步 - 选择要连接的主页

```
POST /channels/meta/select-page
```

发送用户所选主页的 `page_id`。链接到该主页的 Instagram 账户会自动连接；如果您想覆盖要使用的 Instagram 账户，才需要 `instagram` 对象。

**cURL**

```bash
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**

```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**

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

**响应**

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

渠道现已连接。后续的 `GET /channels/meta/status` 将报告 `status: "connected"`。

### 列出已连接页面的帖子

```
GET /channels/meta/posts?platform=instagram
```

返回您所连接页面（Instagram 媒体或 Facebook 帖子）的近期帖子。当您设置一个对特定帖子评论做出反应的入口点（Entry Point）时，这就是您用来渲染选择器的内容。

| 查询参数 | 必需 | 描述 |
|---|---|---|
| `platform` | 是 | `instagram` 或 `facebook`。其他任何值都会返回 `400`。 |
| `limit` | 否 | 要返回的帖子数量，范围为 `1`-`50`。默认为 `25`。 |
| `after` | 否 | 下一页的游标 - 传入上一次响应中的 `nextCursor` 值。 |

**cURL**

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

**响应**

```json
{
  "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` 是 Instagram 自己的标签（`REELS`、`FEED`、`STORY` 或格式 - `IMAGE`、`VIDEO`、`CAROUSEL_ALBUM`）；对于 Facebook，它始终是 `POST`。`nextCursor` 在最后一页时为 `null`。

如果无法列出任何内容，调用仍会返回 `200`，其中包含 `connected: false` 和一个空的 `posts` 数组，外加一个说明原因的 `reason`：

| `reason` | 操作建议 |
|---|---|
| _(absent)_ | 尚未连接页面 - 请先运行连接流程。 |
| `no_instagram_account` | 已连接 Facebook 页面，但未关联 Instagram 商业账户。Facebook 帖子仍可正常列出。 |
| `token_expired` | 存储的页面凭据已失效 - 请重新连接该渠道。 |

### 断开 Instagram + Messenger

```
DELETE /channels/meta
```

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

**响应**

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

这将停止 Instagram 和 Messenger 的入站路由。它是幂等的——在未连接任何内容时调用它仍然会成功。

---

## WhatsApp Business

这用于连接官方 WhatsApp Business 号码。在调用连接之前，该号码必须已存在于账户中。与 Meta 一样，账户持有人在浏览器中进行授权，然后您进行轮询，直到号码报告 `ONLINE`。

### 第 1 步 - 启动 WhatsApp Business 连接

```
POST /channels/whatsapp/connect
```

**cURL**

```bash
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**

```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**

```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.
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `phone_number` | 是 | 要连接的号码，采用 E.164 格式（例如 `+14155551234`）。 |
| `only_waba_sharing` | 否 | 将授权限制为共享现有的 WhatsApp Business 账户，跳过新发件人设置。默认为 `false`。 |
| `retry` | 否 | 为之前尝试未完成的号码重新运行授权。默认为 `false`。 |
| `business_name` | 否 | 仅用于同意屏幕上显示的商家名称的修饰性覆盖（最多 256 个字符）。不存储。 |
| `description` | 否 | 仅用于同意屏幕上显示的商家描述的修饰性覆盖（最多 256 个字符）。不存储。 |

**响应**

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

在账户持有人的浏览器中打开 `oauth_url` 进行授权。一旦他们批准，注册将在后台完成。

### 第 2 步 - 轮询状态直到显示 ONLINE

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

轮询此项直到 `status` 为 `ONLINE`。

**cURL**

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

**JavaScript**

```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**

```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".
```

**响应**

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

`status` 字段可以是：

| `status` | 含义 |
|---|---|
| `PENDING` | 已授权，审批仍在进行中。请继续轮询。 |
| `ONLINE` | 已连接并准备好发送。 |
| `RATE_LIMITED` | 尝试次数过多 - 请稍后再试。 |
| `REGISTRATION_FAILED` | 无法完成设置。 |
| `DELETED` | 该注册已不存在。 |

`live: true` 表示状态是实时向提供商查询的；`false` 表示状态来自上次缓存的结果。

### 断开 WhatsApp Business 号码

```
DELETE /channels/whatsapp/{phoneNumber}
```

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

**响应**

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

号码本身会保留在账户中，因此您可以稍后重新连接它。

---

## WhatsApp Web

WhatsApp Web 通过扫描二维码关联常规 WhatsApp 号码，就像在 WhatsApp 应用中关联设备一样。流程为：启动会话，获取并显示二维码，然后轮询直到状态为 `connected`。

### 第 1 步 - 启动 WhatsApp Web 配对会话

```
POST /channels/whatsapp-web/connections
```

**cURL**

```bash
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**

```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**

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

| 字段 | 必填 | 说明 |
|---|---|---|
| `phone_number` | 是 | 要连接的 WhatsApp 号码，采用 E.164 格式。 |
| `proxy_country` | 否 | 路由区域的 ISO 3166-1 alpha-2 国家/地区代码。省略时会自动根据号码检测。 |
| `force_new` | 否 | 丢弃任何现有会话并开始新的配对。默认为 `false`。 |
| `import_contacts` | 否 | 在首次连接时导入设备的现有联系人。默认为 `false`。 |
| `pause_ai_for_imported_contacts` | 否 | 导入联系人时，对他们保持自动回复暂停状态。默认为 `true`。 |
| `import_existing_chats` | 否 | 导入现有聊天记录（需要 `import_contacts: true`）。默认为 `false`。 |

**响应**

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

### WhatsApp Web 最简单的选项：移交 `connect_url`

响应中包含一个现成的 `connect_url`：一个托管页面，它会显示二维码，在二维码轮换时自动刷新，并在号码关联成功后立即切换到成功消息。只需将此链接提供给账户持有人（在浏览器中打开、发送给他们，或将其显示为二维码/按钮），让他们用 WhatsApp 扫描即可——您无需自行获取二维码或进行任何轮询。该链接有效期约为 30 分钟（`connect_url_expires_at`）；如果他们在完成前链接失效，请重新开始连接以获取新的链接。

当用户可以打开链接时，这是推荐的操作路径。下方的手动步骤（自行获取二维码、轮询状态）适用于希望在自己的界面中渲染二维码的集成。

响应还会直接提供您需要使用的确切 `poll_qr_path` 和 `poll_status_path`，因此您无需自行构建它们。

### 第 2 步 - 获取并显示二维码

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

**cURL**

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

**JavaScript**

```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**

```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.
```

**响应**

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

渲染二维码供用户使用手机扫描（WhatsApp > 已关联设备 > 关联设备）：

- `qr_data_url` 是一个可直接使用的图像——直接将其放入 `<img src>` 即可。
- `qr_code` 是原始负载，如果您想自行生成图像，可以使用它。

二维码的有效期很短。如果您在开始会话后立即调用此接口，可能会收到带有“二维码尚未就绪”的 `404`——只需稍等片刻并重试即可。如果您收到 `410`（“二维码已过期”），请重新开始连接以获取新的代码。

### 第 3 步 - 轮询状态直到连接成功

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

**cURL**

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

**JavaScript**

```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**

```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").
```

**响应**

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

| `status` | 含义 |
|---|---|
| `not_initialized` | 尚无会话（终端故障）。 |
| `qr_pending` | 等待扫描二维码。 |
| `connecting` | 已扫描，正在完成设置。 |
| `connected` / `open` | 已关联并在线 - 表示成功。 |
| `disconnected` | 会话已结束（终端故障）。 |

### 断开 WhatsApp Web 会话

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

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

**响应**

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

此操作将取消关联设备并移除连接。它始终会清理本地状态，因此即使底层会话已经不存在，它也是幂等的。

---

## Telegram

> **可用性：** Telegram 的连接方式与其他渠道相同，且对所有账户开放 — 您无需专门开启此功能。如果账户套餐中未包含 Telegram，下方的 Telegram 端点仍可能返回 `403`，此时错误信息将显示为 `"This channel is not included in your current plan. Upgrade to unlock it."`。

Telegram 通过电话号码加上一次性登录代码（如果账户设置了双重验证，还需加上双重验证密码）来连接个人账户。流程为：开始会话、提交代码、可选地提交密码，然后通过状态确认。

### 第 1 步 - 启动 Telegram 连接会话

```
POST /channels/telegram/connect
```

**cURL**

```bash
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**

```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**

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

| 字段 | 必填 | 说明 |
|---|---|---|
| `phone_number` | 是 | 要连接的账户电话号码，采用 E.164 格式。 |
| `mode` | 否 | `code`（默认）向账户发送一次性登录验证码；`qr` 返回一个登录令牌和用于显示的 QR URL。 |
| `proxy_country` | 否 | 用于出站网络路由的 ISO 3166-1 alpha-2 国家/地区代码。 |
| `force_new` | 否 | 当为 `true` 时，丢弃任何现有会话并重新开始。 |

**响应**

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

在 `code` 模式下，账户会在 Telegram 中收到登录验证码，且 `status` 为 `code_required`。（在 `qr` 模式下，响应还包含 `login_token` 和用于扫描显示的 `qr_url`，且 `status` 为 `qr_required`。）

### Telegram 最简单的选项：移交 `connect_url`

响应包含一个现成的 `connect_url`：一个可自行完成连接的托管页面。在 `code` 模式下，账户持有人输入登录验证码（如果账户启用了两步验证，还需输入密码）。在 `qr` 模式下，页面会显示一个自动刷新的二维码，供用户使用 Telegram 应用扫描。无论哪种方式，它都会自动报告成功，因此您可以直接将此链接提供给账户持有人，而无需自行构建 UI 和轮询。该链接有效期约为 30 分钟（`connect_url_expires_at`）；如果过期，请重新开始连接以获取新的链接。

以下手动步骤（自行收集验证码、提交并轮询状态；或渲染 `qr_url` 并轮询）适用于希望自行渲染 UI 的集成。

### 第 2 步 - 提交登录验证码

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

**cURL**

```bash
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**

```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**

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

**响应**

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

如果 `status` 为 `connected`，则操作完成。如果账户启用了双重验证，`status` 将变为 `password_required` —— 请转到第 3 步。

### 第 3 步 - 提交双重验证密码（仅在需要时）

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

仅在第 2 步返回 `password_required` 时调用此接口。

**cURL**

```bash
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**

```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**

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

**响应**

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

### 检查 Telegram 状态

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

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

**响应**

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

`status` 可以是 `connected`、`code_required`、`password_required`、`initializing`、`disconnected`、`not_initialized` 或 `error`。

### 断开 Telegram

```
DELETE /channels/telegram/{phoneNumber}
```

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

**响应**

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

幂等操作——重复调用均会成功。

---

## Instagram（个人账户）

> 有限可用性的测试版，按账户启用。此功能通过用户名和密码登录个人 Instagram 账户（非官方 Business API）。如果账户未启用该测试版，连接调用将返回权限错误。

由于这需要账户持有人自己的 Instagram 登录信息，最简单的途径是提供托管的 `connect_url`，让他们在那里输入凭据——您的集成永远不会处理密码。

### 第 1 步 - 启动 Instagram（个人）连接

```
POST /channels/instagram-private/connect
```

发送 Instagram `username` 和 `password`。

**响应**

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

如果账户启用了双重验证或 Instagram 触发了检查点（checkpoint），`status` 将返回 `two_factor_required` 或 `challenge_required` - 请将代码提交至下方的 `/connect/{id}/verify-2fa` 或 `/connect/{id}/verify-challenge`，然后轮询 `/connect/{id}/status` 直到返回 `connected`。`{id}` 是上述响应中作为 `account_id`/`username` 返回的标准化 Instagram 用户名 - 请在下方的每个步骤中使用它。

### 第 2 步 - 提交双重验证码（如果被要求）

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

仅在第 1 步（或第 3 步）返回 `two_factor_required` 时调用此接口。

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

**响应**

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

`status` 可能返回 `connected`（完成）、`two_factor_required`（代码错误，请重试）或 `challenge_required`（Instagram 同时要求检查点代码 - 请转至第 3 步）。

### 第 3 步 - 提交检查点确认码（如果被要求）

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

仅在之前的步骤返回 `challenge_required` 时调用此接口。请求和响应格式与上述第 2 步相同。

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

### 检查 Instagram（个人）状态

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

轮询此接口直到 `status` 为 `connected`，或者直到它报告最终失败。

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

**响应**

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

`status` 可以是 `connected`、`two_factor_required`、`challenge_required`、`initializing`、`disconnected`、`not_initialized` 或 `error`。`live: true` 表示这是直接从连接工作进程读取的实时值，而非缓存值。

### Instagram（个人）最简单的选项：移交 `connect_url`

响应包含一个 `connect_url`：这是一个托管页面，账户持有人可以在其中输入其 Instagram 用户名和密码（如果 Instagram 要求，还需输入 2FA 或检查点代码），该页面会自动报告成功。凭据会直接发送至 Instagram，不会被存储。请将此链接提供给账户持有人，而不是在您自己的 UI 中收集他们的密码。该链接的有效期约为 30 分钟（`connect_url_expires_at`）。

### 断开 Instagram（个人）连接

```
DELETE /channels/instagram-private/{id}
```

幂等操作——重复调用均会成功。

### 同步关注者

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

手动触发已连接账户的关注者同步——这与后台自动运行的任务相同，此处将其公开为按需执行的“刷新关注者”操作。它会获取账户当前的关注者列表，记录新增人员，并在开启了关注者外联的“实时”活动中，向新关注者发送开场私信（受每日上限限制）。

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

**响应**

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

> 这五个字段是页面上唯一返回 `camelCase` 而不是 `snake_case` 的地方——这是该端点目前的配置方式，并非拼写错误。`isBaselineSeed: true` 表示这是连接后的首次同步，仅记录初始关注者列表，不会发送外联私信（因此在该次运行中 `dmsSent` 始终为 `0`）。

账户的首次调用可能需要较长时间（遍历完整的关注者列表）；后续调用速度更快，因为只需对比新增的关注者。`404` 表示账户未连接；`412` 表示连接尚未完成初始化——请稍候重试。

---

## LINE

LINE 是最简单的连接渠道，因为它不需要浏览器重定向或轮询。客户在 LINE 开发者控制台中创建一个 Messaging API 渠道，复制两个值，然后您通过单次调用提交它们。随后，您将获得一个 Webhook URL，供客户粘贴到控制台中。

### 第 1 步 - 使用渠道凭据进行连接

```
POST /channels/line
```

**cURL**

```bash
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**

```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**

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

| 字段 | 必填 | 描述 |
|---|---|---|
| `channel_access_token` | 是 | 官方账号的长期 Messaging API 渠道访问令牌。用于发送和接收消息。 |
| `channel_secret` | 是 | Messaging API 渠道密钥，用于验证入站事件签名。 |
| `channel_id` | 否 | 数字渠道 ID。仅供参考。 |

**响应**

```json
{
  "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/..."
}
```

对于接下来的操作，有两个字段非常重要：

- **`webhook_url`** - 客户必须将其粘贴到 LINE 开发者控制台中其 LINE 渠道的 **Webhook URL** 字段中（并启用“使用 Webhook”）。在他们完成此操作之前，不会收到任何入站消息。请在界面中显著展示此内容。
- **`chat_mode_ok`** - 当 `false` 时，官方账号处于“聊天”模式，在 LINE 官方账号管理器中切换到“机器人”模式之前，它不会接收或发送消息。请根据此标志设置您的引导流程，并告知客户切换模式。

> `channel_access_token` 和 `channel_secret` 不会由任何端点返回。如果您以后还需要它们，请务必在您的一侧存储；否则，请从 LINE 控制台重新复制。

此处返回的 `bot_user_id` 是您在下方的状态、验证和断开连接调用中使用的连接标识符。

### 第 2 步 - Webhook 设置后重新验证

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

在客户完成配置 Webhook URL 并切换到机器人模式后，调用此接口以重新验证存储的令牌并刷新缓存的聊天模式。

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

**响应**

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

如果 `token_valid` 为 `false`，则存储的访问令牌不再有效——请让客户在控制台中重新颁发令牌，并使用新令牌再次调用 `POST /channels/line`。

### 检查 LINE 状态

```
GET /channels/line/{botUserId}/status
```

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

**响应**

```json
{
  "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 没有实时状态推送，因此这里的 `live` 始终为 `false`——这些值反映了连接（或上次验证）时捕获的状态。

### 断开 LINE 连接

```
DELETE /channels/line/{botUserId}
```

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

**响应**

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

---

## Viber

Viber 的连接方式与 LINE 相同——在一次调用中粘贴 Viber 管理面板中的机器人授权令牌——但有一点值得注意：连接时会立即在您的机器人上注册我们的 Webhook，因此之后无需单独的控制台步骤。这也意味着，如果我们的入口无法响应 Viber 的同步 Webhook 检查，连接尝试可能会失败，而不仅仅是因为令牌本身错误。

### 第 1 步 - 使用机器人授权令牌连接

```
POST /channels/viber
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `auth_token` | 是 | 机器人授权令牌，来自 Viber 管理面板（我的机器人设置）。 |

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

**响应**

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

授权令牌不会被任何端点回显——如果您需要重新粘贴，请在您的一侧妥善保存。`bot_id` 是下文状态、验证和断开连接调用中使用的连接标识符。

### 检查 Viber 状态

```
GET /channels/viber/{botId}/status
```

报告已存储的连接状态。添加 `?live=true` 可同时针对 Viber 重新检查机器人并刷新缓存的 Webhook 注册——在假设静默的机器人已损坏之前，此操作非常有用。

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

**响应**

```json
{
  "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` 表示机器人的 Webhook 不再指向我们——入站消息已中断。这通常意味着其他工具随后连接了同一个机器人（Viber 的 Webhook 注册遵循“最后写入生效”原则）。使用下方的重新验证调用即可修复，无需让客户重新粘贴令牌。`live` 为 `false` 时，表示响应是最后缓存的状态，而非针对 Viber 的实时检查。

### 重新注册 Webhook

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

`webhook_ok: false` 的修复操作——使用已存储的授权令牌在机器人上重新注册我们的 Webhook。

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

**响应**

```json
{ "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` 表示已存储的令牌不再有效——请使用 `POST /channels/viber` 和新的令牌重新连接。

### 断开 Viber 连接

```
DELETE /channels/viber/{botId}
```

在 Viber 端注销我们的 webhook（尽力而为），并移除连接。

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

**响应**

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

---

## TikTok

> **可用性：** 有限可用性测试版，按账户启用。在账户启用之前，连接 TikTok 会返回权限错误。

TikTok 商业消息（TikTok Business Messaging）是一个像 Meta 一样的完整 OAuth 渠道，但在轮询方面更简单：无需构建专门的状态轮询步骤，因为一旦 TikTok 重定向回来并写入连接，已连接的账户就会自动显示。下方的状态端点仅用于按需确认状态（支持工具、健康检查），而不是你在连接过程中需要循环调用的内容。

### 第 1 步 - 启动 TikTok 连接

```
POST /channels/tiktok/connect
```

无需凭据 - 账户持有人完全在自己的浏览器中进行授权。

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

**响应**

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

在账户持有人的浏览器中打开 `oauth_url`，以便他们登录 TikTok 并批准访问权限。该状态在 `expires_at`（约 30 分钟）后过期 - 如果过期，请重新开始。TikTok 没有 `connect_url` 托管页面快捷方式；自行打开 `oauth_url` 是唯一的途径。

### 检查 TikTok 状态

```
GET /channels/tiktok/{openId}/status
```

`openId` 是 TikTok 商业账户的 open_id，在 OAuth 回调运行后可知。

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

**响应**

```json
{
  "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 没有低成本的实时健康检查，因此 `live` 在此处始终为 `false` - 这些字段反映了连接（或上次令牌刷新）写入的内容。`status: "reauth_required"` 且 `status_reason` 被设置意味着账户需要重新进行连接；TikTok 令牌会自动按年度轮换刷新，如果该轮换失败，就会显示此状态。

### 断开 TikTok 连接

```
DELETE /channels/tiktok/{openId}
```

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

**响应**

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

---

## GoHighLevel

GoHighLevel (GHL) 是一种 CRM 集成，而非消息渠道 - 连接它不会占用套餐中的渠道配额，因为它使用的是账户现有的渠道，而不是添加新渠道。它也是本页面中唯一可以**同时拥有多个连接**的集成：客户安装该应用的每个 GHL 子账户（“位置”）都会获得其自己的条目。

### 第 1 步 - 启动 GHL 连接

```
POST /channels/ghl/connect
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `brand` | 否 | 要通过其进行授权的 GHL 市场列表。默认为标准列表 - 仅当您的部署配置了多个市场应用时才相关。 |

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

**响应**

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

在账户持有人的浏览器中打开 `oauth_url`，以便他们可以选择一个 GHL 位置并批准访问权限。该状态将在 `expires_at`（约 30 分钟后）过期。

### 列出 GHL 连接

```
GET /channels/ghl/status
```

与其他渠道不同，这不是单个连接的状态，而是列出了账户已连接的所有位置。

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

**响应**

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

### 断开 GHL 位置连接

```
DELETE /channels/ghl/{locationId}
```

删除此处的连接，这将停止该位置的所有同步和触发器。这不会卸载 GHL 端的应用 - 如果客户希望卸载，需要从他们的 GHL 市场安装中移除该应用。

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

**响应**

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

---

## 电话号码（购买和释放）

您可以直接购买支持 WhatsApp 的新号码，而不是连接现有号码。搜索可用号码，购买一个，然后轮询直到其完成配置。

::: note
**注意：** 此处购买的号码支持 WhatsApp。购买后，WhatsApp 发送方注册会在后台运行，因此您需要轮询状态，直到其达到 `ONLINE` 才能发送消息。购买时会扣除额度，且在释放号码时**不予**退还。
:::


### 第 1 步 - 搜索可用号码

```
GET /phone-numbers/available?country_code=ISO2
```

**cURL**

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

**JavaScript**

```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**

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

| 查询参数 | 必需 | 描述 |
|---|---|---|
| `country_code` | 是 | 要搜索的 ISO 3166-1 alpha-2 国家/地区代码（例如 `US`、`GB`、`NL`）。 |
| `type` | 否 | 首选号码类别，`local` 或 `mobile`。搜索结果可能仍会返回两种类别。 |

**响应**

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

每个结果都会显示一次性 `purchase_credits` 和周期性 `monthly_credits`。平台提供的号码每月至少需要 50 个积分，并随运营商的每月价格上涨，在购买和每次续订时扣除。请引用搜索返回的 `purchase_credits` / `monthly_credits`；切勿自行推算价格。新账户的首次搜索会配置一些底层资源，因此可能比后续搜索稍慢。

### 第 2 步 - 购买号码

```
POST /phone-numbers
```

使用搜索结果中的 `phone_number`。

**cURL**

```bash
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**

```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**

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

| 字段 | 必填 | 描述 |
|---|---|---|
| `phone_number` | 是 | 通过可用号码搜索返回的号码，采用 E.164 格式。 |
| `country_code` | 是 | ISO 3166-1 alpha-2 国家/地区代码（例如 `US`）。 |
| `display_name` | 否 | 友好标签。默认为电话号码。 |
| `category` | 否 | 可选的类别标签。 |

**响应**

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

该号码以 `PURCHASED` 状态开始。WhatsApp 注册随后在后台进行：`PURCHASED` -> `PENDING` -> `ONLINE`。

> 如果因缺少企业地址或其他必需详细信息未设置而导致购买失败，您将收到一个带有描述性 `error` 的 `400`。请设置缺失的详细信息并重试。

### 第 3 步 - 轮询直到状态为 ONLINE

```
GET /phone-numbers/{phoneNumber}/status
```

这是共享电话号码状态端点 - 它既适用于已购买的 WhatsApp 号码，也适用于您连接的其他号码。

**cURL**

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

**JavaScript**

```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**

```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".
```

**响应**

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

### 第 4 步 - 释放号码

```
DELETE /phone-numbers/{phoneNumber}
```

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

**响应**

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

此操作的具体效果取决于该号码的归属。

对于**通过平台租用**的号码，这是一个真正的释放操作：WhatsApp 发送方会被注销，号码会被交还给运营商并从账户中移除，同时会应用 7 天的冷却期，在此期间任何人均无法重新购买该号码，且不会退还任何积分。

对于一个**由账户自行提供**的号码（其自己的 Twilio 账户、其自己的 Meta 应用或 WhatsApp Business 账户，或 Android 短信网关），相同的调用只会将其从账户中移除。上游提供商处不会释放任何内容，也不会写入冷却时间，因此可以立即重新连接该号码。其 WhatsApp 发送方注册（如果有）可能会保留，也可能不会：拆除过程会尝试使用账户的平台托管 Twilio 凭据删除发送方。在仍处于托管设置的账户上，这些凭据有效且发送方会被删除，因此重新连接意味着需要再次注册。在已切换到其自有 Twilio 的账户上，删除操作无法进行身份验证，发送方会保留在该账户中注册的状态——此时重新连接仅需重新挂载现有的发送方。

### 添加您已拥有的号码 (BYO)

```
POST /phone-numbers/byo
```

完全跳过上述搜索和购买流程。当账户自带号码（他们自己的 Twilio、他们自己的 Meta WhatsApp 商业账户或 Android 短信网关）而不是通过平台租用号码时，请使用此功能。这仅记录号码 - 不会扣除任何积分，也不会在此处配置任何服务提供商。在账户持有人完成 WhatsApp OAuth 以在其上注册发送方（与仪表板的“自带号码”按钮启动的流程相同）之前，该号码将保持非活动状态。

| 字段 | 必填 | 说明 |
|---|---|---|
| `phone_number` | 是 | 要添加的号码，采用 E.164 格式（例如 `+14155551234`）。 |
| `country_code` | 是 | ISO 3166-1 alpha-2 国家/地区代码（例如 `US`）。 |
| `display_name` | 否 | 友好标签。默认为电话号码。 |
| `category` | 否 | 可选的类别标签。 |

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

**响应** (`201 Created`)：

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

非真实 E.164 号码（或看起来像 Meta 的 WhatsApp 测试号码，该号码无法向真实客户发送消息）的 `phone_number` 会返回 `400`。添加账户中已存在的号码（即使拼写略有不同，例如墨西哥的 `+52` 与 `+521` 格式）会返回 `409`，而不是创建重复行。

### 将号码设为主要号码

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

将一个号码切换为 `is_active: true`，并将账户上的所有其他号码切换为 `is_active: false`，此操作是原子的 - 账户在请求过程中永远不会出现两个活动号码或没有活动号码的情况。`is_active` 不能通过常规更新端点进行设置；此专用调用是更改主要号码的唯一方法。

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

**响应**

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

此处的 `phone_number` 是完整的号码对象（与 `GET /phone-numbers` 返回的形状相同），而不仅仅是字符串。如果 `phoneNumber` 不在账户中，则返回 `404`。

### 删除号码记录（不释放号码）

```
DELETE /phone-numbers/{phoneNumber}/record
```

直接删除此账户上的号码记录 - 不涉及服务提供商端的释放或注销，也不适用上述释放步骤中的 7 天冷却期。使用此功能可清除 BYO、WhatsApp Web、Telegram 或 LINE 记录，或过时的条目，而无需经过托管释放流程。与释放不同，删除账户中不存在的号码会返回 `404`，而不是静默成功。

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

**响应**

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

---

## 将渠道路由至营销活动

连接渠道可以将消息**导入**账户。它并不决定**由哪个 AI 智能体来回复这些消息**。

路由由 AI 智能体上的**入口点 (Entry Points)** 处理，而不是由营销活动处理。每个渠道都有一个渠道默认入口点，用于指定在该渠道上回答新的、未知联系人的智能体：

| 您想做什么 | 调用 |
|---|---|
| 将渠道指向应回答该渠道的智能体 | `PUT /entry-points/channel-defaults`，主体为 `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| 检查账户的入口点层级是否已启用 | `GET /entry-points/routing-status`，一旦入口点决定了该账户的路由，它将返回 `{ "success": true, "cutover_enabled": true }` |
| 使渠道处于无智能体回答的状态 | `DELETE /entry-points/channel-defaults?channel=instagram` |

在频道拥有入口点（Entry Point）之前，来自陌生人的第一条消息虽然会被存储，但不会被任何程序获取，也不会有助手进行回复。这是大多数集成最容易忽略的一步：仅连接 Instagram 并创建代理（Agent）是不够的——你还必须将频道指向该代理。完整的调用集（包括每个 WhatsApp 号码对应一个代理、关键词和评论规则）请参阅 [Entry Points API](entry-points.md)。

`POST /channels/campaign` 仍然会写入下文记录的旧版按渠道营销活动路由映射，但任何账户的入站路由都不再参考该映射；它仅保留用于回滚。请勿基于此进行开发。

### 路由一个或多个渠道（旧版营销活动路由映射）

`POST /channels/campaign`

**请求字段**

| 字段 | 必填 | 描述 |
|---|---|---|
| `campaign_id` | 是 | 应回复这些渠道上新联系人的营销活动。必须属于该账户。 |
| `channels` | 是 | 一个非空的渠道数组，用于路由。允许的值：`whatsapp`, `whatsapp_web`, `telegram`, `instagram`, `messenger`, `chat_widget`, `custom_channel`, `sms`, `email`。 |

路由槽位和营销活动的 `enabled_channels` 列表会在一次原子操作中同时更新，因此它们永远不会出现不一致。如果某个渠道已经路由到了另一个营销活动，它会被直接重新指向当前活动。

**cURL**

```bash
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**

```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**

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

**响应**

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

### 路由实际生效的前提条件

在仍读取旧版营销活动路由映射的账户上，路由作为 API 调用会成功，但营销活动上的三件事决定了真实的入站消息是否会被回复。当已路由的渠道保持静默时，请检查这三项。

| 要求 | 否则会发生什么 |
|---|---|
| `type` 为 `Incoming from Unknown Contacts` 或 `Combined` | 请求被拒绝，返回 `400`。外呼和关键词营销活动无法占用路由槽位。 |
| `status` 为 `Live` | 路由已存储但从不获取任何内容。`Draft` 营销活动是导致“我路由了它但没有任何反应”的最常见原因。 |
| `ai_mode` 为 `true` | 联系人已创建且消息已存储，但助手从不回复。 |

关键词匹配现在位于入口点上——在应回答的 AI 智能体上创建一个类型为 `keyword` 的入口点。

### 每个渠道对应一个营销活动

每个渠道恰好拥有一个旧版路由槽位。将第二个营销活动路由到同一渠道会静默地重新指向该槽位并返回 `200` ——不存在冲突错误。之前的营销活动会继续处理它已有的联系人；它只是停止接收新的联系人。

### 清除渠道路由

`DELETE /channels/campaign/{channel}`

移除单个渠道的路由（无论它当前指向哪个营销活动），并将该渠道从该营销活动的 `enabled_channels` 中移除。该渠道上的新未知联系人将不再被任何营销活动处理。已在营销活动中的联系人将照常继续。

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

**响应**

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

它是幂等的：清除一个从未设置路由的渠道也会返回 `200`，并带有 `cleared: false` 和 `campaign_id: null`。此端点需要套餐中包含 **入站营销活动** 功能；否则您将收到 `403`。


---

## 使用您自己的 Meta 应用 (Instagram + Messenger)

默认情况下，Instagram + Messenger 连接通过平台的 Meta 应用运行，因此账户持有者在 Facebook 同意屏幕上看到的是该应用的名称。如果您希望同意屏幕显示**您**的品牌，您可以注册自己的 Meta 应用并将整个流程路由至该应用。配置完成后，它将应用于您的账户——除了品牌标识外，上述连接调用中的任何内容都不会改变。

> **这仅涵盖 Instagram + Messenger。** WhatsApp、WhatsApp Web、Telegram 和 LINE 连接不受自定义 Meta 应用的影响。

### 您的应用首先需要什么

这一部分比较耗时，且完全在 Meta 端进行：

1. **一个**“商务”类型的应用，并添加了 Messenger 和 Instagram 产品。
2. **高级访问权限**（通过 Meta 应用审核）用于：`pages_show_list`、`pages_messaging`、`pages_manage_metadata`、`pages_read_engagement`、`instagram_basic`、`instagram_manage_messages`。如果没有高级访问权限，只有在您的应用中拥有角色的用户才能完成连接——您的客户将无法连接。应用审核通常需要几周时间，并且需要进行商务验证。
3. **在您的应用内创建的 Facebook 商务登录配置**，并授予相同的权限。其数字配置 ID 是针对每个应用唯一的，因此您必须创建自己的配置。

如果您的应用缺少任何必需的权限，连接将在连接时失败，并显示明确的错误信息，指出缺少的内容（在 `/status` 轮询中显示为 `byo_app_missing_permissions`）——而不是看起来成功了但在发送第一条消息时才失败。

### 第 1 步 - 保存您的应用

`PUT /account-config/meta-app`

| 字段 | 必填 | 描述 |
|---|---|---|
| `app_id` | 是 | 您的 Meta 应用 ID（设置 → 基本）。 |
| `app_secret` | 是 | 您的 Meta 应用密钥。在存储前会与 Meta 进行验证，然后加密。任何端点都不会返回此密钥。 |
| `config_id` | 是 | 您应用内 Facebook 商务登录配置的数字 ID。 |

Facebook 登录流程需要这三项。如果你只运行下文所述的 Instagram 登录令牌推送通道，则可以完全省略它们。

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

**响应**

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

### 第 2 步 - 配置您的应用以与我们通信

在您的 Meta 应用控制面板中：

1. **Webhooks** - 对于 Instagram 和 Messenger 产品，将回调 URL (Callback URL) 设置为响应中匹配的 `webhook_urls` 值，并将验证令牌 (Verify token) 设置为 `verify_token`。订阅 `messages`、`messaging_postbacks` 和 `comments` 字段。
2. **有效的 OAuth 重定向 URI** - 添加 `https://api.youraiconnector.com/v1/auth-meta-callback-handler` 以便授权流程可以返回。

`GET /account-config/meta-app` 随时返回相同的设置材料；`DELETE /account-config/meta-app` 会移除应用（未来的连接将恢复为平台应用——同时请移除您应用内的 Webhook 订阅）。

### 第 3 步 - 照常连接

其他内容均无变化。`POST /channels/meta/connect`（以及托管的 `connect_url` 页面）会自动为您的账户使用您的应用；响应中的 `uses_byo_meta_app: true` 会确认同意屏幕将显示哪个应用。消息发送、页面选择和断开连接的工作方式完全相同。

## 使用您自己的 Instagram 登录应用（令牌推送）

上一节介绍了 Facebook 登录流程，即通过 Facebook 公共主页连接账户。Meta 还提供了 **Instagram API 和 Instagram 登录**（Instagram 商家登录）功能：账户持有人直接在 Instagram 上进行身份验证，无需涉及 Facebook 账户或公共主页。

如果您的平台已经运行了带有该产品的 Meta 应用，则完全不需要使用我们这边的任何 OAuth 流程。您的客户只需授权**您的**应用，然后您将每个账户完成的凭据推送给我们即可：

1. 您保存一次 Instagram 应用的凭据（以便我们验证您的 Webhook）。
2. 针对每个账户，您推送 Instagram 专业账户 ID 以及您的应用获取的 Instagram 长期用户令牌。
3. 您将应用的 Instagram 消息 Webhook 指向我们。对于您未推送的账户，其事件将被确认并忽略。
4. 您负责令牌的生命周期：在您自己的系统中刷新令牌，并使用相同的调用推送每个已刷新的令牌。我们不会刷新任何推送的令牌。

### 您的应用首先需要什么

- 添加到您的 Meta 应用中的 **Instagram** 产品（“API 设置与 Instagram 登录”）。该产品拥有**自己的应用编号 (App ID) 和应用密钥 (App Secret) 对**，与 Facebook 的应用编号/密钥分开——您可以在产品的设置面板中找到它们。
- `instagram_business_basic` 和 `instagram_business_manage_messages` 的**高级访问权限**（通过 Meta 应用审核）（如果您使用评论自动化，请添加 `instagram_business_manage_comments`）。如果没有此权限，只有在您的应用中拥有角色的用户才能对其进行授权。

### 第 1 步 - 保存您的 Instagram 应用凭据

使用与上述相同的端点——将 Instagram 对发送至 `PUT /account-config/meta-app`。此通道不需要 Facebook 字段：如果你只运行 Instagram 登录，则单独发送该对；如果你两者都运行，则与 Facebook 字段一起发送。保存操作始终描述整个设置，因此你遗漏的任何设置都将被移除。

| 字段 | 必需 | 描述 |
|---|---|---|
| `instagram_app_id` | 是（组合） | Instagram 产品自己的数字应用编号（非 Facebook 应用编号）。 |
| `instagram_app_secret` | 是（组合） | Instagram 产品自己的应用密钥。静态加密，从不返回。 |

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

**响应** — 包含 Instagram 登录 Webhook URL（`instagram` 和 `messenger` URL 仅在同时存储了 Facebook 字段时才会出现）：

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

在您应用的 Instagram 产品 **Webhook** 面板中，将回调 URL 设置为 `webhook_urls.instagram_login`，将验证令牌设置为 `verify_token`，并订阅 `messages` 和 `comments` 字段。

### 第 2 步 - 为每个账户推送令牌

`PUT /channels/instagram-login/token`

与 `sub_account_id` 一样适用于所有其他路由，因此代理密钥可以配置其整个账户群。

| 字段 | 必需 | 描述 |
|---|---|---|
| `ig_user_id` | 是 | **Instagram 专业账户 ID** — 来自 `GET https://graph.instagram.com/v21.0/me?fields=user_id,username` 的 `user_id` 字段。这与 Instagram Webhook 中作为 `entry.id` 携带的 ID 相同。⚠️ 它**不是**来自 `/me` 的 `id` 字段——该字段是应用范围内的，且在不同的 Meta 应用中各不相同。推送应用范围内的 ID 会返回一个 `400` 指出该错误。 |
| `access_token` | 是 | 您的应用为该账户获取的 Instagram 长期用户令牌。在存储前会针对 Instagram 进行实时验证：令牌必须有效且必须属于 `ig_user_id`。 |
| `expires_at` | 否 | 令牌的 ISO-8601 过期时间。或者发送 `expires_in`（秒）。默认为 60 天。 |
| `username` | 否 | 账户的 @handle；无论如何我们都会从 Instagram 读取它。 |

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

**响应**

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

作为推送的一部分，我们会将您的应用订阅到该账户的 Webhook（使用推送的令牌 `subscribed_apps`），因此消息无需您进行任何额外调用即可开始传输。

**刷新** - 将刷新后的令牌推送到具有相同 `ig_user_id` 的同一端点；它会就地更新存储的令牌和过期时间。

**冲突** - 一个 Instagram 账户绝不会同时在两个连接上处于活动状态。如果该账户已在其他地方连接，或者通过 Facebook 页面流程在此账户上连接，则推送会返回一个 `409`，告知您应先断开哪个连接。Facebook 流程连接绝不会被自动替换，因为它可能还在为 Messenger 提供服务。

### 第 3 步 - 客户端离开时断开连接

`DELETE /channels/instagram-login/token`（相同的身份验证和 `sub_account_id`）会尽力取消订阅 Webhook 并删除存储的凭据。即使令牌已经失效，它也总是会成功——一旦凭据被删除，该账户的 Webhook 事件就会被忽略。

---

## 构建可靠包装器的提示

- **温和轮询。** 每隔几秒钟就足够了。一旦达到终止状态（`connected` / `ONLINE` 或失败状态）请停止，并为循环设置一个合理的总超时时间（浏览器/二维码步骤会过期，请参阅每个 `expires_at`）。
- **对路径中的电话号码进行 URL 编码。** 开头的 `+` 应发送为 `%2B`。端点也可以恢复纯数字，但编码是安全的默认做法。
- **永远不要期望返回机密信息。** 访问令牌、渠道机密和页面令牌会被接受或存储，但绝不会在任何响应中返回。
- **处理身份验证门控。** `403` 表示 API 访问不在套餐内，或者您正在连接的渠道未包含在账户的套餐中。请参阅 [API 访问](../integrations/api-access.md)。
- **注意速率限制。** 经过身份验证的请求上限为每分钟 300 次；`429` 表示请稍后再试。请参阅 [身份验证](authentication.md)。

## 后续步骤

- [身份验证](authentication.md) - 四种已接受的身份验证形式及错误格式。
- [API 访问](../integrations/api-access.md) - 生成和管理您的 API 密钥。