# API 访问

API（应用程序编程接口）是不同软件系统之间进行通信的一种方式。<span data-t="appName">Your AI Connector</span> API 允许您（或您的开发人员）自动创建联系人、发送消息、管理列表以及从自定义渠道接收传入消息——所有这些都无需使用仪表板。


**为什么要使用 API？** 如果您想将应用程序连接到没有内置集成的工具，或者需要大规模自动化重复性任务，API 就是实现这一目标的方法。

::: note
**注意：** 本页面性质偏向技术。如果您是企业主而非开发人员，建议您将此页面分享给您的技术团队或自由职业开发人员。
:::


---

## 生成您的 API 密钥

::: note
**注意：** API 访问是符合条件的套餐中提供的一项付费功能。如果您的套餐不包含此功能，API 请求将被拒绝并返回 `403` 响应。如果不确定是否启用了 API 访问，请检查您的套餐或联系支持团队。
:::


1. 在左侧边栏中，点击 **Settings**（齿轮图标）。
2. 在 Settings 侧边栏的 **Integrations** 组下，点击 **API Key**。


3. 如果您还没有密钥，请点击 **Generate API key**。
4. 如果您已经拥有一个密钥，它将以掩码形式显示在 **Your key** 下方。如果您的密钥支持，请点击 **Show** 以显示它，然后点击 **Copy** 进行复制——您将看到一条确认提示。
5. 请将密钥存放在安全的地方——每次 API 请求都需要用到它。


::: note
**注意：** 部分账户会看到“Your key can't be displayed”而不是 Show/Copy 控件——这是因为密钥是在应用程序支持重新显示功能之前创建的。该密钥仍然可以正常工作；只有在确实需要再次查看明文时，才需要使用 **Regenerate**（在密钥卡片下方，同一部分中）。重新生成会立即作废旧密钥，并导致所有使用该密钥的集成失效，直到您粘贴新密钥为止——请在重新生成后立即更新您的集成。
:::


::: warning
**重要提示：** 您的 API 密钥就像密码一样——它授予对您账户的完全访问权限。请勿公开分享或将其发布在他人可见的地方。如果您认为密钥已泄露，请立即重新生成。
:::


> **团队成员：** API 密钥属于账户所有者，因此如果您是以受邀团队成员（包括管理员）身份登录，该部分将显示一条说明，而不是密钥。请以账户所有者身份登录以查看、复制或重新生成密钥——这也适用于作用域密钥。

> **在哪里查找：** **API Key** 是 Settings → Integrations 下的一个独立部分，与 **Webhooks** 分开。如果指南或同事告诉您在“Webhooks”下查找密钥，请查看旁边的部分。

---

## 基础 URL

所有 API 请求均使用以下基础网络地址：

```
https://api.youraiconnector.com/v1/
```

---

## 身份验证

每个请求都必须包含您的 API 密钥，以便平台识别您的身份。最简单的方法是将其添加到网址末尾：

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

您也可以将密钥作为请求标头发送，而不是放在 URL 中（建议在生产环境中使用，这样密钥就不会出现在服务器日志中）：

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

所有请求都必须使用安全连接 (HTTPS)。不安全的 (HTTP) 请求将被拒绝。

> **正在寻找完整的开发者指南？** 本页面是涵盖最常见操作的快速入门。如需完整的、分步指南（包含每个资源以及 cURL、JavaScript 和 Python 示例），请参阅 [API 入门](../api/getting-started.md) 和 [API 参考](../api/reference.md)。

---

## 常见 API 操作

### 创建联系人

**请求：**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**必填字段：** 创建联系人时始终需要 `phoneNumber`（带国家/地区代码）。仅有电子邮件地址是不够的——没有有效电话号码的请求将被拒绝。电子邮件是可选的。

**响应：**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

保存 `data.contactId` ——您在调用“将联系人添加到列表”时需要用到它。

::: note
**注意：** 如果具有相同电话号码的联系人已存在，API **不会**创建或返回该联系人，而是返回 `{ "success": false, "error_code": 409 }`。请先使用 `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...` 查找现有联系人。
:::


---

### 将联系人添加到列表

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

在应用程序的 **联系人 → 列表** 下，通过列表行菜单（**复制列表 ID**）查找列表的 ID。

---

### 更新联系人

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

仅会更改您包含的字段。这也是导入后批量加载自定义字段值的方法——请参阅 [自定义字段、潜在客户资料和备注](../get-started/custom-contact-fields.md#bulk-loading-custom-fields)。详细信息请参阅 [联系人 API](../api/contacts.md)。

---

### 发送消息（自定义渠道）

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `customData.fromId` | 是 | 您平台上的联系人 ID |
| `customData.customChannel` | 是 | 您的自定义渠道名称 |
| `customData.body` | 是 | 要发送的消息文本 |
| `customData.campaignId` | 否 | 将消息路由到特定营销活动 |
| `customData.firstName` | 否 | 联系人名字（创建新联系人时使用） |
| `customData.lastName` | 否 | 联系人姓氏 |
| `customData.email` | 否 | 联系人电子邮件地址 |

::: note
**注意：** 此端点用于自定义渠道消息传递。对于 WhatsApp、短信、Instagram 和 Messenger，消息通过广播、营销活动和 AI 代理发送。
:::


---

### 接收传入消息（自定义渠道）

接收来自外部系统的消息作为自定义渠道。这就是像 GoHighLevel 这样的集成将消息发送到 <span data-t="appName">Your AI Connector</span> 的方式。有关完整详细信息，请参阅 [自定义渠道](../messaging-channels/custom-channels.md)。

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `customData.messageSid` | 是 | 此消息的唯一 ID（防止重复）。您也可以使用 `customData.id`。 |
| `customData.fromId` | 是 | 您外部系统中的发送者 ID。 |
| `customData.toId` | 是 | 您的业务标识符。 |
| `customData.body` | 是 | 消息文本。 |
| `customData.channel` | 否 | 来源标签（例如 `"email"`、`"livechat"`、`"custom"`）。 |
| `customData.status` | 否 | 消息状态。默认为 `"received"`。 |
| `messageType` | 否 | 文本消息使用 `"text"`，表情符号反应使用 `"reaction"`。 |

---

## 可用操作概览

| 操作 | 方法 | 地址 | 说明 |
|---|---|---|---|
| 创建联系人 | `POST` | `/contacts` | 向您的账户添加新联系人 |
| 获取联系人详情 | `GET` | `/contacts?phoneNumber=X` 或 `/contacts?email=X` | 通过电话号码或电子邮件查找联系人 |
| 更新联系人 | `PUT` | `/contacts/{contactId}` | 更新现有联系人上的任何字段 |
| 将联系人添加到列表 | `POST` | `/contacts/lists` | 将现有联系人添加到特定列表 |
| 发送消息 | `POST` | `/send_custom_channel_message` | 通过自定义渠道发送消息 |
| 接收消息 | `POST` | `/incoming_custom_channel_message` | 接收来自外部系统的消息 |

---

## 速率限制

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## 最佳实践

- **安全存储您的 API 密钥** — 使用密码管理器或服务器端配置，切勿在浏览器访问者可以读取的客户端代码中使用。
- **始终包含国家/地区代码**（电话号码中 `+1` 代表美国，`+44` 代表英国，`+31` 代表荷兰）。
- **妥善处理错误** — 检查状态码并阅读返回的任何错误消息。
- **处理重复项** — 重复的电话号码会返回 `{ "success": false, "error_code": 409 }` 而不是新联系人。如果您需要处理该联系人，请先查找它。
- **在进行批量操作之前**，先使用小数据集进行测试。

---

## 错误响应

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## 后续步骤

- [Webhooks](webhooks.md) — 从应用程序接收实时通知（与您的 API 密钥分开的部分）。
- [连接 AI 助手 (MCP)](connect-ai-clients.md) — 使用相同的 API 密钥让 Claude 管理您的账户。
- [Facebook 潜在客户表单](facebook-lead-forms.md) — 将 API 与自动化平台结合使用以获取潜在客户。
- [GoHighLevel 集成](ghl-integration.md) — 一个完整的双向 API 集成示例。