Dialogflow对接Telegram机器人自定义Payload报错排查

核心结论 #

Dialogflow Fulfillment完全支持Telegram自定义Payload，你的问题大概率是Payload语法错误，或者响应格式不符合要求。

1. 正确的Telegram自定义Payload格式 #

Telegram的自定义Payload必须嵌套在payload.telegram字段下，按钮需使用Telegram官方的键盘格式（内联键盘或普通键盘）。以下是同时返回注册卡片和带“是/否”按钮消息的正确代码示例：

// 添加注册表单卡片
agent.add(new Card({
  title: '注册表单',
  text: '请填写以下信息完成注册',
  buttonText: '打开注册表单',
  buttonUrl: 'https://your-reg-form-url.com'
}));

// 添加带是/否按钮的自定义Payload（内联键盘示例）
agent.add({
  payload: {
    telegram: {
      text: '还需要其他帮助吗？',
      reply_markup: {
        inline_keyboard: [
          [{ text: '是', callback_data: 'need_help' }],
          [{ text: '否', callback_data: 'no_help' }]
        ]
      }
    }
  }
});

如果要用普通键盘（而非内联按钮），将inline_keyboard替换为keyboard即可：

reply_markup: {
  keyboard: [['是', '否']],
  resize_keyboard: true,
  one_time_keyboard: true
}

2. 排查Webhook 500错误（URL_UNREACHABLE） #

• 语法错误检查：检查Payload的JSON结构是否完整，比如逗号、括号是否闭合，属性名是否正确（Telegram的字段名均为小写，如reply_markup而非replyMarkup）。
• Webhook可用性：确保Dialogflow配置的Webhook URL是公网可访问的，没有被防火墙或CDN拦截。
• 日志排查：在Dialogflow控制台的「Fulfillment」→「日志」中查看具体的错误堆栈，定位代码中的问题（比如变量未定义、函数调用错误等）。

3. 解决followupEvent跳过卡片的问题 #

使用setFollowupEvent()会直接触发指定的后续意图，当前意图的响应内容（比如注册卡片）不会被发送，因为followup是直接跳转逻辑，而非追加响应。因此正确的做法是在同一个意图中同时返回卡片和Payload，不要拆分到两个意图。

4. 在线编辑器额外注意事项 #

如果使用Dialogflow的在线编辑器（Inline Editor），需确保：

• 代码没有语法错误（比如缺少分号、拼写错误）
• 已正确引入所需模块（Card类默认已在Dialogflow的Node.js环境中可用）

内容的提问来源于stack exchange，提问作者Hannah