跳到主要内容

使用 Dify 接收通知

机器人支持通过 Dify 方式将接收到的用户消息或事件回调至 Dify 服务。
该机制便于业务方快速集成大模型能力，实现智能回复、AI 助手等功能。

本文档介绍回调工作原理、触发条件及接入示例，帮助你快速完成机器人 Dify 的接入与处理。

工作流程​

整体流程旨在通过集成 Dify，实现机器人对话的上下文感知与智能响应。具体步骤如下：

  1. 消息转发至 Dify

    • 融云机器人根据配置的集成类型（如 dify_chat、dify_completion 等），将用户消息转发至 Dify 对应的 APP 模式；
    • 支持流式（Streaming）与非流式（Standard）两种响应模式。

  2. Dify 响应处理

    • Dify 接收到消息请求后，进行模型推理和响应生成；
    • 根据 Dify 配置，选择是否启用流式输出，返回完整文本或逐段流式数据。

  3. 响应接收与消息发送

    • 融云机器人接收 Dify 返回的结果后，按以下逻辑处理发送：
      • 流式模式：以流式消息形式实时推送至用户会话；
      • 非流式模式：拼接完整文本后作为普通消息发送；
    • 在首次消息交互时，存储下列信息以便维护上下文：
      • 用户 ID（消息发送者）；
      • 会话类型 ；
      • Target ID (目标 ID，即客户端 targetId，根据会话类型 channelType 的不同，可能为二人目标 ID、群聊 Id)；
      • Bot ID（机器人）；
      • Dify conversation_id（Dify 会话标识）；
    • 存储时效为 24 小时，确保后续对话具备上下文感知能力。

  4. 上下文关联与会话延续

    • 在后续对话中，融云机器人会自动将 Dify 会话 ID 传递至 Dify 后端；
    • 实现跨消息的上下文延续，支持多轮智能对话、状态记忆与流程联动。

回调事件类型说明​

回调事件类型及其触发条件请参考文档 回调事件类型列表。

⚠️ 不同事件类型对应的 data 字段结构可能不同，请根据具体类型进行解析和处理。

回调消息类型说明​

objectName 表示回调事件的消息类型。仅支持以下消息类型：

值说明
RC:TxtMsg文本消息

回调参数说明​

通用字段（适用于所有事件）​

参数路径类型说明
inputsObject允许传入 App 定义的各变量值
inputs.typeString事件类型
inputs.timestamplong事件触发时间（Unix 毫秒）
inputs.bot_userIdString机器人用户 ID
inputs.bot_nameString机器人名称
inputs.bot_profileUrlString机器人头像 URL
inputs.bot_typeString机器人类型
inputs.bot_metadata_{key}String机器人自定义元数据，采用 Map key 扁平化方式

message:private 类型​

参数路径类型说明
inputs.data_fromUserIdString来源用户 ID
inputs.data_toUserIdString接收方 ID，通常为机器人自身 ID。
inputs.data_objectNameString消息类型，例如文本消息 RC:TxtMsg、图片消息 RC:ImgMsg。
inputs.data_channelTypeString会话类型。PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、CUSTOMERSERVICE（客服会话）、NOTIFY（系统通知）、MC（应用公众服务）、MP（公众服务）、 ULTRAGROUP（超级群服务）。
inputs.data_msgTimestampNumber消息时间戳
inputs.data_msgUIDString消息唯一 ID
inputs.data_extraContentString附加消息内容

message:group_mentioned 类型​

参数路径类型说明
inputs.data_fromUserIdString来源用户 ID
inputs.data_toUserIdString群聊 Id。
inputs.data_objectNameString消息类型，例如文本消息 RC:TxtMsg、图片消息 RC:ImgMsg。
inputs.data_channelTypeString会话类型。PERSON（二人会话）、PERSONS（讨论组会话）、GROUP（群组会话）、TEMPGROUP（聊天室会话）、CUSTOMERSERVICE（客服会话）、NOTIFY（系统通知）、MC（应用公众服务）、MP（公众服务）、 ULTRAGROUP（超级群服务）。
inputs.data_msgTimestampNumber消息时间戳
inputs.data_msgUIDString消息唯一 ID
inputs.data_extraContentString附加消息内容

dify_chat​

参数路径类型说明
queryString用户输入的文本消息
response_modeString机器人集成配置中用于控制 stream 参数的响应模式
userString发送消息的用户标识
conversation_idString会话 ID，由融云端保存 24 小时，用于实现消息的上下文关联能力

dify_completion​

参数路径类型说明
inputs.queryString用户输入的文本消息
response_modeString机器人集成配置中用于控制 stream 参数的响应模式
userString发送消息的用户标识

dify_chatflow​

参数路径类型说明
queryString用户输入的文本消息
response_modeString机器人集成配置中用于控制 stream 参数的响应模式
userString发送消息的用户标识

回调请求示例​

dify_chat 和 dify_chatflow 示例​

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {
      "type": "message:group_mentioned",
      "timestamp": 1000,
      "bot_userId": "bo-001",
      "bot_type": "AI",
      "bot_name": "",
      "bot_profileUrl": "",
      "bot_metadata_creator": "运营团队",
      "bot_metadata_version": "v1.2",
      "data_fromUserId": "user123",
      "data_toUserId": "user123",
      "data_objectName": "RC:TxtMsg",
      "data_content": "",
      "data_channelType": "PERSON",
      "data_extraContent": "",
      "data_msgUID": "msg001",
      "data_msgTimestamp": 10000
    },
    "query": "What are the specs of the iPhone 13 Pro Max?",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123"
}'

diify_completion 示例​

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {
     "query": "What are the specs of the iPhone 13 Pro Max?",
      "type": "message:group_mentioned",
      "timestamp": 1000,
      "bot_userId": "bo-001",
      "bot_type": "AI",
      "bot_name": "",
      "bot_profileUrl": "",
      "bot_metadata_creator": "运营团队",
      "bot_metadata_version": "v1.2",
      "data_fromUserId": "user123",
      "data_toUserId": "user123",
      "data_objectName": "RC:TxtMsg",
      "data_content": "",
      "data_channelType": "PERSON",
      "data_extraContent": "",
      "data_msgUID": "msg001",
      "data_msgTimestamp": 10000
    },
    "response_mode": "streaming",
    "user": "abc-123"
}'

注意事项​

  • Dify 接口需公网可访问：确保回调目标地址可被机器人服务访问，否则将导致请求失败。
  • API Key 与 App 类型匹配：不同类型（如 chat、completion）需使用对应的 API Key。
  • 集成类型正确配置：Dify App 类型需与机器人中配置的集成模式一致。
  • 上下文 ID 管理合理：机器人会自动存储会话 ID 以支持上下文延续，时效为 24 小时。
最后于 更新