DEVELOPER DOCUMENTATION

把 Agent 的指令，
连接到真实微信。

一套 API，连接设备、下发任务并获取结果。
xiyebot 执行手机操作，你的系统负责业务逻辑。

5 个核心接口13 种任务类型资料版本 2026.09.09.1

产品与接入方式

xiyebot 通过安卓真机上的无障碍服务操作官方微信。一个授权码绑定一台手机，对应一个微信号。任务在手机上串行执行；执行结果可通过查询接口获取，或由回调送达你的系统。

你的 AI / 业务系统→xiyebot→安卓真机→执行结果

选择你的接入方式

场景	回调配置	回复逻辑
自建业务系统直连	自行配置回调地址	在你的系统中处理入站消息
获客 AgentOS	由平台引擎配置，不要覆盖	由平台 AI 员工处理

本页是根据官网公开资料整理的接入文档。xiyebot 是执行层；对话内容与决策由你的 AI Agent 或业务系统产生。

快速开始

准备安卓真机，安装 Xiyebot Agent，完成无障碍、输入法与后台运行设置。
使用授权码激活设备，保持手机亮屏、微信登录并在前台。
在服务端安全配置 ROBOT_ID，先查询设备是否在线。
给自己的微信发送测试消息，拿到 taskId 后查询最终状态。

完整手机安装步骤 ↗

Shell · 检查在线状态

curl "https://flowbot.efguc.com/wx/api/getRobotInfo?robotId=${ROBOT_ID}"

Shell · 发送第一条消息

curl -X POST \
  "https://flowbot.efguc.com/wx/api/sendTask?robotId=${ROBOT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "taskList": [{
      "type": 10001,
      "searchText": "我的微信名",
      "message": "这是一条测试消息。",
      "idempotencyKey": "first-message-001"
    }]
  }'

将“我的微信名”替换为微信实际显示的联系人名字，备注名优先。示例使用 Shell 环境变量；授权码应由服务端保存，避免写入前端页面。

鉴权与响应

BASEhttps://flowbot.efguc.com/wx

所有 /api/* 核心接口使用 robotId（授权码）鉴权。可放在 URL 查询参数中；POST 也可通过 JSON body 的 robotId 字段传入。授权码格式为 xyb 加 32 位十六进制字符。

JSON · 统一响应信封

{
  "code": 200,
  "message": "...",
  "data": {}
}

授权码不存在或被禁用时返回 401。参数错误返回 400；以响应中的具体 message 为排查依据。

查询设备状态

GET / POST/api/getRobotInfo

根据手机心跳判断在线状态。建议在发送有时效的任务之前先检查。

参数	必填	说明
`robotId`	是	设备授权码

JSON · 响应字段节选

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "robotId": "xyb...",
    "online": true,
    "status": "online"
  }
}

online=false 表示手机 Agent 没有及时上报心跳。离线时任务仍可能入库排队，超过任务超时时间后结束为 timeout。

下发任务

POST/api/sendTask

在 taskList 中提交任务。任务与授权码绑定的手机关联，并在该手机上串行执行。

字段	要求	说明
`taskList[].type`	必填	任务类型号，见下方任务表
`searchText`	依类型	联系人或群显示名，必须与微信显示一致
`targetType`	可选	`friend` 默认；群任务使用 `group`
`message`	依类型	文字正文或素材 URL，随任务类型变化
`idempotencyKey`	建议	稳定的业务消息 ID，重试时保持不变
`timeoutSeconds`	可选	默认 90 秒
`priority`	可选	默认 5，数值越小越先执行

JSON · 请求示例

{
  "taskList": [{
    "type": 10001,
    "searchText": "客户",
    "message": "您好，您的订单已发货。",
    "idempotencyKey": "order-1001-shipped"
  }]
}

JSON · 入库响应

{
  "code": 200,
  "message": "指令发送成功",
  "data": {
    "taskList": [{
      "taskId": "task_xxx",
      "status": "pending",
      "searchText": "客户",
      "type": 10001
    }]
  }
}

返回 200 仅表示任务已入库，不能当作微信已发送成功。请保存 taskId，用 getTaskStatus 查询终态。

查询任务结果

GET / POST/api/getTaskStatus

参数	必填	说明
`robotId`	是	创建该任务的授权码
`taskId`	是	sendTask 返回的任务 ID

pending→dispatched→running→终态

终态包括 succeeded、failed、cancelled、timeout。finished=true 表示已结束，并不一定成功。

JSON · 成功响应字段节选

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "taskId": "task_xxx",
    "status": "succeeded",
    "finished": true,
    "success": true,
    "result": { "sent": true },
    "errorCode": null
  }
}

建议入库后先等 10 秒，再每 5 秒查询一次，最多查询至 timeoutSeconds + 30 秒。只能查询本授权码通过 sendTask 创建的任务，其他任务返回 404。

好友资料的结果位于 result.profile；通讯录同步结果位于 result.contacts[]。

读取聊天记录

GET / POST/api/getChatHisList

只读查询 xiyebot 通过无障碍看到的消息，用于查看近期消息和排障。

参数	必填	说明
`robotId`	是	设备授权码
`searchText`	否	会话名；不传则读取跨会话最近消息
`limit`	否	1–100，默认 20

结果在 data.list，按时间正序排列。role=user 表示客户消息，role=assistant 表示本微信号发出的消息。消息类型包含 text、image、voice、file(文件抓取,data.fileUrl 为可下载地址,业务端拉取解析)。

这不是微信数据库导出。手机不在前台时的消息、撤回或表情包等可能缺失；图片与语音也可能表现为占位内容或转写文字。

配置回调地址

POST/api/updateCallBackUrl

自建系统直连时，设置接收设备状态、任务结果和入站消息的地址。每个 robotId 仅保存一个回调地址。

JSON · 请求体

{
  "callBackUrl": "https://your-backend.example.com/xiyebot/callback"
}

请求同时需要携带 robotId 鉴权。地址配置完成后会收到一次 mode=init 回调。

获客 AgentOS 的回调由平台引擎管理，二次开发不要调用此接口覆盖地址，否则平台 AI 员工将无法收到消息。该场景需要任务结果时，使用 getTaskStatus。

13 种任务类型

所有类型通过 sendTask 下发。以下列出关键字段；字段别名、素材限制及完整示例可查阅官方原始指南。

type	能力	关键字段 / 边界
`10001`	微信文字消息	searchText、message、targetType
`10002`	微信图片消息	searchText、message（图片 URL）、fileName
`10006`	微信文件 / 视频	searchText、fileUrl、fileName、mimeType（视频传 video/mp4,作为可播放视频发送;推视频用本类型,勿用发文本发 URL）
`10010`	小程序链接	searchText、message；发送可点击链接文字，不是卡片
`10020`	朋友圈图文 / 视频	imageUrls（最多 9 张）\| videoUrl（文案+视频,与图片互斥）、caption、dryRun
`10021`	视频号视频	videoUrl、caption、fileName
`10022`	抖音视频发布	videoUrl、caption、dryRun；仅发布
`10023`	小红书视频发布	videoUrl、title、caption、dryRun；仅发布
`20004`	修改好友备注	searchText、remark
`20005`	添加好友	phone / searchText、message；只确认申请发出
`20006`	读取好友资料	searchText；通过任务结果读取 profile
`20007`	同步通讯录	contactTypes、maxItems、maxScrolls；执行较慢
`50009`	群 @ 成员	searchText、targetType=group、atName、message

朋友圈发布示例

JSON · 多图预演

{
  "taskList": [{
    "type": 10020,
    "imageUrls": [
      "https://cdn.example.com/1.jpg",
      "https://cdn.example.com/2.jpg"
    ],
    "caption": "本周新品，欢迎了解。",
    "dryRun": true
  }]
}

示例素材地址需替换为真实可下载的地址。朋友圈 dryRun=true 会停在发表前，便于人工确认版式。多图使用 imageUrls 数组；单个 imageUrl 仅表示一张图。

回调事件

回调通过 POST 投递到设备配置的地址。基本结构包括 robotId、mode、searchText 和 data 数组。

mode	触发时机	用途
`init / online`	注册、上线或设备状态通知	更新设备状态
`receipt`	任务入库	记录任务已接收
`callBack`	任务到达终态	更新成功、失败及错误码
`logs`	观察到客户入站消息	交给你的对话引擎处理

接收端返回 2xx 表示接收成功。根据官网说明，投递失败会按指数退避重试三次。平台接入场景由平台引擎消费回调，自建系统才自行处理。

错误码与排障

错误 / 状态	处理方式
`401 robotId无效`	检查授权码格式、是否存在或被禁用
`400 参数错误`	根据 message 补齐具体字段，不要盲目重试
`404 任务不存在`	检查 taskId 与 robotId 是否配对
`timeout`	检查手机电量、网络与 Agent 是否持续运行
`SEARCH_VISUAL_NOT_FOUND` `FIRST_RESULT_NOT_CONVERSATION`	核对微信中的联系人或群名，备注名优先
`CHAT_MESSAGE_CONTENT_MISMATCH`	检查弱网或微信弹窗，再使用原 idempotencyKey 重试一次
`IMAGE_URL_INVALID` `VIDEO_TOO_LARGE`	检查公网素材地址、访问条件与文件大小
`AUTH_CODE_ALREADY_BOUND`	在管理后台解绑旧设备，再激活新设备

运行条件与能力边界

Android 8.0 及以上真机，推荐 Android 11+；不支持 iPhone、模拟器或无安卓兼容层的鸿蒙 NEXT。
保持亮屏、微信已登录且在前台，允许 Agent 持续后台运行。
任务按人操作手机的节奏串行执行。API 调用不限次是计费方式，不代表无限执行吞吐。
抖音、小红书目前仅开放视频发布；评论、私信与数据回读等仍在开发中。
小程序原生卡片与微信原生语音气泡未开放；企业微信属于其他通道。
无障碍操作仍受微信规则与界面变化影响，不能视为免除平台风控。

把 Agent 的指令，连接到真实微信。