messaging-api

LINE Messaging API

不要凭记忆回答 LINE API 问题——LINE 会频繁更新 API，训练数据不可靠。请务必查阅以下参考资料。

用于构建、审查和调试 LINE Bots 及 LINE Messaging API 集成的参考资料。

工作流

构建

1. 阅读 references/api-common.md（速率限制、向前兼容性、错误处理）
2. 加载与正在实现的功能相关的参考资料
3. 对于架构或设计选择，请查阅 references/experts.md，获取方向性指导
4. 按照参考资料中的规范和约束编写代码

审查 / 调试

1. 阅读 references/api-common.md（速率限制、错误代码）
2. 加载与正在审查的代码相关的参考资料
3. 根据规范交叉检查代码（大小限制、令牌过期时间、计数规则、必填字段）
4. 对于设计模式方面的问题，请查阅 references/experts.md
5. 报告违规之处，并注明具体约束

环境变量

LINE_CHANNEL_ACCESS_TOKEN=Bot access token
LINE_CHANNEL_SECRET=Channel secret (webhook signature verification)

通用规范

**编写任何 LINE bot 代码前，请先阅读 references/api-common.md。**其中包含影响所有 API 交互的规则：向前兼容性（不要使用严格的架构——LINE 可能会在不通知的情况下添加字段）、速率限制、错误处理、重试策略和日志记录建议。

Webhook

• 验证：x-line-signature 标头（HMAC-SHA256，base64，密钥 = Channel Secret）
• 请求体：{"destination": "U...", "events": [...]}
• Bot 服务必须返回 200

签名验证（伪代码）

channel_secret = ENV['LINE_CHANNEL_SECRET']
signature = request.headers['x-line-signature']
body = request.body   # raw bytes, do NOT parse/reformat before verification

digest = HMAC_SHA256(key = channel_secret, message = body)
expected = Base64.encode(digest)

if signature != expected:
    return 403  # reject — not from LINE

events = JSON.parse(body)['events']
for event in events:
    handle(event)
return 200

• 验证前切勿反序列化或重新格式化请求体
• 仅使用 UTF-8 编码
• 官方 SDK 会自动处理——请尽可能使用

完整的事件类型、属性和 webhook 设置 → references/webhook-events.md

消息发送

所有请求都需要 Authorization: Bearer {channel access token}：

模式	端点	用途
回复	POST /v2/bot/message/reply	回复用户（需要一次性 replyToken）
推送	POST /v2/bot/message/push	随时向特定用户/群组发送消息
多播	POST /v2/bot/message/multicast	向多个用户发送消息（最多 500 人）
广播	POST /v2/bot/message/broadcast	向所有好友发送消息

• 每个请求最多发送 5 条消息
• 域名：api.line.me（常规）/ api-data.line.me（内容上传）

消息对象 → references/message-objects.md 完整的发送 API（Narrowcast、统计、验证等）→ references/message-sending.md

Flex Message

三层结构：

Container (Bubble / Carousel)
  └── Block (Header / Hero / Body / Footer)
       └── Component (Box / Button / Image / Video / Icon / Text / Span / Separator)

最简 Flex Message：

{
  "type": "flex", "altText": "Notification",
  "contents": {
    "type": "bubble",
    "body": {
      "type": "box", "layout": "vertical",
      "contents": [{"type": "text", "text": "Hello Flex!", "weight": "bold"}]
    }
  }
}

完整的组件规范、布局和视频说明 → references/flex-message.md 官方 Flex Message Simulator 示例 → assets/examples/

参考索引

文件	主题
references/api-common.md	请先阅读。 速率限制、错误处理、向前兼容性
references/webhook-events.md	Webhook 事件类型和 JSON 结构
references/message-objects.md	消息对象、快捷回复、发送者自定义
references/action-objects.md	操作对象（postback、URI、datetimepicker 等）
references/message-sending.md	回复/推送/多播/窄播/广播、统计信息
references/flex-message.md	Flex Message 组件、布局、样式
references/rich-menu.md	Rich Menu 的增删改查、标签页切换、显示优先级
references/user.md	用户资料、关注者 ID、账号关联
references/group-chat.md	群组/聊天室消息和成员 API
references/audience.md	受众管理（创建/添加/获取/删除）
references/insights.md	投递、关注者和互动洞察
references/channel-token.md	Channel 访问令牌生命周期
references/coupon.md	优惠券的增删改查、奖励类型、发送
references/url-schemes.md	用于深度链接的 LINE URL 方案
references/experts.md	专家领域路由和 17 个专家资料
assets/examples/	Flex Message JSON 示例（11 个展示案例）

SDK

官方 SDK：Python | Node.js | Go | Java | PHP | Ruby

其他语言：使用 LINE OpenAPI 规范和 OpenAPI Generator。