LINE Notify

Log in

LINE Notify API Document

  • 2023/11/17 Updated
    imageThumbnail/imageFullsizeのHTTPサポートを削除しました (HTTPSをご利用ください)
  • 2021-06-14 Updated
    トークン(連携サービス)の発行数の制限に関する記述を追加
  • 2019-06-25 Updated
    imageFullsizeに関する記述を修正
  • 2019-06-11 Updated
    notificationDisabledに関する記述を追加
  • 2016-11-08 Updated
    Stickerに関する記述を追加
  • 2016-10-24 Updated
    画像uploadに関する記述を追加
  • 2016-09-29 Updated
    初版

API 全体の流れと、実装の必要な箇所について

API は OAuth2 による認証と、LINEへの通知用のものとで構成されます。全体として以下のような流れになります。

  1. ユーザ：LINEの通知を設定しようとする
  2. 連携サービス： OAuth2 authorization endpoint へのリダイレクトを行う
  3. LINE：通知先チャンネルの選択及びユーザへの認可確認を行い、連携サービスにリダイレクト
  4. 連携サービス：リダイレクト時に付与されたパラメータを用いて OAuth2 token endpoint にアクセスし、アクセストークンを取得する
  5. 連携サービス：アクセストークンを保存する
  6. (通知時) 連携サービス：保存したアクセストークンを用いて通知APIをコールする
  7. (通知設定確認時) 連携サービス：連携状態確認APIをコールしてユーザに連携状態を表示する
  8. (通知解除時) 連携サービス：連携解除APIをコールする

以上の流れのうち連携サービスで必要と思われる実装箇所は以下の通りです

  • OAuth2 のアクセストークンと、ユーザを関連づけて保存する部分
  • 通知のタイミングで通知APIを呼ぶ部分
  • (連携状態を確認するページがある場合) 連携状態APIをコールして連携状態を表示する部分
  • (連携サービス側から通知解除を行う場合) 通知解除APIをコールする部分

通知設定確認や通知解除の機能はこちら側のウェブページからも提供しますので、APIでの実装は必須ではありません。

認証系

概要：OAuth2 (https://tools.ietf.org/html/rfc6749) に準拠したプロバイダになります。認証方法は authorization_code です。ここで得られるアクセストークンは、通知サービスのみで利用可能です。

認証系 API のエンドポイントのホスト名は notify-bot.line.me になります。

GET https://notify-bot.line.me/oauth/authorize

OAuth2 における authorization endpoint URI です。

リクエスト方法

リクエストメソッド/ヘッダ 値
Method GET

リクエストパラメータ

受けつけるパラメータは以下の通りです。

パラメータ名 必須 型 説明
response_type 必須 固定値 "code" を指定します
client_id 必須 string 発行した OAuth のクライアントIDを指定します
redirect_uri 必須 uri

登録したリダイレクトURIを指定します。

code パラメータ漏洩を防ぐため、リダイレクトURIは https とすることをお勧めします。
scope 必須 固定値 "notify" を指定します
state 必須 string

CSRF 攻撃に対応するための任意のトークンを指定します
典型的にはユーザのセッションIDから生成されるハッシュ値などを指定し、redirect_uri アクセス時に state パラメータを検証することでCSRF攻撃を防ぎます。

LINE Notify ではウェブアプリケーション連携を想定しているため state パラメータを必須とさせて頂いています。
response_mode 任意 string

"form_post" を指定すると、リダイレクトに代わり form post によって redirect_uri への POST リクエストとなります
拡張仕様: https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html

これはレスポンスの code パラメータが特定環境で漏洩することを防ぐためであるため、指定することをお勧めします

参照：http://arstechnica.com/security/2016/07/new-attack-that-cripples-https-crypto-works-on-macs-windows-and-linux/

レスポンス

成功時には以下のパラメータをつけて、指定された redirect_uri にリダイレクトまたはフォームによってPOSTされます。

パラメータ名 型 説明
code string access token 取得用のコードです
state string 指定された state パラメータがそのまま渡されます

失敗時には以下のパラメータをつけて、指定された redirect_uri にリダイレクトされます。

パラメータ名 型 説明
error string OAuth2 https://tools.ietf.org/html/rfc6749#section-4.1.2 で定義されるエラーコードが指定されます
error_description string OAuth2 https://tools.ietf.org/html/rfc6749#section-4.1.2 で定義される通り、クライアント開発者向けにエラー内容についての追加の説明を返します。未定義または空文字列である可能性があります。
state string 指定された state パラメータがそのまま渡されます

POST https://notify-bot.line.me/oauth/token

OAuth2 の token endpoint になります。

リクエスト方法

リクエストメソッド/ヘッダ 値
Method POST
Content-Type application/x-www-form-urlencoded

リクエストパラメータ

受けつけるパラメータは以下の通りです。

パラメータ名 必須 型 説明
grant_type 必須 固定値 "authorization_code" を指定します
code 必須 string リダイレクト時に付与された code パラメータの値を指定します
redirect_uri 必須 uri authorization endpoint API に指定した redirect_uri を指定します
client_id 必須 string 発行した OAuth のクライアントIDを指定します
client_secret 必須 string 発行した OAuth のクライアントシークレットを指定します

レスポンス

レスポンスヘッダ 値
Status

200: 成功時

400: リクエストが不正

上記以外: 時間をおいて再試行するか処理を中断
Content-Type application/json

レスポンス本文

レスポンス本文はJSONのobject型になります。

name type value description
access_token string 認証用アクセストークンです。後述の通知系APIを呼ぶ際に使用します
このアクセストークンに有効期限はありません。

通知系

概要：LINE への通知のためのAPIです。全て前もって OAuth 認証が必須となります。連携状況確認・実際の通知・連携の解除ができます。

通知系 API のエンドポイントのホスト名は notify-api.line.me になります。

認証方法

リクエストヘッダに Authorization: Bearer <access_token> を付与してアクセスします。使用したアクセストークンが無効な場合、RFC6750 に基きステータスコード 401 と共に WWW-Authenticate ヘッダを返します。

POST https://notify-api.line.me/api/notify

アクセストークンに関連付けられたユーザ・またはグループに対して通知を送信します。

もしこのAPIの呼び出しでステータスコード 401 がレスポンスされた場合、該当するアクセストークンは LINE Notify 側で無効化 (主にユーザによる無効化) されたことを示します。この場合、連携サービス側でも連携情報を削除してしまってかまいません。

リクエストは application/x-www-form-urlencoded (HTMLのデフォルトのフォームの送信形式と同一です) で、POST メソッドを使用します。

想定するユースケース

連携サービス側で LINE に通知したいイベントが発生したとき

リクエスト方法

リクエストメソッド/ヘッダ 値
Method POST
Content-Type application/x-www-form-urlencoded
OR
multipart/form-data
Authorization Bearer <access_token>

リクエストパラメータ

受けつけるパラメータは以下の通りです。

パラメータ名 必須 型 説明
message 必須 String 最大 1000文字
imageThumbnail 省略可能 HTTPS URL 最大 240×240px / JPEG のみ許可されます
imageFullsize 省略可能 HTTPS URL 最大 2048×2048px / JPEG のみ許可されます
imageFile 省略可能 File

LINE上の画像サーバーにアップロードします。
対応している画像形式は、png, jpegです。

imageThumbnail/imageFullsizeと同時に指定された場合は、imageFileが優先されます。

1時間にuploadできる量に制限があります。
詳しくは、API Rate Limitの項を見てください。
stickerPackageId 省略可能 Number パッケージ識別子。
Stickerの識別子は以下を参照ください。
Sticker一覧
stickerId 省略可能 Number Sticker識別子
notificationDisabled 省略可能 Boolean

true: メッセージ送信時に、ユーザに通知されない。

false: メッセージ送信時に、ユーザに通知される。ただし、LINEで通知をオフにしている場合は通知されません。

デフォルト値は false です。

レスポンス

レスポンスヘッダ 値
status

200: 成功

400: リクエストが不正

401: アクセストークンが無効

500: サーバ内エラーにより失敗

上記以外: 時間をおいて再試行するか処理を中断
Content-Type application/json

レスポンス本文

レスポンス本文はJSONのobject型になります。

name type value description
status number

HTTP ステータスコードに準拠した値

200: 成功時

400: リクエストが不正

401: アクセストークンが無効
message string 人間可読なメッセージです

サンプル

$ curl -X POST -H 'Authorization: Bearer <access_token>' -F 'message=foobar' \ https://notify-api.line.me/api/notify {"status":200,"message":"ok"} $ curl -v -X POST -H 'Authorization: Bearer invalidtoken' -F 'message=foobar' \ https://notify-api.line.me/api/notify {"status":401,"message":"Invalid access token"}

GET https://notify-api.line.me/api/status

連携状態を確認するAPIです。この API を使うと、使用したアクセストークンが有効かどうかを確認することができます。取得できる場合には関連付けられたユーザ・またはグループ名を取得することができます。

連携サービス側の画面で、どのグループへの通知が設定されているかユーザに表示させたい場合に使用します。/api/notify や /api/revoke を呼ぶ前にこのAPIで状態を確認する必要はありません。

もしこのAPIの呼び出しでステータスコード 401 がレスポンスされた場合、該当するアクセストークンは LINE Notify 側で無効化 (主にユーザによる無効化) されたことを示します。この場合、連携サービス側でも連携情報を削除してしまってかまいません。

想定するユースケース

連携サービス側でユーザに連携状態を確認させたいとき

LINE Notify 側でも同様の機能を提供しますので、このAPIへの対応は必須ではありません。

リクエスト方法

リクエストメソッド/ヘッダ 値
Method GET
Authorization Bearer <access_token>

レスポンス

メッセージ本文にJSONとして詳細な情報が記載されます。

レスポンスヘッダ 値
Status

200: 成功時・アクセストークンは有効

401: アクセストークンは無効

上記以外: 時間をおいて再試行するか処理を中断
Content-Type application/json

レスポンス本文

レスポンス本文はJSONのobject型になります。

name type value description
status number

HTTP ステータスコードに準拠した値

200: 成功時・アクセストークンは有効

401: アクセストークンは無効
message string 人間可読なメッセージです
targetType string

通知先がユーザの場合は "USER"

通知先がグループの場合は "GROUP"
target string

通知先がユーザの場合はユーザ名、ただし内部処理中に取得に失敗した場合は null

通知先がグループの場合はグループ名、ただし該当ユーザがグループを既に抜けている場合は null

サンプル

$ curl -H 'Authorization: Bearer <access_token>' \ https://notify-api.line.me/api/status {"status":200,"message":"ok","target":"foobar"} $ curl -H 'Authorization: Bearer invalidtoken' \ https://notify-api.line.me/api/status {"status":401,"message":"Invalid access token"}

POST https://notify-api.line.me/api/revoke

連携サービス側から通知設定を解除するためのAPIです。このAPIを使うと、使用したアクセストークンが直ちに無効化され、以降のAPIアクセスに使用できなくなります。

連携サービス側での連携削除のステップは以下のようになります

  1. /api/revoke を呼び出す
  2. 1 でステータスコード 200 がレスポンスされた場合、このリクエストをもってアクセストークンの無効化が成功したため、連携を削除して終了
  3. 1 でステータスコード 401 がレスポンスされた場合、既にアクセストークンが無効なため、連携を削除して終了
  4. その他のステータスコードがレスポンスされた場合は処理を中断 (のちに再試行など)

想定するユースケース

連携サービス側でユーザに連携状態を解除させたいとき

LINE Notify 側でも同様の機能を提供しますので、このAPIへの対応は必須ではありません。

リクエスト方法

リクエストメソッド/ヘッダ 値
Method POST
Content-Type application/x-www-form-urlencoded
Authorization Bearer <access_token>

リクエストパラメータ

パラメータはありません。

レスポンス

メッセージ本文にJSONとして詳細な情報が記載されます。

レスポンスヘッダ 値
Status

200: 成功時

401: アクセストークンは無効

上記以外: 時間をおいて再試行するか処理を中断
Content-Type application/json

レスポンス本文

レスポンス本文はJSONのobject型になります。

name type value description
status number

HTTP ステータスコードに準拠した値

200: 成功時

401: アクセストークンが無効
message string 人間可読なメッセージです

サンプル

$ curl -X POST -H 'Authorization: Bearer <access_token>' \ https://notify-api.line.me/api/revoke {"status":200,"message":"ok"} $ curl -X POST -H 'Authorization: Bearer invalidtoken' \ https://notify-api.line.me/api/revoke {"status":401,"message":"Invalid access token"}

API Rate Limit

各サービスごとに1時間にAPIをcallできる回数の上限が設定されています。
デフォルトは1000回に設定されています。

上限はaccess tokenごとに設定されています。

API Rate Limitのstatusは、APIの以下のresponse headerで確認することができます。

Header name Description
X-RateLimit-Limit 1時間に可能なAPI callの上限回数
X-RateLimit-Remaining API callが可能な残りの回数
X-RateLimit-ImageLimit 1時間に可能なImage uploadの上限回数
X-RateLimit-ImageRemaining Image uploadが可能な残りの回数
X-RateLimit-Reset

リセットされる時刻 (UTC epoch seconds)

ex:1472195604

トークン(連携サービス)の発行数の制限

1ユーザーあたり100個まで発行することが可能です。