messaging-api
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLINE Messaging API
LINE Messaging API
Do not answer LINE API questions from memory — LINE updates APIs frequently and training data is unreliable. Always consult the references below.
Reference for building, reviewing, and debugging LINE Bots and LINE Messaging API integrations.
请勿凭记忆回答LINE API相关问题——LINE会频繁更新API，训练数据并不可靠。请务必参考下方文档。
本文档是构建、评审和调试LINE Bot与LINE Messaging API集成的参考指南。
Workflow
工作流程
Build
构建
- Read references/api-common.md (rate limits, forward compatibility, error handling)
- Load the relevant reference for the feature being implemented
- For architecture or design choices, consult references/experts.md for directional guidance
- Write code following specs and constraints from references
- 阅读 references/api-common.md（速率限制、向前兼容性、错误处理）
- 加载与待实现功能相关的参考文档
- 若涉及架构或设计选择，请参考 references/experts.md 获取方向性指导
- 遵循参考文档中的规范和约束编写代码
Review / Debug
评审 / 调试
- Read references/api-common.md (rate limits, error codes)
- Load relevant references for the code being reviewed
- Cross-check code against specs (size limits, token expiry, counting rules, required fields)
- For design pattern concerns, consult references/experts.md
- Report violations with reference to specific constraints
- 阅读 references/api-common.md（速率限制、错误代码）
- 加载与待评审代码相关的参考文档
- 对照规范交叉检查代码（大小限制、令牌过期、计数规则、必填字段）
- 若涉及设计模式问题，请参考 references/experts.md
- 结合具体约束报告违规问题
Environment Variables
环境变量
LINE_CHANNEL_ACCESS_TOKEN=Bot access token
LINE_CHANNEL_SECRET=Channel secret (webhook signature verification)LINE_CHANNEL_ACCESS_TOKEN=机器人访问令牌
LINE_CHANNEL_SECRET=频道密钥（用于webhook签名验证）Common Specifications
通用规范
Read references/api-common.md before writing any LINE bot code. Contains rules that affect all API interactions: forward compatibility (don't use strict schemas — LINE adds fields without notice), rate limits, error handling, retry policy, and logging recommendations.
在编写任何LINE机器人代码前，请先阅读 references/api-common.md。其中包含影响所有API交互的规则：向前兼容性（请勿使用严格模式——LINE会在未通知的情况下新增字段）、速率限制、错误处理、重试策略以及日志记录建议。
Webhook
Webhook
- Verification: header (HMAC-SHA256, base64, key = Channel Secret)
x-line-signature - Body:
{"destination": "U...", "events": [...]} - Bot server must return
200
- 验证：请求头（采用HMAC-SHA256算法，base64编码，密钥=频道密钥）
x-line-signature - 请求体：
{"destination": "U...", "events": [...]} - 机器人服务器必须返回 状态码
200
Signature Verification (pseudocode)
签名验证（伪代码）
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- Never deserialize or re-format the body before verification
- Use UTF-8 encoding exclusively
- Official SDKs handle this automatically — use them when possible
Full event types, properties, and webhook settings → references/webhook-events.md
channel_secret = ENV['LINE_CHANNEL_SECRET']
signature = request.headers['x-line-signature']
body = request.body # 原始字节，验证前请勿解析/格式化
digest = HMAC_SHA256(key = channel_secret, message = body)
expected = Base64.encode(digest)
if signature != expected:
return 403 # 拒绝请求——并非来自LINE
events = JSON.parse(body)['events']
for event in events:
handle(event)
return 200- 验证前切勿反序列化或格式化请求体
- 仅使用UTF-8编码
- 官方SDK会自动处理此验证——尽可能使用官方SDK
完整的事件类型、属性及webhook设置 → references/webhook-events.md
Message Sending
消息发送
All require :
Authorization: Bearer {channel access token}| Mode | Endpoint | Purpose |
|---|---|---|
| Reply | | Reply to user (requires one-time replyToken) |
| Push | | Send to a specific user/group at any time |
| Multicast | | Send to multiple users (max 500) |
| Broadcast | | Send to all friends |
- Max 5 messages per request
- Domain: (general) /
api.line.me(content upload)api-data.line.me
Message objects → references/message-objects.md
Full sending API (Narrowcast, statistics, validation, etc.) → references/message-sending.md
所有接口均需携带 请求头：
Authorization: Bearer {channel access token}| 模式 | 接口地址 | 用途 |
|---|---|---|
| Reply | | 回复用户（需使用一次性replyToken） |
| Push | | 随时向特定用户/群组发送消息 |
| Multicast | | 向多个用户发送消息（最多500人） |
| Broadcast | | 向所有好友发送消息 |
- 每次请求最多发送5条消息
- 域名：（通用接口）/
api.line.me（内容上传接口）api-data.line.me
消息对象详情 → references/message-objects.md
完整发送API（Narrowcast、统计、验证等）→ references/message-sending.md
Flex Message
Flex Message
Three-layer structure:
Container (Bubble / Carousel)
└── Block (Header / Hero / Body / Footer)
└── Component (Box / Button / Image / Video / Icon / Text / Span / Separator)Minimal Flex Message:
json
{
"type": "flex", "altText": "Notification",
"contents": {
"type": "bubble",
"body": {
"type": "box", "layout": "vertical",
"contents": [{"type": "text", "text": "Hello Flex!", "weight": "bold"}]
}
}
}Full component specs, layout, video → references/flex-message.md
Official Flex Message Simulator examples →
assets/examples/三层结构：
Container（Bubble / Carousel）
└── Block（Header / Hero / Body / Footer）
└── Component（Box / Button / Image / Video / Icon / Text / Span / Separator）最简Flex Message示例：
json
{
"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模拟器示例 →
assets/examples/Reference Index
参考文档索引
| File | Topic |
|---|---|
| references/api-common.md | Read first. Rate limits, error handling, forward compatibility |
| references/webhook-events.md | Webhook event types and JSON structure |
| references/message-objects.md | Message objects, Quick Reply, sender customization |
| references/action-objects.md | Action objects (postback, URI, datetimepicker, etc.) |
| references/message-sending.md | Reply/Push/Multicast/Narrowcast/Broadcast, statistics |
| references/flex-message.md | Flex Message components, layout, styles |
| references/rich-menu.md | Rich Menu CRUD, tab switching, display priority |
| references/user.md | User profile, follower IDs, account link |
| references/group-chat.md | Group/Room messaging and member APIs |
| references/audience.md | Audience management (create/add/get/delete) |
| references/insights.md | Delivery, follower, and interaction insights |
| references/channel-token.md | Channel access token lifecycle |
| references/coupon.md | Coupon CRUD, reward types, sending |
| references/url-schemes.md | LINE URL schemes for deep linking |
| references/experts.md | Expert domain routing and 17 specialist profiles |
| assets/examples/ | Flex Message JSON examples (11 showcases) |
| 文件 | 主题 |
|---|---|
| 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 | Reply/Push/Multicast/Narrowcast/Broadcast、统计数据 |
| 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 | 频道访问令牌生命周期 |
| references/coupon.md | 优惠券增删改查、奖励类型、发送 |
| references/url-schemes.md | 用于深度链接的LINE URL schemes |
| references/experts.md | 专家领域路由及17位专家档案 |
| assets/examples/ | Flex Message JSON示例（11个展示案例） |