Campsite项目Bot DMs功能开发指南

什么是Bot DMs功能

Bot DMs（机器人私信）是Campsite项目中一项强大的功能，它允许用户与你的集成应用进行一对一的私密对话。当启用此功能后，用户可以在侧边栏中看到你的应用名称和头像，并像与真人对话一样发起私信会话。

功能启用步骤详解

1. 设置Webhook监听

首先需要建立一个能够监听message.dm事件的Webhook端点。这个Webhook需要满足以下要求：

• 必须是HTTPS协议的安全端点
• 需要正确处理Campsite发送的验证请求
• 能够快速响应（建议响应时间<3秒）

2. 确保Webhook活跃

Webhook必须保持活跃状态并能够正确响应事件。Campsite会定期检查Webhook的可用性，如果检测到多次失败，可能会暂时禁用你的集成。

3. 用户界面显示

当上述条件满足后，你的集成应用将自动出现在用户的"新建会话"界面中，并带有特殊的"应用"徽章标识。

消息处理机制

接收用户消息

当用户向你的应用发送消息时，Campsite会向你的Webhook发送一个包含message.dm事件类型的请求。典型的消息负载结构如下：

{
  "id": "唯一事件ID",
  "type": "message.dm",
  "timestamp": "ISO8601时间戳",
  "organization_id": "组织ID",
  "application_id": "应用ID",
  "data": {
    "message": {
      "id": "消息ID",
      "content": "消息内容",
      "created_at": "创建时间",
      "thread_id": "会话线程ID",
      "sender": {
        "id": "用户ID",
        "name": "用户名称",
        "type": "user",
        "avatar_urls": {
          "xs": "小尺寸头像URL",
          "sm": "中等尺寸头像URL",
          "base": "基础尺寸头像URL"
        }
      }
    }
  }
}

发送消息给用户

Campsite提供了专门的API端点用于向用户发送私信。这个接口设计有以下特点：

• 使用用户ID而非会话ID进行消息发送
• 无需维护每个用户的会话线程ID
• 支持富文本消息格式
• 提供消息已读回执功能

最佳实践指南

响应时效性

• 即时响应：对于简单查询，建议在3秒内回复
• 处理中状态：对于耗时操作，应先发送"处理中"状态反馈
• 进度更新：长时间操作应定期发送进度更新

错误处理

• 清晰错误：使用用户友好的错误描述
• 恢复建议：提供明确的恢复步骤
• 日志记录：记录完整错误上下文供调试

用户体验

• 一致性：保持与Campsite界面风格一致
• 可预测：遵循常见对话模式
• 可访问：考虑不同用户群体的使用习惯

高级功能扩展

对于需要更复杂交互的场景，可以考虑：

1. 上下文记忆：存储会话上下文提供连贯对话体验
2. 快捷操作：在消息中嵌入可点击的快捷操作按钮
3. 富媒体支持：合理使用图片、视频等富媒体内容
4. 多语言支持：根据用户偏好自动切换语言

通过合理利用Bot DMs功能，开发者可以在Campsite平台上构建出高度交互性、用户友好的集成应用，显著提升用户体验和工作效率。