PyMessager

PyMessager 是一个用于 Facebook Messenger 的 Python API，同时也是一个演示如何在 Facebook Messenger 上开发聊天机器人的示例项目。

完整的教程可以在 使用 Python 开发 Facebook 机器人 和 聊天机器人：从 0 到 1 中找到，那里有更详细的设置和开发信息。

开始之前

1. 准备一个 Facebook 页面。（如果没有，请先创建）
2. 在 Facebook 开发者平台 上创建一个开发者应用。
3. 启动一个 Python 项目，并安装所需的包和模块：Flask、Requests。
4. 使用 Let's Encrypt 为你的域名申请 SSL 证书。

安装

要安装 PyMessager，只需运行：

$ pip install pymessager

或者从仓库安装：

$ git clone git@github.com:enginebai/PyMessager.git
$ cd PyMessager
$ pip install -r requirements.txt

开始使用

导入

from pymessager.message import Messager, ... # 其他你需要的

初始化

你可以通过开发者控制台中的 Facebook 访问令牌来初始化一个消息客户端：

from pymessager.message import Messager
client = Messager(config.facebook_access_token)

接收方 API

以下代码用于构建消息接收器，为你的机器人准备主要有三个步骤：

1. 设置 Webhook

@app.route(API_ROOT + FB_WEBHOOK, methods=["GET"])
def fb_webhook():
    verification_code = 'I_AM_VERIFICIATION_CODE'
    verify_token = request.args.get('hub.verify_token')
    if verification_code == verify_token:
        return request.args.get('hub.challenge')

2. 接收消息

@app.route(API_ROOT + FB_WEBHOOK, methods=['POST'])
def fb_receive_message():
    message_entries = json.loads(request.data.decode('utf8'))['entry']
    for entry in message_entries:
        for message in entry['messaging']:
            if message.get('message'):
                print("{sender[id]} says {message[text]}".format(**message))
    return "Hi"

3. 使用 HTTPS 启动服务器

if __name__ == '__main__':
    context = ('ssl/fullchain.pem', 'ssl/privkey.pem')
    app.run(host='0.0.0.0', debug=True, ssl_context=context)

发送方 API

消息类型包括 text、image、quick replies、button template 或 generic template。API 提供了不同的类来生成这些消息模板。

发送文本和图片

向收件人发送简单的文本或图片，只需确保图片 URL 是有效的链接。

client.send_text(user_id, "Hello, I'm enginebai.")
client.send_image(user_id, "http://image-url.jpg")

快速回复

QuickReply(title, payload, image_url, content_type) 类定义了响应消息时显示给用户的按钮。

参数	描述	必填
title	按钮标题	是
payload	点击后的有效载荷字符串	是
image_url	图标图片的 URL	否
content_type	TEXT 或 LOCATION	是

client.send_quick_replies(user_id, "Help", [
         QuickReply("Projects", Intent.PROJECT),
         QuickReply("Blog", Intent.BLOG),
         QuickReply("Contact Me", Intent.CONTACT_ME)
     ])

按钮模板

ActionButton(button_type, title, url, payload) 类定义了一个包含文本和按钮附件的按钮模板，用于请求用户输入。

参数	描述	必填
button_type	WEB_URL 或 POSTBACK	是
title	按钮标题	是
url	链接	仅当 button_type 为 url 时
payload	点击后的有效载荷字符串	仅当 button_type 为 POSTBACK 时

client.send_buttons(user_id, "You can find me with below", [
    ActionButton(ButtonType.WEB_URL, "Blog", "http://blog.enginebai.com"),
	ActionButton(ButtonType.POSTBACK, "Email", Intent.EMAIL)
])

通用模板

GenericElement(title, subtitle, image_url, buttons) 类定义了一个水平可滚动的商品轮播，每个商品都包含一张图片附件、简短描述以及用于请求用户输入的按钮。

参数	描述	必填
title_text	消息主标题	是
subtitle_text	消息副标题，不需要的话可以留空	否
button_list	ActionButton 的列表	是

project_list = []
for project_id, project in projects.items():
    project_list.append(GenericElement(
        project["title"],
        project["description"],
        config.api_root + project["image_url"], [
            ActionButton(ButtonType.POSTBACK,
                         self._get_string("button_more"),
                         # Payload use Intent for the beginning
                         payload=Intent.PROJECTS.name + project_id)
        ]))
client.send_generic(user_id, project_list)

实用 API

订阅页面

在你的聊天机器人开始接收消息之前，你需要将应用程序订阅到你的聊天机器人页面。要订阅页面，只需调用：

client.subscribe_to_page()

设置欢迎消息和“开始使用”按钮

问候语仅会在用户首次在移动端打开此聊天机器人时显示。有效载荷是用户点击“开始使用”按钮时触发的内容。

client.set_greeting_text("Hi, this is Engine Bai. Nice to meet you!")
client.set_get_started_button_payload("HELP")  # 指定一个有效载荷字符串。

问题

欢迎提交 bug 报告或功能请求，并在打开任何 issue 之前务必阅读贡献指南。

贡献

1. 检查当前已打开或已关闭的 issue，或者为功能请求或 bug 报告打开一个新的 issue，并使用不同的标签（feature/bug）。
2. 在 GitHub 上 fork 此 仓库，以便在 master 分支或新分支上进行自定义。
3. 编写一个测试，以证明该功能按预期工作，或 bug 已被修复。
4. 发送 pull request，并等待代码审查。

阅读更多关于贡献的信息。

许可证

MIT 许可证 (MIT)

版权所有 © 2017 Engine Bai。

特此授予任何人免费获取本软件及其相关文档文件（“软件”）副本的权利，允许其以任何方式处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售该软件的副本，并允许向接收软件的人提供该软件，但须遵守以下条件：

上述版权声明和本许可声明应包含在该软件的所有副本或实质性部分中。

“软件”按“原样”提供，不提供任何形式的担保，无论是明示的还是默示的，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论这些责任是基于合同、侵权行为或其他原因产生的，也无论这些责任是否与该软件或其使用有关，或以其他方式与之相关。

PyMessager 快速上手指南

PyMessager 是一个用于开发 Facebook Messenger 聊天机器人的 Python API 库。本指南将帮助你快速完成环境配置并运行第一个机器人。

环境准备

在开始之前，请确保满足以下前置条件：

1. Facebook 资源：
   • 拥有一个 Facebook 公共主页（Page）。
   • 在 Facebook for Developers 创建开发者应用，并获取 Page Access Token。
2. 系统依赖：
   • Python 环境（推荐 Python 3）。
   • Web 框架：Flask。
   • HTTP 库：Requests。
3. HTTPS 支持：
   • Facebook Messenger 要求回调地址必须为 HTTPS。请使用 Let's Encrypt 或其他方案为你的域名配置 SSL 证书。

安装步骤

你可以通过 PyPI 直接安装，或从源码安装。

方式一：使用 pip 安装（推荐）

$ pip install pymessager

国内加速提示：如果下载速度较慢，可使用清华或阿里镜像源：

$ pip install pymessager -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

$ git clone git@github.com:enginebai/PyMessager.git
$ cd PyMessager
$ pip install -r requirements.txt

基本使用

以下是构建一个简单的消息收发机器人的核心步骤。

1. 初始化客户端

导入库并使用你的 Facebook Access Token 初始化客户端。

from pymessager.message import Messager

# 替换为你的实际 Token
client = Messager(config.facebook_access_token)

2. 设置消息接收 (Webhook)

使用 Flask 搭建服务器以接收 Facebook 的回调请求。你需要处理验证（GET）和消息接收（POST）两个路由。

from flask import Flask, request
import json

app = Flask(__name__)
API_ROOT = ""
FB_WEBHOOK = "/webhook"

# 步骤 1: 验证 Webhook
@app.route(API_ROOT + FB_WEBHOOK, methods=["GET"])
def fb_webhook():
    verification_code = 'I_AM_VERIFICIATION_CODE' # 需在 Facebook 开发者后台设置相同的 verify_token
    verify_token = request.args.get('hub.verify_token')
    if verification_code == verify_token:
        return request.args.get('hub.challenge')
    return "Error", 403

# 步骤 2: 接收消息
@app.route(API_ROOT + FB_WEBHOOK, methods=['POST'])
def fb_receive_message():
    message_entries = json.loads(request.data.decode('utf8'))['entry']
    for entry in message_entries:
        for message in entry['messaging']:
            if message.get('message'):
                sender_id = message['sender']['id']
                text = message['message']['text']
                print(f"{sender_id} says {text}")
                
                # 简单回复示例
                client.send_text(sender_id, f"You said: {text}")
    return "Hi"

# 步骤 3: 启动 HTTPS 服务器
if __name__ == '__main__':
    # 请确保 ssl/fullchain.pem 和 ssl/privkey.pem 路径正确
    context = ('ssl/fullchain.pem', 'ssl/privkey.pem')
    app.run(host='0.0.0.0', debug=True, ssl_context=context)

3. 发送消息示例

初始化 client 后，你可以轻松发送文本、图片或交互按钮。

发送文本和图片：

client.send_text(user_id, "Hello, I'm enginebai.")
client.send_image(user_id, "http://image-url.jpg")

发送快捷回复 (Quick Replies)：

from pymessager.message import QuickReply

client.send_quick_replies(user_id, "Help", [
    QuickReply("Projects", "INTENT_PROJECT"),
    QuickReply("Blog", "INTENT_BLOG"),
    QuickReply("Contact Me", "INTENT_CONTACT")
])

发送按钮模板 (Button Template)：

from pymessager.message import ActionButton, ButtonType

client.send_buttons(user_id, "You can find me with below", [
    ActionButton(ButtonType.WEB_URL, "Blog", "http://blog.enginebai.com"),
    ActionButton(ButtonType.POSTBACK, "Email", "INTENT_EMAIL")
])

4. 初始配置（可选但推荐）

在用户首次与机器人互动前，建议设置欢迎语和“开始”按钮。

# 订阅页面（通常在部署后执行一次）
client.subscribe_to_page()

# 设置问候语和开始按钮载荷
client.set_greeting_text("Hi, this is Engine Bai. Nice to meet you!")
client.set_get_started_button_payload("HELP")

完成上述步骤后，将你的 HTTPS 域名配置到 Facebook 开发者后台的 Webhook 设置中，即可开始测试你的聊天机器人。