API 访问

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

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

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

生成您的 API 密钥

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

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

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

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

重要提示： 您的 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 参考。

常见 API 操作

创建联系人

请求：

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（带国家/地区代码）。仅有电子邮件地址是不够的——没有有效电话号码的请求将被拒绝。电子邮件是可选的。

响应：

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

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

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

将联系人添加到列表

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

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

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

更新联系人

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

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

仅会更改您包含的字段。这也是导入后批量加载自定义字段值的方法——请参阅自定义字段、潜在客户资料和备注。详细信息请参阅联系人 API。

发送消息（自定义渠道）

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`	否	联系人电子邮件地址

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

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

接收来自外部系统的消息作为自定义渠道。这就是像 GoHighLevel 这样的集成将消息发送到 Your AI Connector 的方式。有关完整详细信息，请参阅自定义渠道。

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 or email hi@youraiconnector.com for guidance.

最佳实践

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

错误响应

{
  "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 hi@youraiconnector.com if this persists

后续步骤

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

API 访问 #

生成您的 API 密钥 #

基础 URL #

身份验证 #

常见 API 操作 #

创建联系人 #

将联系人添加到列表 #

更新联系人 #

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

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

可用操作概览 #

速率限制 #

最佳实践 #

错误响应 #

后续步骤 #

API 访问

生成您的 API 密钥

基础 URL

身份验证

常见 API 操作

创建联系人

将联系人添加到列表

更新联系人

发送消息（自定义渠道）

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

可用操作概览

速率限制

最佳实践

错误响应

后续步骤