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サイトから取得できる。

また、APIHTTPS経由でアクセスする。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リファレンス

https://devdocs.line.me/ja/

構成コンポーネント
  • 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)

  1. リクエストヘッダの署名検証
  2. 受信イベントごとの処理
  3. レスポンス返却
制約
  • WebhookのHTTPS POSTに対しては、常に200 OKを返す
  • WebhookのHTTP POSTリクエストが何れか失敗しても、リクエストは再送されない
署名検証

リクエスト送信元がLINEであることを確認するために、署名検証を行わなくてはいけない。

各リクエストの「X-Line-Signature」ヘッダと
リクエストボディとChannel secretから計算したものが同じであることを必ず検証する。

この部分はSDKでメソッドが提供されているので、それを呼ぶだけで実現できる。

Webhook event object

LINE Platformで発生したイベントを表すJSONオブジェクトで以下がある。

  • Common Fields
    全イベント共通で含まれるフィールドで、以下が含まれる
  1. type
    typeでイベント種別を識別できる。以下がある。
    • message
      メッセージが送信されると発生
    • follow
      イベント送信元に友だち追加 or ブロック解除されると発生
    • unfollow
      イベント送信元にブロックされると発生
    • join
      イベントの送信元グループまたはトークルームに参加すると発生
    • leave
      イベントの送信元グループから退出させられると発生、自分で退出した場合は発生しない
    • postback
      イベントの送信元が、template messageに付加されたポストバックアクションを実行すると発生
      ※選択肢から選んだ、などが起きた場合。このイベントへは返信可能。
    • Beacon event
      イベント送信元のユーザがLINE Beaconデバイスの受信圏内に出入りした場合に発生
      ※一部の企業・ユーザに限定開放しているらしく、今後オープン化していくとのこと。このイベントへは返信可能。
      >> 色々応用が利きそうなので、将来これだけで何かできるかも。
  2. timestamp
  3. Source user
  4. Source group
  5. 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以降で対応
    以下のテンプレートがある。
  1. Buttons
    画像、タイトル、テキストと、複数のアクションボタンを組み合わせたテンプレートメッセージ
    Buttonsテンプレートには表示上の高さ制限があり、text表示領域の高さが一定以上になると領域の下部がカットされる。 このため、文字幅によっては、文字数制限範囲内であってもテキストが全文表示されない場合がある。
  2. Confirm
    2つのアクションボタンを提示するテンプレートメッセージ
  3. Carousel
    Buttonsを複数並べて提示できるテンプレートメッセージ
    > 画像の有無、titleの有無、アクションの数は、全てのカラムで統一する必要がある

また、テンプレートメッセージに付加するアクションには以下がある。

  1. Postback action
    dataフィールドで指定された文字列がpostback eventとしてwebhookで通知される
    また、textフィールドを指定した場合は、その内容がユーザの発言として同時に送信される
  2. Message action
    textフィールドに指定した文字列が、その内容がユーザの発言として同時に送信される
  3. URI action
    uriで指定されたURIを開く
    uriには、http、https、telを指定可能

Content

ユーザから送信された画像、動画、音声のバイナリデータにアクセスするAPI
コンテンツはメッセージが送信されてからある期間経過した時点で自動的に削除される。保存される期間についての保証もない。

Profile

ユーザのプロフィール情報を取得するAPI
以下が取れる

  • 表示名
  • ユーザ識別子(送信元IDなどにセットされるもの)
  • 画像URL
  • ステータスメッセージ(設定で、ひとこと入れられるもの)

Leave

グループまたはトークルームから退出するAPI

実装について

基本的にSDKでメソッドが提供されているなので、そちらを使いながら実装すればOK。
実際に使って実装したが、難しくなかった。

[Github]

GitHub - line/line-bot-sdk-php: SDK of the LINE Messaging API for PHP

[PHP APIリファレンス]

line-bot-sdk-php

[LaravelでBot作るときの雛形を作りました]

qiita.com