消息与对话 #

Messages API 让您可以向任何联系人发送消息、读取对话、更正或删除已发送的消息、对消息做出反应、拉取完整的聊天会话线程、导出记录，以及将聊天标记为已读或未读——所有这些操作都无需打开收件箱。

本页面上的所有路径均相对于基础 URL https://api.youraiconnector.com/v1。每个请求都需要您的 API 密钥——请参阅身份验证以获取发送密钥的完整方式列表。以下示例使用了 X-API-Key 标头，其中一个 cURL 示例也展示了 ?apiKey= 查询形式。

投递工作原理： 发送消息不会等待其送达。API 会接收您的消息，立即返回一个消息 ID，然后在后台通过联系人的渠道（WhatsApp、短信、Instagram 等）进行投递。要跟踪消息是否实际送达或已读，请通过网络钩子 (Webhooks) 监听状态更新——请勿使用轮询。发送响应仅确认消息已被接收。

发送消息 #

有两种发送方式。选择最适合您识别联系人方式的一种：

• 按联系人 ID 发送 — 您已经知道联系人的 ID（例如，您通过 API 创建了该联系人或从 Webhook 获取了该 ID）。使用 POST /contacts/{contactId}/send-message。
• 按联系人身份发送 — 您知道联系人的电话号码、Instagram ID 等，但不知道其内部 ID。使用 POST /contacts/send 并让平台找到正确的联系人。

两者都以相同的方式将消息加入队列，并根据联系人所在的渠道进行投递。您无需选择传输方式——平台会自动将 WhatsApp 联系人的消息通过 WhatsApp 发送，将短信联系人的消息通过短信发送，依此类推。

两者也都只能查找已存在的联系人。这两个调用都不会创建联系人：如果 ID 或身份信息没有匹配项，则会返回 404，它不会变成新的联系人。因此，如果您是第一次给某人发消息，请先使用 POST /contacts 创建联系人，或者在 WhatsApp Web 上使用下方的 直接发送到 WhatsApp Web 号码，它会在同一次调用中创建联系人。

按联系人 ID 发送 #

POST /contacts/{contactId}/send-message

在 LinkedIn 上，即使对方正在 LinkedIn 端处理该对话，您通过这种方式或从收件箱发送的消息仍会送达。AI 自身的回复及其后续跟进消息会在该对话中被拦截。被拦截的回复会从聊天中移除，而不是显示为发送失败，因为实际上并未发送任何内容，也不会消耗额度。AI 在将对话转交给人工之前的最后一条回复仍会正常送达。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi! Your appointment is confirmed for tomorrow at 10:00.",
    }),
  }
);
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

响应 (200 OK)：

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

按联系人身份发送 #

POST /contacts/send

当您没有联系人的内部 ID 时，请使用此方法。提供消息 body 以及 contact_id，或者提供 channel 以及与该渠道匹配的身份字段。

哪些渠道可以通过身份信息解析。 14 个渠道中只有 6 个接受身份字段而非 contact_id：whatsapp, whatsapp_web 和 sms 通过 phone_number 查找，instagram 通过 instagram_id 查找，messenger 通过 messenger_id 查找，telegram 通过 telegram_user_id 查找。其余 8 个 — instagram_private, chat-widget, custom, email, line, imessage, linkedin 和 viber — 没有可供查找的公共身份，因此在这些渠道上发送消息需要 contact_id；仅传递 channel 会返回 400，提示您需要 contact_id。

cURL（使用 ?apiKey= 查询表单）

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

响应 (201 Created)：

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

消息可能被拒绝的原因： 开启了“请勿打扰”或隐私模式的联系人无法接收外发消息 — 请求将失败并返回 422。如果没有联系人匹配您提供的 ID 或身份，您将收到 404。

在 WhatsApp Web 上发送：变体与突发保护 #

当联系人使用 WhatsApp Web 时，以下两点适用于 body。

Spintax 大括号会在发送时展开。 body 的 {Hi|Hello|Hey} there, quick question 会作为三种问候语中的一种发出，并在发送时进行选择——大括号内容永远不会到达联系人处。使用此功能可以为每个联系人提供来自同一集成代码的不同开场白。不带大括号的文本将按原样发送。

完全相同的开场白突发发送将被拒绝。 如果一个 WhatsApp Web 号码在一小时内向从未给您写过信的联系人发送了十条近乎相同的开场白，后续消息将无法送达：发送请求会像往常一样被接受（您仍会收到 messageId），但消息随后会显示为 status: "failed" 和 error_code: "opener_burst"，并附带客户可读的原因。重试相同的文本无济于事——请更改文本、等待一小时后再发送。现有对话内的回复不受影响。相关原因请参阅 Identical openers get numbers restricted。

直接发送到 WhatsApp Web 号码 #

POST /whatsapp-web/send

无需先查找联系人，即可直接发送消息到 WhatsApp Web 上的电话号码。如果该号码还不是联系人，则会在同一次调用中创建联系人，并默认将 AI 设置为关闭状态，这样消息看起来就像是您手动发送的，后续也不会有助手接管对话。如果联系人已存在，则直接使用该联系人。

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

调用成功时返回 202：

{ "success": true, "queued": true, "contactId": "abc123" }

202 表示已接受，但尚未送达。在活跃时间之外，发送请求会被挂起并在下一个允许的时间段发出，除非您传递了 ignoreActiveHours 参数。请使用此处获得的 contactId，通过 列出联系人的消息 来读取消息本身的状态。

当发送失败时：

如果针对同一联系人的挂起发送任务仍在等待中，再次调用时会返回 409，因此不会在同一个人身上堆积发送队列。

在对话中记录一条备注 #

POST /contacts/notes

向联系人的对话中添加一行内容，且不会发送给对方。此功能适用于需要让你的团队和 AI 了解，但联系人无需知晓的背景信息：例如语音助手刚完成的通话摘要、来自 CRM 的备注，或同事留下的记录。它适用于所有渠道（WhatsApp、SMS、Instagram、Messenger、Telegram、聊天小部件、自定义渠道等）。

备注的处理方式：

• 它会以黄色 备注 卡片的形式显示在收件箱的聊天记录中，并附带发送者的姓名（如果指定了的话）。
• AI 会将其作为对话历史的一部分进行读取，并标记为内部备注，因此 AI 的下一次回复会将其纳入考量。
• 它绝不会发送给联系人，不消耗消息额度，也不会触发任何操作：没有 AI 回复、没有自动化流程、没有 Webhook、没有通知，也不会产生未读标记。它不会暂停 AI，也不计作你团队的回复。

查找联系人的方式与 按联系人身份发送 相同：使用其 ID，或使用 channel 加上匹配的标识符。备注只能发送给已存在的联系人；若未匹配到任何内容，则会返回 404。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

响应 (201，或当 external_id 已被记录时返回 200 和 duplicate: true)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

备注会出现在 列出联系人的消息 中，并带有 type: "note"。

使用 AI 生成回复草稿 #

POST /contacts/{contactId}/draft-reply

要求处理对话的 AI 智能体撰写下一条回复，并将文本返回给您。不会发送任何内容。 这与收件箱中的 生成回复 按钮所撰写的草稿相同：智能体将使用其设置、知识库以及目前的对话内容，并以联系人的语言进行回答。使用此功能可以在 AI 和联系人之间加入人工（或您自己的应用程序）：获取草稿，显示以供审批，然后通过 按联系人 ID 发送 进行发送（无论是否修改）。

• 草稿由分配给该联系人的智能体撰写。如果联系人尚未分配智能体，则由负责处理其下一条消息的智能体撰写。
• 在撰写草稿时，智能体不会运行任何工具或函数，因此不会执行预订、打标签、转交或其他操作。
• 对话中不会存储任何内容，联系人也看不到任何内容。
• 草稿的费用与该智能体在此对话中回复一条 AI 消息的积分相同；如果您连接了自己的 AI 密钥，则不收取费用。
• 对话中至少需要有一条消息。

所有正文字段均为可选；空正文（或无正文）将生成下一条回复的草稿。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

响应 (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

400 表示对话中尚无消息、您的积分已用尽，或者联系人没有可供撰写草稿的智能体或营销活动（error 会说明具体原因）。404 表示联系人不存在，或者团队成员的密钥仅限于查看其无法访问的联系人。该密钥或团队成员需要拥有编辑消息的权限。

通过 MCP 使用 AI 客户端？ 相同的操作也可作为 generate_reply_draft 工具使用。

列出联系人的消息 #

GET /contacts/{contactId}/messages

返回联系人的消息，按最新消息在前排序，并支持基于游标的分页。

关于过滤和分页的说明： filter 和 direction 过滤器是在读取每一页后应用的，因此过滤后的页面包含的项目数可能少于 limit。但 next_cursor 仍会在整个对话中推进，因此请持续翻页直到 next_cursor 为 null。

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

消息字段 #

下载消息附件 #

POST /chat-exports/media/download-url

为您提供一条指向消息所附文件（图片、语音留言、视频或文档）的最新下载链接。该链接有效期为 1 小时。当您需要将附件保存到其他地方（例如，归档联系人发送的简历或语音留言），或者当消息上的 media_url 或 新消息 Webhook 无法打开时，请使用此功能。

要查找带有附件的消息，请使用 filter=media 列出联系人的消息。每条消息的 id 和联系人的 ID 共同构成了 messagePath。

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

响应 (200 OK)：

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

通过 MCP 使用 AI 客户端？ 相同的操作可作为 get_chat_media_download_url 工具使用。

列出聊天会话 #

聊天会话是一个与联系人的对话窗口。当没有打开的会话时，它会在收到第一条消息时自动开启，并在联系人最后一条消息发出 48 小时后自动关闭（每收到一条新消息，关闭时间都会向后顺延 48 小时）。AI 结束聊天并不会关闭会话；它只会触发“聊天已结束” (Chat Concluded) 的 Webhook。会话的作用是将漫长的历史记录分页为可读的对话，而不是将其显示为一个无休止的列表。

所有联系人的近期会话 #

GET /chat-sessions/recent

返回账户中所有联系人在过去 X 小时内开始的会话，按最新时间排序。

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

响应 (200 OK)：

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

单个联系人的所有会话 #

GET /chat-sessions/{contactId}

返回单个联系人的所有聊天会话。与上述相同的 status、limit 和 includeMessages 参数——hours 在此处不适用。

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

两个端点之间的会话 ID 字段名称不同。 近期会话列表将其称为 session_id（它还携带联系人的详细信息，因为会话来自许多联系人）；按联系人列表将其称为 id。在获取下方完整线程时，无论哪个值，您都可以将其作为 {sessionId} 传入。

当 includeMessages=true 时，每个会话都会获得一个 messages 数组，其条目包含 id、body、direction、timestamp、type、channel 和 status。

获取聊天会话线程 #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

聊天会话将联系人的消息归入一个对话窗口。此端点返回单个会话的完整线索（按时间从旧到新排序），以及会话的元数据。您可以通过聊天会话端点找到联系人的会话 ID。

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

session 对象报告了 status（激活时为 ChatSessionOpened，结束后为 ChatSessionClosed）、start_date_time、end_date_time 以及人类可读的 tag。messages 数组使用与列表端点相同的 消息字段。

编辑、删除和对消息做出反应 #

这些端点会在消息发送后对其进行更改。其中两个端点不仅会触达您自己的副本，还会触达联系人的渠道，因此在连接它们之前请阅读章节介绍——具体可行性完全取决于对话所在的渠道。

每个渠道允许的操作

在所有其他渠道（WhatsApp Business API、SMS、Instagram、Messenger、电子邮件、LINE、自定义渠道）上，删除操作仍会从您的收件箱中移除消息，但联系人会保留其副本，且完全无法进行编辑或反应。

编辑消息 #

POST /contacts/{contactId}/messages/{messageId}/edit

重写您已发送的消息，同时在联系人的设备和您的副本中进行更新。

与删除不同，当渠道拒绝操作时，此操作会明确报错：您会收到一个 409，并且您的副本会保持联系人所见的状态，因为显示一条他们从未收到的编辑内容会导致双方信息不同步。edit_reason 字段会告知您原因——渠道的编辑窗口已关闭、渠道已断开连接、消息包含渠道无法编辑的附件（media_not_editable：在 WhatsApp Web 上仅能编辑文本消息，无法编辑照片、视频或文件下方的文本），或者出现了其他错误。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

如果渠道不接受该编辑，您将收到一个 409，且没有任何内容被更改：

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

已删除的消息、完全不支持编辑的渠道以及对于其渠道而言过旧的消息都会返回 400 —— 请求从未到达该渠道。

删除单条消息 #

DELETE /contacts/{contactId}/messages/{messageId}

从您的对话中移除消息，并在渠道允许的情况下，同时撤回联系人的副本。无需请求正文。

当消息存在时，此操作总是返回 200，即使无法撤回联系人的副本——因为您的副本确实已经删除，所以报错会产生误导。请阅读响应中的三个字段，以告知用户实际发生了什么：

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

已删除的消息不会从对话历史记录中移除。它们会保留在 GET /contacts/{contactId}/messages 中，并带有 is_deleted: true 以及空的 body 和 media_url。

一次性删除多条消息 #

POST /contacts/{contactId}/messages/bulk-delete

仅从您的一侧清除一批消息。消息正文和附件会被清空，但联系人设备上的内容不会被撤回——若要同时撤回消息，请使用上述单条消息端点逐一删除。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "deleted": 2
}

对消息做出反应 #

POST /contacts/{contactId}/messages/{messageId}/react

在消息上添加您自己的表情符号反应，或通过发送空字符串来撤回反应。联系人自己的反应永远不会受到影响。

与编辑操作一样，如果联系人从未收到该消息，此操作会失败而不是显示反应，并且失败信息会告知您是否值得重试：

• 422 — 此对话永远无法送达：频道不支持反应、消息没有频道端 ID，或者表情符号超出了该频道允许的范围。
• 409 — 频道暂时无法访问。重试可能会成功。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

reactions 数组是当前消息上所有反应的完整集合，包括您和联系人的反应。在 409 或 422 情况下，它会原样返回，因此直接根据该数组进行渲染的客户端永远不会显示未送达的反应。

评价或标记消息 #

PATCH /contacts/{contactId}/messages/{messageId}

对消息进行点赞或点踩评价，和/或将其标记为重要。这仅是您一侧的记录工作——不会向联系人发送任何内容。

至少发送其中一个，否则会收到 400。只会写入你发送的内容，因此收藏消息永远不会清除其评分，反之亦然——响应只会回显你发送的字段。

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

将消息标记为已读 #

您可以清除特定消息或整个对话的未读状态。

将特定消息标记为已读 #

POST /contacts/{contactId}/messages/mark-read

传入要标记为已读的消息 ID。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

将整个聊天标记为已读 #

POST /contacts/{contactId}/mark-read

清除收件箱中联系人整个对话的未读标记。无需请求正文。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123"
}

将整个聊天标记为未读 #

POST /contacts/{contactId}/mark-unread

将未读标记重新放回对话上——当团队成员打开了聊天但又将其交回时非常有用。无需请求正文。

这是一个仅限收件箱的标记：它不会更改对话的最后阅读时间，因此在支持阅读回执的渠道上，不会向联系人发送阅读回执。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：

{
  "success": true,
  "contact_id": "contact123"
}

导出对话 #

导出功能为你提供整个对话的可读副本，而无需逐页翻阅消息。每个导出端点都接受一个 filter，可选值为 all（默认）、text、media 或 tool_use，与消息列表上的过滤器相匹配。

导出单个联系人的聊天记录 #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

响应包含 format=json (200 OK)：

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

使用 format=txt（默认值）时，data 则是生成的副本文件的下载链接：

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

下载链接有效期较短。 获取链接后请立即下载文件，不要存储链接——当再次需要副本时，请重新请求导出。

导出所有近期对话 #

GET /chat-exports/recent

通过单次调用，导出过去 X 小时内所有活跃联系人的对话。

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

使用 format=txt 时，响应内容即为文本文件本身，以文件下载形式发送，而非 JSON 格式。

此单次调用会拉取每个匹配联系人的完整历史记录，因此在繁忙账户上请保持 hours 和 limit 的数值适中。

通过电子邮件向联系人发送对话记录 #

POST /chat-exports/{contactId}/email

通过电子邮件向联系人发送其对话记录——即由您自己的系统驱动的“将此聊天记录发送给我”流程。

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

响应 (200 OK)：

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCount 会告知您为了保持邮件长度合理而省略了多少条最早的消息。200 表示对话记录已生成并排队等待发送，并不代表邮件已送达收件箱。

为单个联系人暂停或恢复 AI #

PUT /contacts/{contactId}

将 is_bot_active 设置为 false 可停止 AI 回复某个联系人，将其改回 true 即可交还对话控制权。当人工介入对话时，这是您需要的接管开关：即使机器人处于暂停状态，您通过 API 发送的消息仍会正常送达。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

响应

{
  "success": true,
  "contact_id": "contact123"
}

在回复时暂停

如果人工通过发送回复来接管对话，您可以在同一个请求中暂停机器人，而无需进行第二次调用。POST /contacts/{contactId}/send-message 接受以下可选标志：

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

当应用暂停时，响应中会包含 "botPaused": true。

使用 POST /contacts/bulk-flag 将联系人标记为私密也会暂停该联系人的机器人服务。有关完整字段列表，请参阅 联系人。

构建您自己的收件箱 #

收件箱所需的一切功能都在本页面及 联系人 中：

如需实时更新，请使用 Webhooks 订阅 New Message、Replies、Human Alerted 和 Chat Concluded 事件，而不是通过定时轮询此 API。

消息 API 错误 #

消息端点返回标准的错误信封：

{
  "success": false,
  "error": "Contact not found"
}

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

后续步骤 #

• Webhooks — 获取推送的发送状态更新，无需轮询。
• Contacts — 创建并查找您联系的对象。
• Appointments — 为您的联系人预约并管理日程。