logo
开发者文档
搜索
用户概述

用户概述

用户是指 Agent/workflow 发起对话的终端用户,GPTBots 支持开发者为不同用户设置唯一身份标识ID,通过该用户IDuser_id可以在不同渠道之间进行用户 身份关联,实现跨渠道用户身份合并、 通过 Tools 实现业务业务查询、维护用户属性和聊天记录等。

用户 CDP 信息存储于 Agent/workflow 之下,同个用户在不同的 Agent/Workflow 下数据是相互隔离的。

用户体系示意图

flowchart LR
 subgraph Col1["用户来源平台"]
        LC["Livechat"]
        IC["Intercom"]
        WG[" Widget "]
        TG["Telegram"]
  end
 subgraph Col2_5["来源平台子Channel"]
        tgb01["TGBOT01"]
        tgb02["TGBOT02"]
  end
 subgraph Col2["匿名 ID"]
        a1["lc0001"]
        a2["ic0001"]
        a3["wg0001"]
        tga1["tb0001"]
        tga2["tg0001"]
  end
 subgraph Col3["UserId"]
        U1["ABC123"]
        U2["ABC456"]
  end
 subgraph Col4["ConversationId"]
        c1["c001"]
        c2["c002"]
        c3["c003"]
        c4["c004"]
        c5["c005"]
  end
 subgraph Col5["Agent/Workflow"]
        Bot["Agent
        Workflow"]
  end
    LC -- 自动生成匿名ID --> a1
    IC -- 自动生成匿名ID --> a2
    WG -- 自动生成匿名ID --> a3
    TG -- 用户来源于子channel --> tgb01 & tgb02
    tgb01 -- 自动生成匿名ID --> tga1
    tgb02 -- 自动生成匿名ID --> tga2
    a1 -- 设置user_id --> U1
    a2 -- 设置user_id --> U1
    a3 -- 设置user_id --> U2
    tga1 -- 设置user_id --> U2
    tga2 -- 设置user_id --> U2
    U1 -- 生成新对话ID --> c1
    U1 -- 生成新对话ID --> c2
    U2 -- 生成新对话ID --> c3
    U2 -- 使用旧对话ID --> c4
    c4 -- 若过期(>60分钟)
    自动生成新对话ID --> c5
    c1 --> Bot
    c2 --> Bot
    c3 --> Bot
    c4 --> Bot
    c5 --> Bot

     LC:::redStyle
     IC:::blueStyle
     WG:::greenStyle
     TG:::purpleStyle
     tgb01:::purpleStyle
     tgb02:::purpleStyle
     a1:::redStyle
     a2:::blueStyle
     a3:::greenStyle
     tga1:::purpleStyle
     tga2:::purpleStyle
     U1:::userGray
     U2:::userGray
     c1:::redStyle
     c2:::blueStyle
     c3:::greenStyle
     c4:::purpleStyle
     c5:::purpleStyle
    classDef userGray fill:#f5f5f5,stroke:#e6e6e6,color:#222
    classDef redStyle fill:#ffd6d6,stroke:#ffbdbd,color:#222
    classDef blueStyle fill:#dff0ff,stroke:#cfeaff,color:#222
    classDef greenStyle fill:#ecffd9,stroke:#d5ffb3,color:#222
    classDef purpleStyle fill:#f1e0ff,stroke:#e1c7ff,color:#222
    style Col1 stroke:#757575
  • 匿名ID(anonymous_id)由 GPTBots 系统服务根据用户来源平台自动生成。
  • 设置user_id是可选的,开发者可以根据业务场景需要自定决定是否为用户设置user_id,以实现在不同渠道之间进行用户身份关联和用户属性共用。

定义

用户

用户是指与 Agent 产生对话的终端用户。

用户ID(user_id)

由企业开发者为终端用户所赋予的身份唯一标识ID,通过 API 接口支持开发者为某个匿名ID设置UserId。UseId 的使用场景和高级用法请参考设置用户ID

  • user_id级别高于anonymous_id
  • 多个anonymous_id可以同时属于一个user_id

匿名ID(anonymous_id)

用户在三方平台(如:Telegram、WhatsApp、LINE等)与 Agent 进行对话时,GPTBots 会使用该三方平台的用户惟一标识符作为anonymous_id。 匿名ID的生成逻辑请参考[匿名ID取值逻辑](## 匿名ID取值逻辑)。

三方平台

GPTBots 平台当前支持将 Agent 集成至众多三方平台,包含:intercom 、webchat、 livechat 、 telegram 、 WhatsApp 等

对话ID(conversation_id)

对话ID(conversation_id)由 Agent、对话类型和 user_id(anonymous_id)所共同生成的惟一标识ID,conversation_id是不同业务场景隔离的最小单位(通常包含多个消息ID)。

  • conversation_id 的自动过期时间为 60分钟,但通过 API 渠道生成的conversation_id 没有过期时间。
  • 三方平台和部件气泡等渠道所生成的conversation_id在过期后会再次生成一个全新的conversation_id开启一轮新对话。

消息ID(message_id)

消息ID 即message_id用于标识 Agent 与用户的一次对话消息,是 Agent 与用户的一次对话的最小单位。

  • message_id 是由 GPTBots 平台生成的,开发者无法自定义message_id
  • message_id 归属于conversation_id,一个 conversation_id通常包含多个message_id

对话类型

对话类型(conversation_type)用于标识用户发起对话场景,如:工作空间-Workflow、WhatsApp、API、工作空间-Search 等。

对话ID(conversation_id)的生成原理

当用户通过三方平台与 Agent 发起对话时,系统会根据用户所在的三方平台,为用户生成的anonymous_id,并基于anonymous_id自动生成conversation_id用于承载用户与 Agent 的一轮对话。

  • 开发者通过 API 方式使用时,必须先生成conversation_id,方可发起与 Agent/Workflow 的对话。
  • 非 API 的其他渠道平台,GPTBots 会自动生成conversation_id

匿名ID 取值逻辑

匿名ID来源平台 匿名ID取值逻辑 对应来源平台字段 说明
Telegram Telegram用户ID tg_user_id Telegram 用户的唯一数字标识符,用于区分不同用户
Telegram 群聊 Telegram chatID + Telegram 用户ID tg_chat_id + tg_user_id 群聊的聊天会话标识符与用户标识符的组合,用于在群组环境中唯一标识用户互动
LINE LINE 用户ID line_user_id LINE 用户的唯一标识符,用于识别平台内的个体用户
LiveChat LiveChat threadId lc_thread_id LiveChat 会话线程的唯一标识符,用于跟踪和管理用户对话线程
Slack Slack 用户ID slack_user_id Slack 用户的唯一标识符,用于识别平台内的个体用户
Slack Public Channel Slack(teamId+channelId+UserId) slack_team_id + slack_channel_id + slack_user_id Slack 团队标识符、公共频道标识符与用户标识符的组合,用于在公共频道中唯一标识用户
Intercom Intercom用户ID intercom_user_id Intercom 用户的唯一标识符,用于客户支持平台中的用户追踪和管理
钉钉 钉钉 senderId dd_user_id 钉钉用户的唯一标识符,用于企业协作平台中的用户区分
钉钉群聊 钉钉(senderId+群聊ID) dd_chat_id + dd_senderId 钉钉分配给消息发送者的唯一标识符、群聊的唯一标识符,用于企业协作平台中的用户区分
WhatsApp by meta WhatsApp 用户 ID wa_user_id WhatsApp 用户的唯一标识符,通常基于用户的手机号码(例如,国际格式手机号码后缀@c.us)
WhatsApp by EngageLab WhatsApp 用户 ID wa_user_id WhatsApp 用户的唯一标识符,通常基于用户的手机号码(例如,国际格式手机号码后缀@c.us)
Discord Discord用户ID discord_user_id Discord 用户的唯一数字标识符,用于游戏和社区平台中的用户识别
Instagram Instagram senderId instagram_user_id Instagram 分配给消息发送者(即 Instagram 用户)的唯一标识符
Facebook senderId facebook_user_id Facebook 分配给消息发送者(即 Instagram 用户)的唯一标识符
sobot Sobot memberId sobot_memberId sobot 用户 ID
Sobot 群聊@用户 Sobot(guildId + channelId + memberId) guildId + channelId + memberId Sobot 群聊@用户的唯一标识符,用于在群聊环境中唯一标识用户互动
Intercom senderId intercom_senderId Intercom 用户 ID
Zoho Sales IQ zoho conversationId zoho_sales_iq_conversationId Zoho Sales IQ 的对话惟一标识符
微信客服 微信客服用户ID wechat_customer_service_user_id 微信客服 用户 ID

GPTBots内置渠道匿名ID(anonymous_id)取值逻辑

集成渠道 匿名ID取值逻辑 说明
API 无匿名ID 用户仅可使用user_id生成对话ID
工作空间 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID
分享 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID
Iframe 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID
AI搜索 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID
AI搜索(iframe) 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID
Widget 匿名ID=浏览器指纹ID 基于浏览器指纹生成随机ID,清除缓存或无痕模式下可能会生成新的ID

当用户已登录 GPTBots 平台时,系统自动将其 GPTBots账户ID设置为user_id,并自动关联anonymous_id(浏览器指纹ID)。

对话类型

对话类型(conversation_type)用于标识用户发起对话场景,通过conversation_type字段值可以分场景查询日志数据。

对话类型 字段值 说明
全部 ALL 全部类型来源的对话ID
工作空间-Search C 工作空间Agent产生的对话ID
工作空间-Agent CHAT 工作空间Search产生的对话ID
工作空间-Workflow C_WORKFLOW 工作空间 Workflow 产生的对话ID
工作空间-Apps C_APPS 工作空间 Market 各类 AI 应用产生的对话ID
API API API调用产生的对话ID
Iframe EMBED Iframe产生的对话ID
部件气泡 WIDGET 部件气泡产生的对话ID
AI搜索 AI_SEARCH AI搜索产生的对话ID
分享 SHARE 分享产生的对话ID
WhatsApp by Meta WHATSAPP_META WhatsApp by Meta产生的对话ID
WhatsApp by EngageLab WHATSAPP_ENGAGELAB WhatsApp by EngageLab产生的对话ID
钉钉机器人 DINGTALK 钉钉机器人产生的对话ID
Discord DISCORD Discord产生的对话ID
Slack SLACK Slack产生的对话ID
Zapier ZAPIER Zapier产生的对话ID
微信客服 WXKF 微信客服产生的对话ID
Telegram TELEGRAM Telegram产生的对话ID
LiveChat LIVECHAT LiveChat产生的对话ID
LINE LINE LINE产生的对话ID,若存在多个LINE Channel,则会有多个Channel选项
Instagram INSTAGRAM Instagram产生的对话ID
Facebook FACEBOOK Facebook产生的对话ID
Sobot SO_BOT Sobot产生的对话ID
Zoho Sales IQ ZOHO_SALES_IQ Zoho Sales IQ产生的对话ID
Intercom INTERCOM Intercom产生的对话ID

⚠️ 注意:表格中的字段值,可用于通过 API获取对话列表数据的筛选条件。
如 LINE、Telegram 等支持添加多个通道的三方平台,「Agent-日志」进行筛选对话类型会支持 2 级类型。
表格中的字段值,可在更新用户ID API中作为anonymous_id_source字段的值。