# LINE MINI App API reference
# Service Messages
This feature is only available for verified MINI Apps. For unverified MINI Apps, you can test the feature on the internal channel for Developing, but you can't use the feature on the internal channel for Published.
The Service Message API enables you to send service messages from your service to your LINE MINI App users.
Sending service messages requires a service notification token and a template.
# Issuing a service notification token
Issues a service notification token. Service notification tokens are used to send a service message to the associated user.
Service notification tokens have the following features:
- A service notification token expires 1 year (31,536,000 seconds) after being issued. While it is still valid, up to 5 service messages can be sent.
- Every time you use the service notification token, the token value is renewed unless it expired or no longer has remaining message counts. If you are planning to send successive service messages to a user, keep the renewed service notification token.
Issuing multiple service notification tokens reusing an access token obtained by liff.getAccessToken()
(LIFF access token) is not allowed.
Only one service notification token can be issued per LIFF access token.
Each service notification token is associated with one user. You cannot use a service notification token associated with one user to send a service message to other users.
# HTTP request
POST https://api.line.me/message/v3/notifier/token
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
For more information, see Channel access token in the LINE Platform basics.
Long-lived channel access tokens and channel access token with a user-specified expiration (Channel Access Token v2.1) cannot be used for LINE MINI App channels.
When developing LINE MINI Apps, either stateless channel access tokens or short-lived channel access tokens can be used. Stateless channel access tokens are recommended among those two. Stateless channel access tokens have an unlimited number of issuances, so there is no need for the application to manage the token lifecycle.
# Request body
liffAccessToken
String
User access token obtained by liff.getAccessToken()
(LIFF access token).
# Response
Returns status code 200
and a JSON object with the following information.
notificationToken
String
Service notification token
expiresIn
Number
The amount of time remaining in seconds before the service notification token expires. A service notification token expires 1 year (31,536,000 seconds) after being issued.
remainingCount
Number
The number of times you can send a service message with the issued service notification token
sessionId
String
The session ID. For more information, see Sending service messages.
# Error response
Returns one of the following status codes and error messages.
Status code | Description |
---|---|
400 Bad request | This status code means one of the following:
|
401 Unauthorized | This status code means one or both of the following:
|
403 Forbidden | This channel isn't authorized to issue service messages. |
500 Internal Server Error | Error on the internal server |
# Sending service messages
Sends a service message to a user specified in the service notification token.
Once a service message is sent, the token's value is renewed unless the token expired or no longer has remaining message counts. If you are planning to send successive service messages to a user, keep the renewed service notification token.
# HTTP request
POST https://api.line.me/message/v3/notifier/send
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
For more information, see Channel access token in the LINE Platform basics.
Long-lived channel access tokens and channel access token with a user-specified expiration (Channel Access Token v2.1) cannot be used for LINE MINI App channels.
When developing LINE MINI Apps, either stateless channel access tokens or short-lived channel access tokens can be used. Stateless channel access tokens are recommended among those two. Stateless channel access tokens have an unlimited number of issuances, so there is no need for the application to manage the token lifecycle.
# Query parameters
target
service
# Request body
templateName
String
The name of a pre-registered template to use for the service message, with a BCP 47 language tag suffix.
Format: {template name}_{BCP 47 language tag}
Max character limit: 30
The languages and language tags supported by the service message are as follows.
- Arabic:
ar
- Chinese (Simplified):
zh-CN
- Chinese (Traditional):
zh-TW
- English:
en
- French:
fr
- German:
de
- Indonesian:
id
- Italian:
it
- Japanese:
ja
- Korean:
ko
- Malay:
ms
- Portuguese (Brazil):
pt-BR
- Portuguese (Portugal):
pt-PT
- Russian:
ru
- Spanish (Spain):
es-ES
- Thai:
th
- Turkish:
tr
- Vietnamese:
vi
params
object
JSON Object to specify each template variable-value pair.
If the template has no template variable, specify an empty JSON object ({ }
).
The template variables are defined for each template. If a template variable is part of the required elements, be sure to specify a template variable-value pair.
For more information, see Adding service message templates.
notificationToken
String
Service notification token
# Response
Returns status code 200
and a JSON object with the following information.
notificationToken
String
A renewed service notification token. Use this service notification token to send successive service messages.
expiresIn
Number
The remaining amount of time in seconds until renewed service notification token expires
remainingCount
Number
The number of times you can send successive service messages with the renewed service notification token.
sessionId
String
The session ID. For more information, see Sending service messages.
If the values of expiresIn
and remainingCount
are 0
, it means that the service message was sent, but the service notification token couldn't be renewed.
# Error response
Returns one of the following status codes and error messages.
Status code | Description |
---|---|
400 Bad request | This status code means one of the following:
|
401 Unauthorized | This status code means one or both of the following:
|
403 Forbidden | This status code means one of the following:
|
# Common Profile Quick-fill
To use Common Profile Quick-fill, your LINE MINI App must be verified and have completed the application process.
Quick-fill is a feature that automatically fills in the necessary profile information by tapping the Auto-fill button on the LINE MINI App. You can easily use the Common Profile information that a user has set in the Account Center in the LINE MINI App. For more information, see Overview of Common Profile Quick-fill.
# liff.$commonProfile.get()
Gets the information in the Common Profile that the user has set in the Account Center.
When you execute the liff.$commonProfile.get()
method, a modal will appear to confirm the user's profile. After confirming the profile in the displayed modal, the user can tap Auto-fill and the profile information will be entered automatically.
Example of a modal display:
# Syntax
liff.$commonProfile.get(scopes, options);
# Arguments
scopes
Array of strings
Specify the scope of the Common Profile you want to obtain.
For information on the values that can be specified for scopes
, see The scopes
parameters that can be specified and its return value.
options
Object
Options for getting Common Profile information
options.formatOptions
Object
Options related to the format of information. Specify a formatOptions
object for each scope specified in the scopes
property.
Specify the scope for which you want to set the option in camel case format as the key. For example, when the scope is given-name
, the key is givenName
.
# formatOptions
object
excludeEmojis
Boolean
Whether to remove emojis from the string. The default is true
. This can only be specified in the following scopes:
- givenName
- familyName
excludeNonJp
Boolean
Whether to exclude phone numbers with 12 or more digits. The default is true
. If true
, an empty string and error information are returned when the phone number has 12 or more digits. This can only be specified in the following scope:
- tel
digitsOnly
Boolean
Whether to exclude postal codes that contain non-numeric characters. The default is true
. If true
, an empty string and error information are returned when the postal code contains characters other than numbers. This can only be specified in the following scope:
- postalCode
# Return value
Returns Promise
object of type { data: Partial<CommonProfile>, error: Partial<CommonProfileError>}
.
When Promise
is resolved, an object of type Partial<CommonProfile>
containing the user's Common Profile information is passed to the data
property, and an object of type Partial<CommonProfileError>
containing error information is passed to the error
property.
In the following cases, the property of data
will be undefined
or null
:
- Cases where the property value becomes
undefined
- If the target item isn't specified in the
scopes
parameter - If the target item is specified in the
scopes
parameter, but the user doesn't authorized permission for that item
- If the target item isn't specified in the
- Cases where the property value becomes
null
- If the user hasn't set a value for the target item in the Common Profile
- If an error occurs when retrieving the target item in the Common Profile
For information on the values of the properties that can be obtained according to the specified scopes
, see The scopes
parameters that can be specified and its return value.
# Error response
When the Promise
is rejected, LiffError
is passed.
# liff.$commonProfile.getDummy()
Gets the dummy data for the Common Profile. There are 10 types of dummy data available, and you can specify the dummy data to get using the caseId
.
When you execute the liff.$commonProfile.getDummy()
method, a modal will appear to confirm the dummy profile. You can get dummy data for the Common Profile by tapping Auto-fill.
Example of a modal display:
# Syntax
liff.$commonProfile.getDummy(scopes, options, caseId);
# Arguments
scopes
Array of strings
Specify the scope of the Common Profile you want to obtain.
For information on the values that can be specified for scopes
, see The scopes
parameters that can be specified and its return value.
options
Object
Options for getting Common Profile information
options.formatOptions
Object
Options related to the format of information. Specify a formatOptions
object for each scope specified in the scopes
property.
Specify the scope for which you want to set the option in camel case format as the key. For example, when the scope is given-name
, the key is givenName
.
caseId
number
Specify the ID of the dummy data you want to get. Dummy data with IDs from 1
to 10
is available.
For information about dummy data for each caseId
, see Dummy data for Common Profile that can be obtained.
# Return value
Returns Promise
object of type { data: Partial<CommonProfile>, error: Partial<CommonProfileError>}
.
When Promise
is resolved, an object of type Partial<CommonProfile>
containing the dummy data of the Common Profile is passed to the data
property, and an object of type Partial<CommonProfileError>
containing error information is passed to the error
property.
In the following cases, the property of data
will be undefined
or null
:
- Cases where the property value becomes
undefined
- If the target item isn't specified in the
scopes
parameter
- If the target item isn't specified in the
- Cases where the property value becomes
null
- If the dummy data doesn't have a value for the target item
For information on the dummy data you can get for the specified ID, see Dummy data for Common Profile that can be obtained.
# Error response
When the Promise
is rejected, LiffError
is passed.
# liff.$commonProfile.fill()
Automatically fills the form with the Common Profile information you have obtained. The data-liff-autocomplete
attribute is used to link each profile information to the form.
Automatic input using liff.$commonProfile.fill()
is performed using the data-liff-autocomplete
attribute of the form. At this time, the value specified in the data-liff-autocomplete
attribute of the form must match the scope of the profile information obtained (family-name
, tel
, bday-year
, etc.)
For example, if you want to automatically fill in a form after retrieving the year of birth (bday-year
), month of birth (bday-month
), and day of birth (bday-day
) information and then process it into a format like 20110623
, you can use document.getElementById().value
or document.querySelector().value
instead of liff.$commonProfile.fill()
.
# Syntax
liff.$commonProfile.fill(profile);
# Arguments
profile
Partial<CommonProfile>
Specify the profile information that is automatically fill into the form as a Partial<CommonProfile>
type.
For information on the scopes
, that can be specified, see The scopes
parameters that can be specified and its return value.
# Return value
None