# LIFF v1 API reference
This is the API reference for LIFF SDK v1, an older version of LIFF. We highly recommend you use LIFF v2 instead.
Learn how to Add a LIFF app to your channel in the LIFF documentation.
# Client API
# Operating environment
LIFF v1 supports the following versions of operating systems and LINE:
- iOS: iOS 8 or later. iOS 9 or later uses WKWebView (opens new window) and iOS 8.x uses UIWebView (opens new window).
- Safari 8 or later
- Android: 4.2 (Jelly Bean MR1 and API level 17) or later
- Chrome 32 or later
- LINE: Version 7.14 or later
Currently, LIFF apps are not officially supported in OpenChat, which means some functions don't work. For example, retrieving a user's profile information through a LIFF app isn't possible in most cases.
# LIFF SDK errors
LIFF SDK errors are returned in LiffError objects.
Example error
# LiffError object
code
String
Error code
message
String
Error message. Returned when the defined message exists.
# Error details
Error code | Error message | Description |
---|---|---|
INIT_FAILED | Failed to init LIFF SDK | The JavaScript resource of LIFF SDK could not be loaded. |
INIT_FAILED | Current environment is not supported. Please open it with LINE | An attempt was made to open the LIFF app in an unsupported environment. |
INIT_FAILED | Could not authenticate LIFF app | JSON Web Token (JWT) is invalid or does not exist. You should start LIFF from LINE, and specify the JWT. |
INVALID_ARGUMENT | - | The argument is invalid. |
INTERNAL_ERROR | - | An internal error has occurred. |
THINGS_NO_LINKED_DEVICES | There are no linked devices. | No linked device is available. |
BLUETOOTH_CONNECT_FAILED | Failed to connect to device. | Failed to connect to the device. |
BLUETOOTH_ALREADY_CONNECTED | The device is already connected. | The device is already connected. |
BLUETOOTH_CONNECTION_LOST | The device has been disconnected. | No device is connected. |
BLUETOOTH_UNSUPPORTED_OPERATION | The operation is not supported on this characteristic. | The specified operation is not supported for the specified characteristic. |
BLUETOOTH_SERVICE_NOT_FOUND | The service is not found in the GATT server. | The specified service does not exist in the GATT server. |
BLUETOOTH_CHARACTERISTIC_NOT_FOUND | The characteristic is not found in the service. | The specified characteristic does not exist in the service. |
# liff.init()
Initializes a LIFF app. This method will allow you to execute the other methods of the LIFF SDK.
Example request
# Syntax
liff.init(successCallback, errorCallback)
# Arguments
successCallback
Function
Callback to return a data object upon a successful call
errorCallback
Function
Callback to return an error object upon a failed call
# Return value
A data object that contains the information necessary to make various API calls is passed to the first argument of the callback.
Example return value
# Data object
language
String
Language setting of LINE
context.type
String
Type of context. This property indicates where the LIFF app was opened within LINE. One of the following values is contained:
utou
: One-on-one chatroom
: Roomgroup
: Groupnone
: Not in a chat screen
context.viewType
String
Size of the LIFF app view. One of the following values is contained:
compact
tall
full
For more information, see Adding the LIFF app to a channel.
context.userId
String
User ID.
context.utouId
String
One-on-one chat ID. This property is included when the context.type
property has a value of utou
.
context.roomId
String
Room ID. This property is included when the context.type
property has a value of room
.
context.groupId
String
Group ID. This property is included when the context.type
property has a value of group
.
# liff.openWindow()
Opens the specified URL in the LINE's in-app browser or external browser.
- Use of
liff.openWindow()
in an external browser isn't guaranteed. - If the
url
property doesn't contain a query parameter (?key=value
) but has a URL fragment (#URL-fragment
) in LINE versions earlier than 10.16.0 for iOS, the URL fragment will be set to an invalid value. This table shows an example of the link destination whenhttps://example.com#URL-fragment
is set in theurl
property.
LINE version for iOS | Link destination |
---|---|
Versions prior to 10.16.0 | https://example.com#URL-fragment?is_liff_external_open_window=false |
Version 10.16.0 or later | https://example.com#URL-fragment |
Example request
# Syntax
liff.openWindow(params)
# Arguments
params
Object
Parameter object
params.url
String
URL. Specify the absolute path to the URL.
params.external
Boolean
Whether to open the URL in an external browser. Specify one of the following values: The default value is false
.
true
: Opens the URL in an external browser.false
: Opens the URL in the LINE's in-app browser.
# Return value
None
# liff.getAccessToken()
Gets the current user's access token.
You can use the access token obtained with this API to send user information from the LIFF app to the server. For more information, see Using user information in LIFF apps and servers in the LIFF documentation.
The access token is valid for 12 hours after being issued. When the user closes the app, the access token is revoked.
- If the user starts the LIFF app in a LIFF browser, the LIFF SDK will get an access token when you call
liff.init()
- If the user starts the LIFF app in an external browser, the LIFF SDK will get an access token when these steps are satisfied:
- You call
liff.login()
. - The user logs in to LINE.
- You call
liff.init()
.
- You call
Example request
# Syntax
liff.getAccessToken()
# Arguments
None
# Return value
Returns the current user's access token as a string.
# liff.getProfile()
Gets the current user's profile.
Example request
# Syntax
liff.getProfile()
# Arguments
None
# Return value
Returns a Promise
object.
When the Promise
is resolved, the object containing the user's profile information is passed.
userId
String
User ID
displayName
String
Display name
pictureUrl
String
Image URL. This property is not returned if it has not been set by the user.
statusMessage
String
Status message. This property is not returned if it has not been set by the user.
This method internally calls LINE Login using axios (opens new window). For error handling, refer to the axios documentation and Status codes in the LINE Login API reference.
Example user profile information
# liff.sendMessages()
Sends messages on behalf of the user to the chat screen where the LIFF app is opened. If the LIFF app is opened on a screen other than the chat screen, messages cannot be sent.
If you open the LIFF app in a web browser by using the LINE URL scheme https://line.me/R/app/{liffId}
, then you can't send messages from the LIFF app, even if you call liff.sendMessages(messages)
.
Example request
# Syntax
liff.sendMessages(messages)
# Arguments
messages
Array of objects
Message objects
Max: 5
You can send the following types of Messaging API messages:
- Text message
- Sticker message
- Image message
- Video message
- Audio message
- Location message
- Template message. However, only a URI action can be set as an action.
- Flex Message
When messages are sent to a chat that includes a bot LINE Official Account, the LINE Platform sends webhook events to the bot server. When image, video, and audio messages are sent using the liff.sendMessages()
method, resulting webhook events contain the contentProvider.type
property whose value is external
. For more information, see Message event in the Messaging API reference.
# Return value
There is no return value if the message is sent successfully.
This method internally calls the LINE platform using axios (opens new window). For error handling, refer to the axios documentation and Status codes below.
# Status codes
Status code | Description |
---|---|
400 | The message is invalid. |
401 | Authentication failed. |
403 | The access token does not have appropriate permissions. |
# liff.closeWindow()
Closes the LIFF app.
Example request
# Syntax
liff.closeWindow()
# Arguments
None
# Return value
None
# liff.initPlugins()
Enable the plugins.
For example, if you enable the Bluetooth plugin, you can use the client API (liff.bluetooth.*
) provided by the Bluetooth plugin.
Example request
# Syntax
liff.initPlugins(pluginNames)
# Arguments
pluginNames
Array of String
Plugin name. Specify one of the following values:
bluetooth
*The Bluetooth plug-in can only be activated on LINE for Android or versions before 9.19.0 for LINE for iOS. When using LINE 9.19.0 or later for iOS, activation fails and a FORBIDDEN error is returned.
# Return value
Returns a Promise
object.
- If the plugin is enabled successfully, the
Promise
is resolved. - If you fail to enable the plugin, the
Promise
is rejected and the error information is passed.
# liff.bluetooth.getAvailability()
Due to a technical issue, liff.bluetooth.getAvailability()
has been suspended on LINE 9.19.0 or later for iOS.
Check if the Bluetooth plugin can be used. Call this method to check the following conditions:
Bluetooth support for the LIFF app added to your channel is enabled
NoteYou must enable the Bluetooth® Low Energy function of the LIFF app added to your channel to initialize the Bluetooth plugin.
Smartphone has Bluetooth enabled
User has accepted the LINE Things Terms of Use
If using LINE on Android, user has granted permission to use smartphone location information
Enable the Bluetooth plugin by using liff.initPlugins() beforehand.
Example request
# Syntax
liff.bluetooth.getAvailability()
# Arguments
None
# Return value
Returns a Promise
object.
When the Bluetooth plugin is checked for availability, the Promise
is resolved and a Boolean
object indicating whether or not the Bluetooth plugin can be used is passed.
# liff.bluetooth.requestDevice()
Due to a technical issue, liff.bluetooth.requestDevice()
has been suspended on LINE 9.19.0 or later for iOS.
Scans the linked device, and acquires the information.
You can use a filter to restrict the devices that receive the advertisement packets.
Make sure you first enable the Bluetooth plugin with liff.initPlugins().
Example request
# Syntax
liff.bluetooth.requestDevice(options)
# Arguments
options
Object
RequestDeviceOptions
object expressing the filter. Omit to retrieve advertisement packets from all devices.
# Data object
# RequestDeviceOptions object
filters
Array of Object
Array of the LINEBluetoothRequestDeviceFilter
object
# LINEBluetoothRequestDeviceFilter object
deviceId
String
Device ID of the device that receives the advertisement packet
# Return value
Returns a Promise
object.
When scanning linked devices and acquiring the information, the Promise
is resolved and the BluetoothDevice
object indicating information about the devices is passed.
# Data object
# BluetoothDevice object
id
String
Device ID
name
String
device name
gatt
Object
watchingAdvertisements
Boolean
Monitoring status of advertisement packet (*)
Method | Return value | Description |
---|---|---|
watchAdvertisements | Promise <void> | Starts the reception of the advertisement packet. (*) |
unwatchAdvertisements | void | Stops the reception of the advertisement packet. (*) |
addEventListener | void | Registers the event listener. You can register the event listener in advertisementreceived event(*) and gattserverdisconnected event. |
removeEventListener | void | Deletes the already-registered event listener. You can delete the event listener registered in advertisementreceived event(*) and gattserverdisconnected event. |
(*) These functions are implemented on experiment basis. These functions may be changed or stopped without prior notice.
# BluetoothRemoteGATTServer object
To communicate with devices, use the BluetoothRemoteGATTServer
object that expresses the GATT server (Generic Attribute Profile server).
If Promise
is resolved after executing liff.bluetooth.requestDevice()
, then BluetoothRemoteGATTServer
can be accessed from the gatt
property of the BluetoothDevice
object.
device
Object
connected
Boolean
true
if connected. false
if not connected
Method | Return value | Description |
---|---|---|
connect | Promise <BluetoothRemoteGATTService> | Connects with the device. |
disconnect | void | Disconnects from the GATT server of the device. |
getPrimaryService(serviceUUID) | Promise <BluetoothRemoteGATTService> | Acquires the primary service of the GATT server. Specify a 128-bit UUID as a string in the serviceUUID. Note: This method does not verify the UUID. The UUID is verified when the characteristics are read or written, and when a notification is started or stopped. |
# BluetoothRemoteGATTService object
The BluetoothRemoteGATTService
object is used to acquire the characteristics.
device
Object
uuid
String
GATT Service UUID
Method | Return value | Description |
---|---|---|
getCharacteristic(characteristicUUID) | Promise <BluetoothRemoteGATTCharacteristic> | Acquires the characteristics. Specify a 128-bit UUID as a string in the characteristicUUID. Note: This method does not verify the UUID. The UUID is verified when the characteristics are read or written, and when a notification is started or stopped. |
# BluetoothRemoteGATTCharacteristic object
The BluetoothRemoteGATTCharacteristic
object is used to read or write the characteristic of the devices, and also to start or stop a notification.
service
Object
uuid
String
UUID
value
Object
Method | Return value | Description |
---|---|---|
readValue | Promise <DataView (opens new window)> | Reads the value of the characteristic. |
writeValue(value) | Promise <void> | Writes the BufferSource (opens new window) value to the characteristic. |
startNotifications | Promise <BluetoothRemoteGATTCharacteristic> | Starts the notification of characteristic change. |
stopNotifications | Promise <BluetoothRemoteGATTCharacteristic> | Stops the notification of characteristic change. |
addEventListener | void | Registers the event listener. You can register the event listener in characteristicvaluechanged event containing the target property. |
removeEventListener | void | Deletes the already-registered event listener. You can delete the event listener registered in characteristicvaluechanged event. |
readValue()
method, writeValue()
method, startNotifications()
method, and stopNotifications()
method verify the UUID and properties. If a UUID or property that does not exist is specified, an error occurs.
Example request
# Events
# advertisementreceived event
If an advertisement packet is received, the advertisementreceived
event occurs.
The advertisementreceived
event is a function that is implemented on experiment basis. This function may be changed or stopped without prior notice.
device
Object
name
String
device name
rssi
Number
RSSI
manufacturerData
Object
Map<Number, DataView>object. Data in which the Company Identifier Code is mapped to the DataView
object.
# gattserverdisconnected event
If the Bluetooth connection is disconnected due to various reasons, the gattserverdisconnected
event occurs. Be sure to register the event listener.
Example request
# characteristicvaluechanged event
If a characteristic is changed, the characteristicvaluechanged
event occurs.
# liff.bluetooth.referringDevice
Due to a technical issue, liff.bluetooth.referringDevice
has been suspended on LINE 9.19.0 or later for iOS.
When the LIFF app is launched via a device, liff.bluetooth.referringDevice is set to a BluetoothDevice
object that indicates device information.
# Server API
# Preparing a channel access token
You need a channel access token to use the LIFF server API.
# On a LINE Login channel
Issue a channel access token for the LINE Login channel.
For more information, see Issue short-lived channel access token in the Messaging API reference.
# On a Messaging API channel
Issue a channel access token for the Messaging API channel.
For more information, see Channel access tokens in the Messaging API documentation.
# Adding the LIFF app to a channel
Adds the LIFF app to a channel. You can add up to 30 LIFF apps on one channel.
Example request
# HTTP request
POST https://api.line.me/liff/v1/apps
# Request headers
Authorization
Bearer {channel access token}
For more information, see Preparing a channel access token.
Content-Type
application/json
# Request body
view.type
String
Size of the LIFF app view. Specify one of these values:
compact
tall
full
For more information, see Size of the LIFF app view.
view.url
String
Endpoint URL. This is the URL of the web app that implements the LIFF app (example: https://{Heroku app name}.herokuapp.com
). Used when the LIFF app is launched using the LIFF URL.
The URL scheme must be https. URL fragments (#URL-fragment) can't be specified.
view.moduleMode
Boolean
true
to use the LIFF app in modular mode. When in modular mode, the share button in the header is not displayed.
description
String
Name of the LIFF app
features.ble
Boolean
true
if the LIFF app supports Bluetooth® Low Energy for LINE Things. false
otherwise.
permanentLinkPattern
String
How additional information in LIFF URLs is handled. Specify concat
.
For more information, see Opening a LIFF app in the LIFF documentation.
# Response
Returns status code 200
and a JSON object with the following properties.
liffId
String
LIFF app ID
Example response
# Error response
One of the following status codes is returned.
Status code | Description |
---|---|
400 | This status code means one of the following:
|
401 | Authentication failed. |
# Update LIFF app settings
Partially updates LIFF app settings.
Example request
# HTTP request
PUT https://api.line.me/liff/v1/apps/{liffId}
# Request headers
Authorization
Bearer {channel access token}
For more information, see Preparing a channel access token.
Content-Type
application/json
# Path parameters
liffId
ID of the LIFF app to be updated
# Request body
view.type
String
Size of the LIFF app view. Specify one of these values:
compact
tall
full
For more information, see Size of the LIFF app view.
view.url
String
Endpoint URL. This is the URL of the web app that implements the LIFF app (example: https://{Heroku app name}.herokuapp.com
). Used when the LIFF app is launched using the LIFF URL.
The URL scheme must be https. URL fragments (#URL-fragment) can't be specified.
view.moduleMode
Boolean
true
to use the LIFF app in modular mode. When in modular mode, the share button in the header is not displayed.
description
String
Name of the LIFF app.
features.ble
Boolean
true
if the LIFF app supports Bluetooth® Low Energy for LINE Things. false
otherwise.
permanentLinkPattern
String
How additional information in LIFF URLs is handled. Specify concat
.
For more information, see Opening a LIFF app in the LIFF documentation.
Only the properties specified in the request body are updated.
# Response
Status code 200
is returned.
# Error response
One of the following status codes is returned.
Status code | Description |
---|---|
401 | Authentication failed. |
404 | This status code means one of the following:
|
# Get all LIFF apps
Gets information on all the LIFF apps added to the channel.
Example request
# HTTP request
GET https://api.line.me/liff/v1/apps
# Request headers
Authorization
Bearer {channel access token}
For more information, see Preparing a channel access token.
# Response
Returns status code 200
and a JSON object with these properties.
apps
Array of objects
Array of LIFF app objects
apps[].liffId
String
LIFF app ID
apps[].view.type
String
Size of the LIFF app view. One of these values:
compact
tall
full
For more information, see Size of the LIFF app view.
apps[].view.url
String
Endpoint URL. This is the URL of the web app that implements the LIFF app (example: https://{Heroku app name}.herokuapp.com
). Used when the LIFF app is launched using the LIFF URL.
apps[].view.moduleMode
Boolean
true
to use the LIFF app in modular mode. When in modular mode, the share button in the header is not displayed.
apps[].description
String
Name of the LIFF app
apps[].features.ble
Boolean
true
if the LIFF app supports Bluetooth® Low Energy for LINE Things. false
otherwise.
apps[].permanentLinkPattern
String
How additional information in LIFF URLs is handled. concat
is returned.
For more information, see Opening a LIFF app in the LIFF documentation.
Example response
# Error response
One of the following status codes is returned.
Status code | Description |
---|---|
401 | Authentication failed. |
404 | There is no LIFF app on the channel. |
# Delete LIFF app from a channel
Deletes a LIFF app from a channel.
Example request
# HTTP request
DELETE https://api.line.me/liff/v1/apps/{liffId}
# Request headers
Authorization
Bearer {channel access token}
For more information, see Preparing a channel access token.
# Path parameters
liffId
ID of the LIFF app to be deleted
# Response
Status code 200
is returned.
# Error response
One of the following status codes is returned.
Status code | Description |
---|---|
401 | Authentication failed. |
404 | This status code means one of the following:
|