EvolutionAPI消息截断问题分析与解决方案

问题背景

在基于EvolutionAPI构建的即时通讯聊天机器人系统中，开发者发现了一个关键性的消息传输问题。当系统通过Flow Builder与AI服务(如Flowise+OpenAI)集成时，AI生成的完整响应消息在内部测试环境中显示正常，但通过EvolutionAPI传输到通讯客户端时出现了内容截断现象。

现象描述

具体表现为：

1. AI服务返回的完整响应包含多行文本和选项菜单（如健身目标选择的4个选项）
2. Flow Builder的对话模拟界面能正确显示全部内容
3. 但通讯客户端仅显示部分文本，关键选项信息丢失

示例消息结构：

{
  "text": "Ótimo, Mauricio! Agora...\n\n1. Perder Peso.\n2. Ganhar...",
  "question": "13981283322",
  "chatMessageId": "272169fc-..."
}

技术分析

经过深入排查，发现问题的核心在于消息处理链中的以下几个技术点：

1. 换行符处理异常
   AI响应中的\n\n换行符可能被错误解析为消息结束标记，导致后续内容被丢弃。MessageProtocol对特殊字符的处理需要特别注意。

2. 消息长度限制
   EvolutionAPI可能默认启用了消息长度限制机制，而包含选项菜单的AI响应往往超过标准文本消息长度。

3. 内容类型识别
   系统未能正确识别带编号列表的消息结构，导致无法自动转换为通讯平台支持的列表消息格式(ListMessage)。

4. 字符编码问题
   葡萄牙语等特殊字符可能在传输过程中出现编码转换问题，加剧了内容截断现象。

解决方案

针对上述分析，建议采取以下解决方案：

1. 消息预处理中间件
   在EvolutionAPI前端添加消息格式化层：

   def format_ai_response(response):
       # 统一换行符为通讯平台兼容格式
       text = response['text'].replace('\n\n', '\n')
       # 检测编号列表并转换为交互式按钮
       if re.match(r'\d+\.\s+.+', text):
           return convert_to_interactive(text)
       return {'text': text}
   

2. 协议层优化
   修改MessageProtocol实现，确保：

   • 正确处理多行文本消息
   • 支持扩展字符集
   • 实现自动分片机制处理长消息

3. 配置调整
   在evolution-api配置中增加：

   messaging:
     max_length: 4096  # 扩展默认长度限制
     preserve_newlines: true
     auto_convert_lists: true
   

实施建议

1. 版本验证
   建议在测试环境验证最新版EvolutionAPI是否已修复相关问题

2. 监控机制
   添加消息完整性检查日志：

   [MessageIntegrity] Input: 580chars | Output: 520chars | Diff: 60chars
   

3. 备用呈现方案
   对于关键选项消息，可考虑：

   • 转换为通讯平台官方列表消息
   • 使用快速回复按钮(Quick Replies)
   • 采用多消息分片发送

影响评估

该问题的解决将直接影响以下技术栈的集成：

• AI编排工具(Flowise/CrewAI/Dify)的输出兼容性
• 多语言聊天机器人的消息可靠性
• 复杂交互流程的用户体验

通过系统性的协议优化和预处理机制，可以确保EvolutionAPI在AI集成场景下保持消息传输的完整性和可靠性。建议开发者在实现类似功能时，特别注意特殊字符处理和消息类型转换这两个关键环节。