LINEミニアプリ APIリファレンス
サービスメッセージ
この機能は、認証済ミニアプリでのみ利用できます。未認証ミニアプリの場合、開発用の内部チャネルではテストできますが、公開用の内部チャネルでは利用できません。
サービスメッセージAPIを使用すると、サービスからLINEミニアプリのユーザーに、サービスメッセージを送信できます。
サービスメッセージを送信するには、サービス通知トークンとテンプレートが必要です。
サービス通知トークンを発行する
サービス通知トークンを発行します。サービス通知トークンを使用すると、紐づけられたユーザーに対してサービスメッセージを送信できます。
サービス通知トークンの特徴は以下のとおりです。
- サービス通知トークンは、発行から1年間（31,536,000秒間）有効です。有効期限が切れるまでに、最大5回サービスメッセージを送信できます。
- サービス通知トークンを使用すると、有効期限が切れておらず、残りの送信可能回数が0でない場合は、サービス通知トークンの値が更新されます。ユーザーに対して、後続のサービスメッセージを送信する場合は、更新後のサービス通知トークンを保存してください。
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 | 以下のいずれかです。
|
| 401 Unauthorized | 以下のいずれか、または両方です。
|
| 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>型で指定します。
指定できるスコープについては、「取得できる共通プロフィールのスコープと戻り値」を参照してください。
戻り値
なし