外观
如何选择接口
| 你的需求 | 推荐接口 | 是否同步等待回复 |
|---|---|---|
| 用户刚刚说了一句话 | POST /open/v1/message | 是 |
| 系统要主动欢迎、提醒或跟进一位用户 | POST /open/v1/outbound-message | 是 |
| 一次触达 2—100 位用户 | 创建批量任务 | 否，需要查询结果 |
决策建议
- 有真实的入站用户消息：使用被动消息接口，不要伪装成主动场景。
- 没有用户刚发来的消息，但业务事件需要触达：使用主动消息接口，并选择准确的
scenario。 - 同一活动需要处理多位用户：使用批量任务，避免客户端自行高并发循环。
- 只想接入企业微信、钉钉或飞书：优先使用办公平台快速接入，无需开发 API。
保持会话稳定
externalUserId 标识用户，conversationKey 区分该用户的不同会话空间。两者稳定，系统重启后也能继续原上下文。
用户发来消息时生成回复
- **用途：**用户刚发送文本或图片，分身同步生成回复。
- 准备：
messageId、稳定的externalUserId、消息内容；多会话时再提供conversationKey。 - **上下文：**会保留，相同用户和会话键会延续历史。
- **是否负责发送：**不会；接口返回
replyText，由你的系统发送给用户。 - **成功标准：**HTTP 请求成功且响应
code为0。
bash
curl "$LINGXIE_API_BASE_URL/open/v1/message" -H "Authorization: Bearer $LINGXIE_API_KEY" -H "Content-Type: application/json" -d '{"messageId":"msg_001","externalUserId":"user_001","messageType":"text","text":"你好"}'主动生成一条消息
- **用途：**欢迎、提醒、跟进或召回一位已有用户。
- **准备：**唯一
messageId、场景、用户标识；提醒场景还要提供可信事实。 - **上下文：**会读取相同用户和会话键的历史。
- **是否负责发送：**不会；返回生成内容或
skipped，由业务决定是否发送。 - **成功标准：**响应
code为0，并正确处理generated或skipped。
bash
curl "$LINGXIE_API_BASE_URL/open/v1/outbound-message" -H "Authorization: Bearer $LINGXIE_API_KEY" -H "Content-Type: application/json" -d '{"messageId":"out_001","scenario":"check_in","externalUserId":"user_001"}'批量生成消息
- **用途：**一次为 2—100 位用户创建主动消息任务。
- **准备：**唯一
batchRequestId、场景和收件人列表。 - **上下文：**每个收件人独立读取自己的用户和会话历史。
- **是否负责发送：**不会；任务明细返回每项生成或跳过结果。
- **成功标准：**任务进入终态，并逐项处理成功、跳过或明确失败。
bash
curl "$LINGXIE_API_BASE_URL/open/v1/outbound-message-batches" -H "Authorization: Bearer $LINGXIE_API_KEY" -H "Content-Type: application/json" -d '{"batchRequestId":"batch_001","scenario":"check_in","recipients":[{"itemId":"item_1","externalUserId":"user_1"},{"itemId":"item_2","externalUserId":"user_2"}]}'只在办公软件中聊天
- **用途：**直接在企业微信、钉钉或飞书中使用分身。
- **准备：**目标企业账号及创建机器人的权限。
- **上下文：**平台用户和会话会被稳定区分，系统重启后继续原上下文。
- **是否负责发送：**办公平台连接器会完成消息接收与回复，无需调用 API。
- **成功标准：**页面显示连接成功，私聊和群聊
@机器人均能收到回复。