LINEミニアプリ APIリファレンス

# LINEミニアプリ APIリファレンス

# サービスメッセージ

認証済ミニアプリでのみ利用できます

この機能は、認証済ミニアプリでのみ利用できます。未認証ミニアプリの場合、開発用の内部チャネルではテストできますが、公開用の内部チャネルでは利用できません。

サービスメッセージAPIを使用すると、サービスからLINEミニアプリのユーザーに、サービスメッセージを送信できます。

サービスメッセージを送信するには、サービス通知トークンとテンプレートが必要です。

# サービス通知トークンを発行する

サービス通知トークンを発行します。サービス通知トークンを使用すると、紐づけられたユーザーに対してサービスメッセージを送信できます。

サービス通知トークンの特徴は以下のとおりです。

  • サービス通知トークンは、発行から1年間（31,536,000秒間）有効です。有効期限が切れるまでに、最大5回サービスメッセージを送信できます。
  • サービス通知トークンを使用すると、有効期限が切れておらず、残りの送信可能回数が0でない場合は、サービス通知トークンの値が更新されます。ユーザーに対して、後続のサービスメッセージを送信する場合は、更新後のサービス通知トークンを保存してください。
1つのアクセストークンで複数のサービス通知トークンを発行しないでください

liff.getAccessToken()で取得したアクセストークン（LIFFのアクセストークン）を再利用して、複数のサービス通知トークンを発行することは許可されていません。

LIFFのアクセストークン1つにつき、発行できるサービス通知トークンは1つだけです。

注意

サービス通知トークンは、一人のユーザーに紐づいています。あるユーザーに紐づいたサービス通知トークンを利用して、ほかのユーザーにサービスメッセージを送信することはできません。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/message/v3/notifier/token

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}
詳しくは、「チャネルアクセストークン」を参照してください。

ステートレスチャネルアクセストークンの使用を推奨します

LINEミニアプリチャネルでは、長期のチャネルアクセストークンおよび、任意の有効期間を指定できるチャネルアクセストークン（チャネルアクセストークンv2.1）は使用できません。

LINEミニアプリの開発では、ステートレスチャネルアクセストークンまたは短期のチャネルアクセストークンを使用できます。このうち、ステートレスチャネルアクセストークンの使用を推奨します。ステートレスチャネルアクセストークンは、発行数に制限がないため、アプリケーション側でトークンのライフサイクルを管理する必要がありません。

# リクエストボディ

liffAccessToken

String

必須

liff.getAccessToken()で取得したアクセストークン（LIFFのアクセストークン）

# レスポンス

ステータスコード200と以下の情報を含むJSONオブジェクトを返します。

notificationToken

String

サービス通知トークン

expiresIn

Number

サービス通知トークンの有効期限が切れるまでの秒数。サービス通知トークンは、発行から1年間（31,536,000秒間）有効です。

remainingCount

Number

発行されたサービス通知トークンで、サービスメッセージを送信できる回数

sessionId

String

セッションID。詳しくは、「サービスメッセージを送信する」を参照してください。

レスポンスの例

# エラーレスポンス

以下のいずれかのステータスコードとエラーメッセージを返します。

ステータスコード 説明
400 Bad request 以下のいずれかです。
  • リクエストボディに問題があります。
  • liffAccessTokenプロパティに指定したLIFFのアクセストークンを使用して、サービス通知トークンの発行が短時間に連続してリクエストされました。
401 Unauthorized 以下のいずれか、または両方です。
  • 有効なチャネルアクセストークンが指定されていません。
  • 有効なLIFFのアクセストークンが指定されていません。
    • ユーザーがLIFFアプリを閉じると、有効期限が切れていなくてもアクセストークンは無効化されます。
403 Forbidden このチャネルには、サービス通知トークンを発行する許可が与えられていません。
500 Internal Server Error 内部サーバーのエラーです。

エラーレスポンスの例

# サービスメッセージを送る

サービス通知トークンで指定されたユーザーに、サービスメッセージを送信します。

サービスメッセージを送信すると、有効期限が切れておらず、残りの送信可能回数が0でない場合は、サービス通知トークンの値が更新されます。ユーザーに対して、後続のサービスメッセージを送信する予定がある場合は、更新後のサービス通知トークンを保存してください。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/message/v3/notifier/send

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}
詳しくは、『LINEプラットフォームの基礎知識』の「チャネルアクセストークン」を参照してください。

ステートレスチャネルアクセストークンの使用を推奨します

LINEミニアプリチャネルでは、長期のチャネルアクセストークンおよび、任意の有効期間を指定できるチャネルアクセストークン（チャネルアクセストークンv2.1）は使用できません。

LINEミニアプリの開発では、ステートレスチャネルアクセストークンまたは短期のチャネルアクセストークンを使用できます。このうち、ステートレスチャネルアクセストークンの使用を推奨します。ステートレスチャネルアクセストークンは、発行数に制限がないため、アプリケーション側でトークンのライフサイクルを管理する必要がありません。

# クエリパラメータ

target

必須

service

# リクエストボディ

templateName

String

必須

サービスメッセージに使用する、事前登録済みテンプレートの名前。BCP 47言語タグを末尾に追加してください。
フォーマット：{template name}_{BCP 47 language tag}
最大文字数：30

注意

サービスメッセージでサポートしている言語と言語タグは、以下のとおりです。

  • アラビア語：ar
  • 中国語（簡体字）：zh-CN
  • 中国語（繁体字）：zh-TW
  • 英語：en
  • フランス語：fr
  • ドイツ語：de
  • インドネシア語：id
  • イタリア語：it
  • 日本語：ja
  • 韓国語：ko
  • マレー語：ms
  • ポルトガル語（ブラジル）：pt-BR
  • ポルトガル語（ポルトガル）：pt-PT
  • ロシア語：ru
  • スペイン語（スペイン）：es-ES
  • タイ語：th
  • トルコ語：tr
  • ベトナム語：vi

params

object

必須

テンプレート変数と値のペアを指定するJSONオブジェクト。
テンプレートにテンプレート変数がない場合は、空のJSONオブジェクト（{ }）を指定します。
テンプレート変数は、テンプレートごとに定義されています。必須の要素にテンプレート変数が含まれる場合は、必ずテンプレート変数と値のペアを指定してください。
詳しくは、「サービスメッセージのテンプレートを追加する」を参照してください。

notificationToken

String

必須

サービス通知トークン

# レスポンス

ステータスコード200と以下の情報を含むJSONオブジェクトを返します。

notificationToken

String

更新後のサービス通知トークン。このサービス通知トークンを使用して、後続のサービスメッセージを送信します。

expiresIn

Number

更新後のサービス通知トークンの有効期限が切れるまでの秒数

remainingCount

Number

更新後のサービス通知トークンで、後続のサービスメッセージを送信できる回数

sessionId

String

セッションID。詳しくは、「サービスメッセージを送信する」を参照してください。

注意

expiresInおよびremainingCountの値が0の場合は、サービスメッセージは送信されたが、サービス通知トークンが更新できなかったことを示します。

レスポンスの例

# エラーレスポンス

以下のいずれかのステータスコードとエラーメッセージを返します。

ステータスコード 説明
400 Bad request 以下のいずれかです。
  • リクエストボディに問題があります。
  • サービスメッセージ送信対象のユーザーが存在しません。
401 Unauthorized 以下のいずれか、または両方です。
  • 有効なチャネルアクセストークンが指定されていません。
  • 有効なサービス通知トークンが指定されていません。
403 Forbidden 以下のいずれかです。
  • このチャネルには、サービスメッセージを送信する許可が与えられていません。
  • 指定されたテンプレートが見つかりません。
500 Internal Server Error 内部サーバーのエラーです。

エラーレスポンスの例

# 共通プロフィールのクイック入力

認証済ミニアプリでのみ利用できます

共通プロフィールのクイック入力を利用するには、LINEミニアプリが認証済みであり、かつ利用申請が完了している必要があります。

クイック入力とは、LINEミニアプリ上で［自動入力］をタップすることで、必要なプロフィール情報が自動で入力される機能です。ユーザーがアカウントセンターで設定した共通プロフィールの情報が、LINEミニアプリで簡単に利用できます。詳しくは、「共通プロフィールのクイック入力の概要」を参照してください。

# liff.$commonProfile.get()

ユーザーがアカウントセンターで設定している共通プロフィールの情報を取得します。

liff.$commonProfile.get()メソッドを実行すると、ユーザーがプロフィールの情報を確認するためのモーダルが表示されます。表示されたモーダルでプロフィールを確認後、ユーザーが［自動で入力する］をタップすると、共通プロフィールの情報を取得できます。

モーダルの表示例：

例

# 構文

liff.$commonProfile.get(scopes, options);

# 引数

scopes

Array of strings

必須

取得したい共通プロフィールのスコープを指定します。

scopesに指定できる値については、「取得できる共通プロフィールのスコープと戻り値」を参照してください。

options

Object

任意

共通プロフィールの情報を取得するときのオプション

options.formatOptions

Object

任意

情報の形式に関するオプション。scopesプロパティで指定した各スコープに対して、formatOptionsオブジェクトを指定します。

キーには、オプションを設定したいスコープをキャメルケース形式で指定します。たとえば、スコープがgiven-nameのとき、キーはgivenNameになります。

# formatOptionsオブジェクト

excludeEmojis

Boolean

任意

文字列内の絵文字を削除するかどうか。デフォルトはtrueです。以下のスコープにのみ指定できます。

  • givenName
  • familyName

excludeNonJp

Boolean

任意

12桁以上の電話番号を排除するかどうか。デフォルトはtrueです。trueの場合、電話番号が12桁以上のときは、空文字とエラー情報を返します。以下のスコープにのみ指定できます。

  • tel

digitsOnly

Boolean

任意

数字以外の郵便番号を排除するかどうか。デフォルトはtrueです。trueの場合、郵便番号に数字以外が含まれているときは、空文字とエラー情報を返します。以下のスコープにのみ指定できます。

  • postalCode

例

# 戻り値

{ data: Partial<CommonProfile>, error: Partial<CommonProfileError>}型のPromiseオブジェクトが返されます。

Promiseがresolveされると、dataプロパティにユーザーの共通プロフィール情報を含むPartial<CommonProfile>型、errorプロパティにエラー情報を含むPartial<CommonProfileError>型のオブジェクトが渡されます。

次のような場合、dataが持つプロパティはundefinedもしくはnullになります。

  • undefinedになるケース
    • 引数のscopesで対象の項目を指定していない場合
    • 引数のscopesで対象の項目を指定したが、ユーザーがその項目の権限を許可していない場合
  • nullになるケース
    • ユーザーが共通プロフィールで対象の項目に値を設定していない場合
    • 共通プロフィールで対象の項目を取得する時にエラーが発生した場合

指定したスコープに応じて取得できるプロパティの値については、「取得できる共通プロフィールのスコープと戻り値」を参照してください。

Partial<CommonProfile>型のオブジェクトの例

Partial<CommonProfileError>型のオブジェクトの例

# エラーレスポンス

Promiseがrejectされたときは、LiffErrorが渡されます。

プラグインを正しくインストールせずにAPIを呼んだ場合の例

LIFFブラウザ以外でAPIが呼ばれた場合の例

# liff.$commonProfile.getDummy()

共通プロフィールのダミーデータを取得します。10種類のダミーデータが用意されており、caseIdによって取得するダミーデータを指定できます。

liff.$commonProfile.getDummy()メソッドを実行すると、プロフィールの情報を確認するためのモーダルが表示されます。［自動で入力する］をタップすると、共通プロフィールのダミーデータを取得できます。

モーダルの表示例：

例

# 構文

liff.$commonProfile.getDummy(scopes, options, caseId);

# 引数

scopes

Array of strings

必須

取得したい共通プロフィールのスコープを指定します。

scopesに指定できる値については、「取得できる共通プロフィールのスコープと戻り値」を参照してください。

options

Object

任意

共通プロフィールの情報を取得するときのオプション

options.formatOptions

Object

任意

情報の形式に関するオプション。scopesプロパティで指定した各スコープに対して、formatOptionsオブジェクトを指定します。

キーには、オプションを設定したいスコープをキャメルケース形式で指定します。たとえば、スコープがgiven-nameのとき、キーはgivenNameになります。

caseId

number

必須

取得したいダミーデータのIDを指定します。IDが1から10までのダミーデータが用意されています。

caseIdごとのダミーデータについては、「取得できる共通プロフィールのダミーデータ」を参照してください。

# 戻り値

{ data: Partial<CommonProfile>, error: Partial<CommonProfileError>}型のPromiseオブジェクトが返されます。

Promiseがresolveされると、dataプロパティにダミーデータを含むPartial<CommonProfile>型、errorプロパティにエラー情報を含むPartial<CommonProfileError>型のオブジェクトが渡されます。

次のような場合、dataが持つプロパティはundefinedもしくはnullになります。

  • undefinedになるケース
    • 引数のscopesで対象の項目を指定していない場合
  • nullになるケース
    • ダミーデータで対象の項目に値が設定されていない場合

指定したIDに応じて取得できるダミーデータについては、「取得できる共通プロフィールのダミーデータ」を参照してください。

Partial<CommonProfile>型のオブジェクトの例

Partial<CommonProfileError>型のオブジェクトの例

# エラーレスポンス

Promiseがrejectされたときは、LiffErrorが渡されます。

プラグインを正しくインストールせずにAPIを呼んだ場合の例

LIFFブラウザ以外でAPIが呼ばれた場合の例

# liff.$commonProfile.fill()

取得した共通プロフィールの情報をフォームに自動入力します。それぞれのプロフィール情報とフォームの紐づけには、data-liff-autocomplete属性を用います。

スコープと一致しないフォームへの自動入力

liff.$commonProfile.fill()による自動入力は、フォームのdata-liff-autocomplete属性を用いて行います。このとき、フォームのdata-liff-autocomplete属性に指定する値は、取得したプロフィール情報のスコープ（family-name、tel、bday-yearなど）と一致している必要があります。

たとえば、誕生年（bday-year）、誕生月（bday-month）、誕生日（bday-day）の情報をそれぞれ取得した後、20110623のような形式に加工した上でフォームに自動入力させたい場合は、liff.$commonProfile.fill()の代わりに、document.getElementById().valueやdocument.querySelector().valueを用いることができます。

取得した姓、電話番号、性別をそのまま自動入力する例

取得した共通プロフィール情報の形式を一部変更して自動入力する場合

# 構文

liff.$commonProfile.fill(profile);

# 引数

profile

Partial<CommonProfile>

必須

フォームに自動入力させるプロフィール情報を、Partial<CommonProfile>型で指定します。

指定できるスコープについては、「取得できる共通プロフィールのスコープと戻り値」を参照してください。

# 戻り値

なし