LINE Messaging APIでできることのまとめ
はじめに
仕事でLINE Botを作る機会があり、休みにドキュメントを読み込んだときのメモを晒します。
たしか、Overviewを和訳して糊付けしたヤツです。
なので、これを読むとLINE Messaging APIで何ができるのかほぼ全部判ります。
Overview
https://developers.line.me/messaging-api/overview
アーキテクチャ
LINE Platformに、企業側サーバのURLを記載する必要がある
ユーザーがあなたのアカウントを友達として追加したり、メッセージを送信したりすると、LINEプラットフォームが登録された上記URLにリクエストを送信する。
メッセージ受信とオペレーション
LINE platformから企業側サーバに情報を送信するパターンは以下。
- ユーザがメッセージを送信するメッセージタイプ
- ユーザが(bot)アカウントを友達として追加する操作タイプ
すべてのHTTPリクエストヘッダに署名が含まれているため、
企業側サーバは署名を使用して、リクエストがLINE platformから送信されたことを確認する必要がある。
リクエストがLINE platformから送信されていない場合、リクエストは無効であり、
予期しないイベントが発生する。
Calling APIs
LINEプラットフォームが提供するAPIを使用して、企業サーバーからユーザーに情報を送信することができる。
APIでできること
- 個々のユーザーまたはアカウントを友人として追加したすべてのユーザーにメッセージを送信する
- ユーザーのニックネームを取得する
サーバーはいつでもユーザーにメッセージを送信するためにAPIを呼び出すことができる。
API呼び出しが行われると、以下がリクエストヘッダーに設定され、呼び出しが企業サーバーからのものであることを確認する。
- Channel access token or Channel ID
- Channel secret
- MID for your Channel
これらは、LINE Developersサイトから取得できる。
また、APIはHTTPS経由でアクセスする。HTTPは不可。
Messaging APIでできること
- push messages
Botアカウントを友達に追加しているユーザーに直接メッセージを送信できる。(ユーザーへの単方向)
これをやるためには、followやjoinなどのイベントが発生した場合に、送信元IDを取ってDBなどに保存しておく必要がある。
また、unfollowやleaveが発生した場合は、保存した送信元IDなどは削除しておいた方が良い。
unfollowやleaveした相手にはメッセージは届かないが、こちら側のアプリで余計な処理をしないようにするために入れておくとイイ。 - reply messages
ユーザからのメッセージに返信する。Webhooksを使用してBotアカウントへイベント通知を受ける - Send Imagemap messages using APIs
イメージとリンクを含むリッチコンテンツメッセージを送信する。
Imagemap messagesは、クーポン、特別プロモーション、ニュースアナウンス、ブログ投稿に最適 - Template messages
画像、テキスト、複数のユーザーアクションの選択肢、ボタンなど、さまざまな種類のテンプレートメッセージを送信します - Use your bot in groups and rooms
グループチャット、1対1チャットでユーザーと交流できる
APIリファレンス
構成コンポーネント
- Webhooks
友だち追加情報やユーザから送信されたメッセージをリアルタイムに受信する仕組み - Reply Message
ユーザから受信したメッセージやイベントに対して返信する - Push Message
任意のタイミングでユーザにメッセージを送信するAPI(要PROライセンス) - Multicast
複数のユーザに任意のタイミングでメッセージを送信するAPI(Push Messageの複数版) - Content
ユーザから受信した画像や動画、音声をダウンロードするAPI - Profile
ユーザのプロフィール情報を取得するAPI - Leave
参加したグループやトークルームから退出するAPI
LINE Bot SDK
for PHP(https://github.com/line/line-bot-sdk-php)
Status Codes list
| Status Code | Description |
| 200 | OK |
| 400 | Bad Request. リクエストの仕方に問題あり |
| 401 | Unauthorized. Authorizationヘッダを正しく送信できていない |
| 403 | Forbidden. APIの利用権限がない |
| 429 | Too Many Requests. アクセス頻度が制限を超えた、超えている |
| 500 | Internal Server Error. LINEのサーバ側エラー |
> Sorryコンテンツ返却時のコードを追加してくれると嬉しい
実装の流れ(Webhook)
- リクエストヘッダの署名検証
- 受信イベントごとの処理
- レスポンス返却
制約
署名検証
リクエスト送信元がLINEであることを確認するために、署名検証を行わなくてはいけない。
各リクエストの「X-Line-Signature」ヘッダと
リクエストボディとChannel secretから計算したものが同じであることを必ず検証する。
この部分はSDKでメソッドが提供されているので、それを呼ぶだけで実現できる。
Webhook event object
LINE Platformで発生したイベントを表すJSONオブジェクトで以下がある。
- Common Fields
全イベント共通で含まれるフィールドで、以下が含まれる
- type
typeでイベント種別を識別できる。以下がある。
- message
メッセージが送信されると発生 - follow
イベント送信元に友だち追加 or ブロック解除されると発生 - unfollow
イベント送信元にブロックされると発生 - join
イベントの送信元グループまたはトークルームに参加すると発生 - leave
イベントの送信元グループから退出させられると発生、自分で退出した場合は発生しない - postback
イベントの送信元が、template messageに付加されたポストバックアクションを実行すると発生
※選択肢から選んだ、などが起きた場合。このイベントへは返信可能。 - Beacon event
イベント送信元のユーザがLINE Beaconデバイスの受信圏内に出入りした場合に発生
※一部の企業・ユーザに限定開放しているらしく、今後オープン化していくとのこと。このイベントへは返信可能。
>> 色々応用が利きそうなので、将来これだけで何かできるかも。
- message
- timestamp
- Source user
- Source group
- Source room(複数人トークのこと?)
※1以外は使ったことないので、特に見てないです。
Message event
メッセージが送信されたことを示すEvent Object。
メッセージの種別には以下がある
- text
テキストメッセージ - image
画像、別のAPIでバイナリデータにアクセスする - video
動画、別のAPIでバイナリデータにアクセスする - audio
音声、別のAPIでバイナリデータにアクセスする - location
位置情報(住所、緯度経度) - sticker
スタンプ
Reply message
返信可能なイベントには、replyTokenが含まれているため、これを使用してイベント送信元に返信する。
以下の制約がある
- 一定秒以内に使用しないと無効になる
- トークンの有効期間は1回の返信まで
重たい処理を間に入れると事故りそうなので、そういう場合はどこかにuser_idを保存しておき、push messageで送った方が良い
Push message
企業側サーバから任意のタイミングでメッセージを送信するAPI
Push messageに対応するプランでのみ使用が可能
5件までまとめてメッセージを送信できる
Multicast
基本的にPush messageと同じだが以下が異なる
- 複数のユーザにメッセージを送信可能
- グループ、トークルームにはメッセージを送信できない
Send message object
送信するメッセージのオブジェクト
reply、push、multicastでこの様式を使用する
送信可能なメッセージ種別は以下がある。
- text
2000文字以内のテキストメッセージ - image
オリジナルJPEG画像とプレビューJPEG画像のURL(HTTPSで1000文字以内)を添付する
画像のサイズはそれぞれ以下
オリジナル : 縦横最大1024px、最大1MB
プレビュー : 縦横最大240px、最大1MB
- video
MP4動画とプレビューJPEG画像のURL(HTTPSで1000文字以内)を添付する
動画と画像のサイズはそれぞれ以下
動画 : 長さ1分以下、最大10MB
プレビュー : 縦横最大240px、最大1MB - audio
m4a音声のURL(HTTPSで1000文字以内)を添付する
音声のサイズは
長さ1分以下、最大10MB - location
位置情報を送る - sticker
スタンプを送る、有料のものは識別子が非公開であるため、買って調べるしかない。(そもそもLINE@で勝手に使って良いのかという問題もある) - imagemap
リンク付きの画像コンテンツ。画像全体を1つのリンクとしたり、画像の複数の領域に異なるリンクURLを50個まで指定できる
base URLの末尾にクライアントが要求する解像度を横幅サイズ(px)で付与してくるため、そのリソースパスに画像を置いておく必要がある
リンクで実行できるアクションには以下がある。
- URLアクション
WEBページへ飛ばす - Messageアクション
400文字以内のメッセージを送信する(何に使うのか思いつかない)
タップ領域はImagemap全体の幅を1040pxとして、左上を原点に座標と長さをそれぞれ指定する - template
あらかじめ定義されたレイアウトのテンプレートに、カスタムデータを挿入することによって構築するメッセージ
Template messageは、iOS版およびAndroid版のLINE 6.7.0以降で対応
以下のテンプレートがある。
- Buttons
画像、タイトル、テキストと、複数のアクションボタンを組み合わせたテンプレートメッセージ
Buttonsテンプレートには表示上の高さ制限があり、text表示領域の高さが一定以上になると領域の下部がカットされる。 このため、文字幅によっては、文字数制限範囲内であってもテキストが全文表示されない場合がある。 - Confirm
2つのアクションボタンを提示するテンプレートメッセージ - Carousel
Buttonsを複数並べて提示できるテンプレートメッセージ
> 画像の有無、titleの有無、アクションの数は、全てのカラムで統一する必要がある
また、テンプレートメッセージに付加するアクションには以下がある。
- Postback action
dataフィールドで指定された文字列がpostback eventとしてwebhookで通知される
また、textフィールドを指定した場合は、その内容がユーザの発言として同時に送信される - Message action
textフィールドに指定した文字列が、その内容がユーザの発言として同時に送信される - URI action
uriで指定されたURIを開く
uriには、http、https、telを指定可能
Content
ユーザから送信された画像、動画、音声のバイナリデータにアクセスするAPI
コンテンツはメッセージが送信されてからある期間経過した時点で自動的に削除される。保存される期間についての保証もない。
Profile
ユーザのプロフィール情報を取得するAPI
以下が取れる
- 表示名
- ユーザ識別子(送信元IDなどにセットされるもの)
- 画像URL
- ステータスメッセージ(設定で、ひとこと入れられるもの)
Leave
実装について
基本的にSDKでメソッドが提供されているなので、そちらを使いながら実装すればOK。
実際に使って実装したが、難しくなかった。
[Github]
GitHub - line/line-bot-sdk-php: SDK of the LINE Messaging API for PHP
[LaravelでBot作るときの雛形を作りました]