向智能体发送消息

概述

用于把一条“用户消息（query）”发送给 3Chat 智能体，由智能体生成回复；支持同步等待结果或异步回调两种处理方式，并支持携带附件与指定渠道类型。适用于有开发能力的客户，使用非 3Chat 原生支持的消息渠道。

关键参数详解：

dialogId - 会话 id

可选参数。

如果设置，会查找当前系统是否存在对应会话。

如果会话存在并且userId 参数已设置，则校验对应会话的联系人和userId是否匹配，若不匹配，则返回错误；

如果会话不存在，则返回错误；

userId - 联系人 id

可选参数。

如果参数已设置，会查找当前系统是否存在对应联系人。

如果dialogId 参数已设置，则校验对应会话的联系人和userId是否匹配，若不匹配，则返回错误；

如果联系人存在并且dialogId 参数未设置，则复用当前联系人关联的会话；

如果联系人不存在并且dialogId 参数未设置，则新建联系人和新的会话；

如果参数未设置。

如果dialogId 参数已设置，则使用该会话关联的联系人；

如果dialogId 参数未设置，则新建匿名联系人和新的会话；

async - 处理模式

同步模式（默认）：async = false 或不传 async，请求会阻塞等待智能体处理完成后返回结果（适合前端直出、低并发调用等）。

异步模式：指定 async = true，请求会马上返回，等智能体处理结束后

(1) 若在请求时制定了 sendWebhook：调用此 webhook 推送回复内容

(2) 若未指定 sendWebhook：系统会根据当前会话 channelType 用默认方式把回复发回原渠道

sendWebhook - 异步回调地址

仅在 async=true 时生效

Webhook 回调协议如下：

Method：POST
Body：
{
    "id": "消息 id",
    "content": "agent 回复消息内容",
    "createdAt": "消息时间",
    "agentLogs": "agent 活动日志",  // 具体日志内容可参考接口的响应描述
    "attachments": {
        "key": "",
        "name": "附件名称",
        "url": "附件链接",
        "contentType": "附件类型"
    }
}

Webhook 接收端最佳实践建议

返回 200 表示接收成功（避免平台重试）。

建议你们的 webhook 接口具备：

幂等处理（按 id 去重）

超时控制（例如 3~5s 内返回）

记录请求原文用于排障（特别是 agentLogs）

channelType - 指定会话所属代理来源

当你希望“明确指定会话所属渠道和代理来源”时传入；不传则使用默认值 OPENAPI。此信息会在 3Chat 后台所有展示消息渠道信息的交互内展示指定的渠道信息。

proxy：渠道代理类型，决定 type 的枚举集合

CHATLY

MANYCHAT

type：具体渠道类型枚举，随 proxy 变化

当指定 proxy = CHATLY 时，type 支持：

WECHAT：微信

QYWECHAT：企业微信

WECHAT_PUBLIC：微信公众号/服务号

WECHAT_CUSTOMER_SERVICE：微信客服

FEISHU：飞书

MICRO_APP：小程序

DINGDING：钉钉

RED_BOOK：小红书

当指定 proxy = MANYCHAT 时，type 支持：

TIKTOK

MESSENGER

INSTAGRAM

SMS

files -（附件）说明

files 为附件数组，每个元素描述一个附件

type 推荐使用标准 MIME Type（如 image/png, application/pdf 等）

url 为可访问的文件地址（确保服务端可拉取/可鉴权访问策略一致）

size 为文件大小（单位建议与实现一致，通常为 bytes）

options - 可选参数

options.user：

该字段内的内容只针对新建联系人有效，不会更新已有联系人信息。

请求参数

Header 参数

Body 参数application/json

示例

{
    "query": "我想申请订单退款，订单号是 202602050001，可以帮我看下流程吗？",
    "dialogId": "dlg_20260205103045_abc123",
    "userId": "user_987654321",
    "channelType": {
        "type": "WECHAT",
        "proxy": "CHATLY"
    },
    "async": false,
    "sendWebhook": "https://api.example.com/webhook/agent-callback",
    "files": [
        {
            "name": "order_screenshot.png",
            "type": "image/png",
            "url": "https://cdn.example.com/uploads/order_screenshot.png",
            "size": 245
        },
        {
            "name": "order_screenshot.png",
            "type": "image/png",
            "url": "https://cdn.example.com/uploads/order_screenshot.png",
            "size": 245
        }
    ]
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Body

示例

{
  "code": 200,
  "message": "success",
  "data": {
    "dialogId": "dlg_20260205103045_abc123",
    "agentLogs": [
      {
        "type": "knowledge_hit",
        "name": "RefundPolicyAgent",
        "message": "命中退款流程相关知识库内容",
        "status": "success",
        "kb": [
          {
            "content": "用户在订单支付完成后7天内可申请退款，退款将原路返回，处理时间为3-5个工作日。",
            "chunk_id": "chunk_refund_001",
            "document_id": "doc_refund_policy_v1",
            "document_name": "退款政策说明",
            "enabled": true,
            "lang": "zh-CN",
            "score": 0.87,
            "source": "knowledge_base",
            "created_at": 1707100800
          }
        ],
        "entity": {
          "name": "refund_type",
          "values": [
            "订单退款"
          ]
        },
        "timestamp": 1707100845123
      }
    ],
    "messages": [
      {
        "type": "assistant",
        "contentType": "text",
        "text": "您好～如果您需要申请退款，只要在订单支付完成后的7天内提交申请即可。退款会原路返回，一般会在3-5个工作日内完成处理。如需我帮您发起退款，也可以直接告诉我订单号。",
        "url": "",
        "meta": {
          "width": 0,
          "height": 0,
          "size_kb": 0,
          "duration": 0,
          "format": "",
          "coverUrl": ""
        }
      }
    ]
  }
}

向智能体发送消息

概述#

关键参数详解：#

dialogId - 会话 id#

userId - 联系人 id#

async - 处理模式#

sendWebhook - 异步回调地址#

channelType - 指定会话所属代理来源#

proxy：渠道代理类型，决定 type 的枚举集合#

type：具体渠道类型枚举，随 proxy 变化#

files -（附件）说明#

options - 可选参数#

options.user：#