Bottender

以下 README 是 Bottender v1（稳定版）的文档。如需查看其他版本的文档，请访问：

• 最新 Bottender 版本（v1.x）：https://bottender.js.org/docs/
• 旧版 Bottender（v0.15）：https://bottender.js.org/docs/0.15.17/

• 声明式（Declarative） - Bottender 为你处理对话式用户界面（conversational UIs）的复杂性。你只需为应用中的每个事件和状态设计对应的操作（actions），Bottender 会自动执行。这种方式使你的代码更具可预测性，也更容易调试。

• 原生用户体验（Native User Experience） - Bottender 让你能在所有渠道上构建应用，同时绝不牺牲用户的体验。你可以对构建模块采用渐进增强（progressive enhancement）或优雅降级（graceful degradation）策略。

• 轻松设置（Easy Setup） - 使用 Bottender，你只需少量配置即可让机器人与各渠道对接，包括自动服务器监听、Webhook 设置、签名验证等。

• 生产就绪（Ready for Production） - 已有数千个机器人基于 Bottender 构建。它针对真实世界用例进行了优化，支持自动批量请求（automatic batching request）等众多强大功能。

Bottender 基于 Messaging APIs 构建。

安装

你可以使用 CLI 工具创建一个新的 Bottender 应用：

npx create-bottender-app my-app

在 Windows 上安装时，可能会因 node-gyp 编译原生依赖失败。要解决此问题，你可以安装 windows-build-tools，或查阅 node-gyp 文档。

文档

你可以在 官方网站 找到 Bottender 的完整文档。

快速入门请查看 Getting Started 页面。

社区

你可以在我们的 Discord 服务器中讨论任何关于 Bottender 或聊天机器人开发的话题。立即加入！

示例

我们在 examples 文件夹中提供了大量示例。以下是最简单的入门示例：

// index.js
const { router, text } = require('bottender/router');

async function SayHi(context) {
  await context.sendText('Hi!');
}

async function Unknown(context) {
  await context.sendText('Sorry, I don’t know what you say.');
}

module.export = function App(context) {
  return router([text('hi', SayHi), text('*', Unknown)]);
};

主要功能

Messenger

• Messenger Profile 同步
• 附件上传（Attachment Upload）
• 转交协议（Handover Protocol）
• Persona
• 内置 NLP（Built-in NLP）
• 多页面支持（Multiple Pages）

LINE

• 回复、推送、多播、窄播（Reply, Push, Multicast, Narrowcast）
• 图片地图（Imagemap）
• 富菜单（Rich menu）
• 房间与群组聊天（Room, Group Chat）
• Beacon
• 图标切换（Icon Switch）
• Line Notify
• LIFF（LINE Front-end Framework）

Slack

• 频道聊天（Channel Chat）
• 交互式消息（Interactive Message）
• 斜杠命令（Slash Command）

Telegram

• Webhook 与长轮询（Webhook, Long Polling）
• 更新与删除消息（Updating, Deleting Messages）
• 键盘（Keyboard）
• 群组聊天（Group Chat）
• 内联查询（Inline Query）
• 消息实时位置（Message Live Location）
• 支付（Payment）

Viber

• 订阅/取消订阅事件（Subscribed, Unsubscribed Event）
• 已送达/已读事件（Delivered, Seen Event）

生态系统

• bottender-compose - 一个用于 Bottender 和高阶处理器（higher-order handlers）的工具库。

贡献

欢迎提交 Pull Request 和问题报告。你可以按照以下步骤提交 PR：

先 Fork 并克隆仓库：

git clone git@github.com:your-username/bottender.git

安装依赖：

cd bottender
yarn

确保所有测试通过（包括 ESLint、TypeScript 检查和 Jest 测试）：

yarn test

进行修改并添加测试，确保测试仍然通过。

使用在线一键设置进行贡献

你可以使用 Gitpod（一个免费的在线 VS Code 类似环境）进行贡献。只需点击一次，它将自动：

• 克隆 bottender 仓库
• 安装依赖
• 运行 yarn run start

让你立即开始开发。

许可证

MIT © Yoctol

Bottender 快速上手指南

环境准备

• 操作系统：Windows / macOS / Linux 均可
• Node.js：建议使用 v14 或更高版本（推荐 LTS 版本）
• npm / yarn：确保已安装包管理工具（推荐使用 yarn）

💡 国内用户提示：
若安装速度较慢，可配置 npm 或 yarn 使用国内镜像源（如淘宝 NPM 镜像）：

npm config set registry https://registry.npmmirror.com
# 或使用 yarn
yarn config set registry https://registry.npmmirror.com

⚠️ Windows 用户注意：
安装时若遇到 node-gyp 编译错误，请先安装构建工具：

npm install -g windows-build-tools

安装步骤

使用官方 CLI 快速创建新项目：

npx create-bottender-app my-app

进入项目目录并启动开发服务器：

cd my-app
npm start
# 或
yarn start

基本使用

以下是最简示例，实现一个能响应 “hi” 的聊天机器人：

// index.js
const { router, text } = require('bottender/router');

async function SayHi(context) {
  await context.sendText('Hi!');
}

async function Unknown(context) {
  await context.sendText('Sorry, I don’t know what you say.');
}

module.exports = function App(context) {
  return router([text('hi', SayHi), text('*', Unknown)]);
};

将上述代码保存为 index.js，配合 Bottender 项目模板即可运行。当用户发送 “hi” 时，机器人回复 “Hi!”；其他消息则返回未知提示。

📚 更多用法请参考官方文档：https://bottender.js.org/docs