Evolution API 与 Chatwoot 集成中的消息收发问题分析与解决方案

问题背景

在 Evolution API 与 Chatwoot 的集成过程中，许多开发者遇到了一个典型问题：能够通过 Chatwoot 成功发送消息，但无法接收来自客户端的消息。这个问题在 Evolution API 2.1.1 至 2.2.3 版本和 Chatwoot 3.9 至 4.0.1 版本中均有报告。

技术现象分析

从开发者提供的日志和描述中，我们可以观察到几个关键现象：

1. 消息发送成功但接收失败：系统能够正常发送消息到用户，日志显示消息已成功传递，但来自客户端的回复消息无法在 Chatwoot 界面显示。

2. 日志中的错误信息：部分日志显示"contact not found"和"conversation not found"错误，表明系统在尝试处理接收到的消息时无法找到对应的联系人和会话记录。

3. WebSocket 连接问题：某些情况下会出现 WebSocket 连接在建立前就被关闭的错误，这可能影响消息的实时接收。

根本原因

经过对多个案例的分析，我们发现主要原因集中在以下几个方面：

1. SQS 配置误解：Evolution API 管理界面中的"SQS Enable/Disable"开关被许多开发者误解。虽然标签提到SQS，但实际上这个开关控制的是整个Chatwoot集成的启用状态，而不仅仅是SQS功能。

2. 权限验证问题：部分401 Unauthorized错误表明API请求缺乏有效的认证凭证，这可能与Chatwoot的访问令牌配置不正确有关。

3. 会话记录缺失：某些情况下，系统无法找到有效的会话记录来处理接收到的消息，这通常与实例初始化或会话持久化问题相关。

解决方案

1. 正确配置集成开关

在Evolution API管理界面的Chatwoot配置部分，确保启用第一个开关（标记为"Enable or disable the sqs"）。这个开关实际上控制整个Chatwoot集成的启用状态：

• 访问Evolution API管理界面
• 导航到实例的Chatwoot配置部分
• 确保"Enabled"开关处于开启状态
• 保存配置并重启服务

2. 验证认证配置

确保Chatwoot的API访问令牌正确配置：

• 检查Evolution API配置中的Chatwoot访问令牌
• 验证Chatwoot实例的API端点URL是否正确
• 确保使用的账户ID与Chatwoot中的实际账户匹配

3. 处理群组消息问题

对于无法接收群组消息的情况：

• 检查Evolution API配置中"忽略群组"选项是否被意外启用
• 验证Bot账号在目标群组中的成员身份
• 确保群组ID格式正确

4. 版本兼容性建议

使用经过验证的版本组合：

• Evolution API 2.1.2或更高版本
• Chatwoot 3.13.0或更高版本

最佳实践

1. 配置顺序：建议先完成Chatwoot的基本配置，再在Evolution API中设置集成。

2. 日志监控：定期检查Evolution API和Chatwoot的日志，特别是关注401 Unauthorized和SessionError等错误。

3. 测试流程：

   • 首先测试从Chatwoot发送消息
   • 然后从不同的客户端回复消息
   • 最后验证消息是否出现在Chatwoot对话中

4. 环境检查：

   • 确保网络连接稳定
   • 验证防火墙设置不会阻止Evolution API和Chatwoot之间的通信
   • 检查系统时间同步，避免认证问题

总结

Evolution API与Chatwoot的集成问题多源于配置误解和版本兼容性。通过正确理解配置选项的含义、遵循推荐的配置顺序和使用经过验证的版本组合，大多数收发消息问题都可以得到解决。对于更复杂的环境，建议分步调试，从基础功能开始逐步验证每个环节的正常工作。