Facebook Messenger¶

概述¶

Facebook Messenger Channel通过Messenger Platform API接入，支持发送多种类型消息。

官方文档: https://developers.facebook.com/docs/messenger-platform
接入方式: Page Access Token
API版本: Graph API v19.0
支持消息类型: 文本、图片、音频、视频、文件、按钮模板、通用模板

配置参数¶

Config 结构体¶

type Config struct {
    PageID          string  // 页面ID
    PageAccessToken string  // 页面访问令牌
    AppSecret       string  // 应用密钥
    VerifyToken     string  // 验证令牌
    WebhookURL      string  // Webhook地址
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`page_id`	string	是	-	Facebook页面ID
`page_access_token`	string	是	-	页面访问令牌
`app_secret`	string	否	""	Facebook应用密钥
`verify_token`	string	否	""	Webhook验证令牌
`webhook_url`	string	否	""	Webhook接收地址

page_id¶

数据类型: string
格式: 数字字符串
获取方式:
登录Facebook开发者控制台
进入应用 → Messenger → 设置
找到连接的页面ID

pageaccesstoken¶

数据类型: string
格式: 长字符串，如 EAAB...
获取方式:
在Messenger设置中生成
必须是页面级别的Token
不会过期（除非页面取消授权）

app_secret¶

数据类型: string
用途: 验证Webhook请求的签名
获取方式: Facebook应用设置 → 基本 → 应用密钥

verify_token¶

数据类型: string
用途: Webhook订阅验证
配置: 在代码和Facebook后台保持一致

完整配置示例¶

YAML配置¶

channels:
  - name: messenger-bot
    type: messenger
    config:
      page_id: "123456789012345"
      page_access_token: "EAABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      verify_token: "your-verify-token"
      webhook_url: "https://your-domain.com/webhook/messenger"

Go代码配置¶

import (
    "github.com/example/gort/pkg/channel/messenger"
)

config := messenger.Config{
    PageID:          "123456789012345",
    PageAccessToken: "EAABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    AppSecret:       "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    VerifyToken:     "your-verify-token",
    WebhookURL:      "https://your-domain.com/webhook/messenger",
}

ch, err := messenger.NewMessengerChannel("messenger-bot", config)
if err != nil {
    log.Fatal(err)
}

前置要求¶

1. Facebook开发者账号¶

需要有效的Facebook开发者账号
需要Facebook页面（Page）

2. Facebook应用设置¶

创建Facebook应用
添加Messenger产品
连接Facebook页面
生成Page Access Token

3. Webhook配置¶

配置Webhook URL
设置Verify Token
订阅消息事件:
messages
messaging_postbacks
message_reads

4. 权限申请¶

需要以下权限： - pages_messaging - pages_read_engagement

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	普通文本
图片消息	✅	图片附件
音频消息	✅	音频文件
视频消息	✅	视频文件
文件消息	✅	任意文件
按钮模板	✅	带按钮的消息
通用模板	✅	结构化消息

能力矩阵¶

GetCapabilities() 返回:
- TextMessages:     true
- MarkdownMessages: false
- ImageMessages:    true
- FileMessages:     true
- AudioMessages:    true
- VideoMessages:    true
- TemplateMessages: true
- ReadReceipts:     false
- TypingIndicators: false
- MessageEditing:   false
- MessageDeletion:  false
- ReactionMessages: false

常见配置问题¶

问题1: Page Access Token无效¶

现象: API返回"Invalid token"

原因: - Token错误 - 页面取消授权

解决:

// 确认使用页面级别的Token
config := messenger.Config{
    PageAccessToken: "EAAB...",  // 不是应用Token
}

// 在开发者控制台重新生成Token

问题2: 无法发送消息¶

现象: 返回"User has not responded within 24 hours"

原因: 用户24小时内未与页面互动

解决: - 使用消息标签（Message Tags） - 引导用户先发送消息 - 使用赞助消息（需付费）

问题3: Webhook验证失败¶

现象: Facebook无法验证Webhook

原因: - URL不可访问 - Verify Token不匹配

解决: 1. 确保URL可公网访问且使用HTTPS 2. 确认Verify Token与代码配置一致

发送消息示例¶

发送文本消息¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "messenger-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "1234567890"},  // PSID
    Content:   "Hello Messenger!",
    Type:      message.MessageTypeText,
}

err := ch.SendMessage(ctx, msg)

发送带按钮的消息¶

msg := &message.Message{
    ID:        "msg-2",
    ChannelID: "messenger-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "1234567890"},
    Content:   "Choose an option:",
    Type:      message.MessageTypeText,
}
msg.SetMetadata("buttons", []map[string]string{
    {"type": "postback", "title": "Option 1", "payload": "opt1"},
    {"type": "postback", "title": "Option 2", "payload": "opt2"},
})

err := ch.SendMessage(ctx, msg)

安全建议¶

Token保护: Page Access Token长期有效，请妥善保管
Webhook验证: 使用AppSecret验证签名
HTTPS强制: Webhook必须使用HTTPS
权限控制: 只申请必要的权限

错误代码参考¶

错误	说明
`ErrPageAccessTokenEmpty`	缺少页面访问令牌
`ErrInvalidSignature`	Webhook签名验证失败
`ErrUserNotResponded`	用户24小时内未响应