# LIFF v1 API reference

# 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

LIFF apps not supported in OpenChat

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

Required

Callback to return a data object upon a successful call

errorCallback

Function

Required

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 chat
room: Room
group: Group
none: 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.

Note

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 when https://example.com#URL-fragment is set in the url 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

Required

Parameter object

params.url

String

Required

URL. Specify the absolute path to the URL.

params.external

Boolean

Optional

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.

Note

The access token is valid for 12 hours after being issued. When the user closes the app, the access token is revoked.

Getting an access token

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:
1. You call liff.login().
2. The user logs in to LINE.
3. You call liff.init().

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.

Limitations when opening LIFF apps in web browser

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

Required

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

Required

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()

Not available on LINE 9.19.0 or later for iOS

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

Note
You 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

Note

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()

Not available on LINE 9.19.0 or later for iOS

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.

Note

Make sure you first enable the Bluetooth plugin with liff.initPlugins().

Example request

# Syntax

liff.bluetooth.requestDevice(options)

# Arguments

options

Object

Optional

RequestDeviceOptionsobject expressing the filter. Omit to retrieve advertisement packets from all devices.

# Data object

# RequestDeviceOptions object

filters

Array of Object

Required

Array of the LINEBluetoothRequestDeviceFilter object

# LINEBluetoothRequestDeviceFilter object

deviceId

String

Required

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

String

Required

Device ID

name

String

Optional

device name

gatt

Object

Optional

BluetoothRemoteGATTServer object

watchingAdvertisements

Boolean

Required

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

Required

BluetoothDevice object

connected

Boolean

Required

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

Required

BluetoothDevice object

uuid

String

Required

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

Optional

BluetoothRemoteGATTService object

uuid

String

Required

UUID

value

Object

Optional

DataView object (opens new window)

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.

Note

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.

Note

The advertisementreceived event is a function that is implemented on experiment basis. This function may be changed or stopped without prior notice.

device

Object

Required

BluetoothDevice object

name

String

Optional

device name

rssi

Number

Optional

RSSI

manufacturerData

Object

Optional

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

Not available on LINE 9.19.0 or later for iOS

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.

Issue a channel access token for the LINE Login channel.

For more information, see Issue 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

Required

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

Required

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

Optional

true to use the LIFF app in modular mode. When in modular mode, the share button in the header is not displayed.

description

String

Optional

Name of the LIFF app

features.ble

Boolean

Optional

true if the LIFF app supports Bluetooth® Low Energy for LINE Things. false otherwise.

permanentLinkPattern

String

Optional

How to handle additional information in LIFF URLs. Specify one of these values. The default value is concat.

concat: Concatenate
replace: Replace (Backward compatibility mode)

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: The request contains an invalid value. The maximum number of LIFF apps that can be added to the channel has been reached.
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

Optional

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

Optional

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

Optional

true to use the LIFF app in modular mode. When in modular mode, the share button in the header is not displayed.

description

String

Optional

Name of the LIFF app.

features.ble

Boolean

Optional

true if the LIFF app supports Bluetooth® Low Energy for LINE Things. false otherwise.

permanentLinkPattern

String

Optional

How to handle additional information in LIFF URLs. Specify one of these values. The default value is concat.

concat: Concatenate
replace: Replace (Backward compatibility mode)

For more information, see Opening a LIFF app in the LIFF documentation.

Note

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: The specified LIFF app does not exist. The specified LIFF app has been added to another channel.

# 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 to handle additional information in LIFF URLs. One of these values.

concat: Concatenate
replace: Replace (Backward compatibility mode)

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: The specified LIFF app does not exist. The specified LIFF app has been added to another channel.

# LIFF v1 API reference

# Client API

# Operating environment

# LIFF SDK errors

# LiffError object

# Error details

# liff.init()

# Syntax

# Arguments

# Return value

# Data object

# liff.openWindow()

# Syntax

# Arguments

# Return value

# liff.getAccessToken()

# Syntax

# Arguments

# Return value

# liff.getProfile()

# Syntax

# Arguments

# Return value

# liff.sendMessages()

# Syntax

# Arguments

# Return value

# Status codes

# liff.closeWindow()

# Syntax

# Arguments

# Return value

# liff.initPlugins()

# Syntax

# Arguments

# Return value

# liff.bluetooth.getAvailability()

# Syntax

# Arguments

# Return value

# liff.bluetooth.requestDevice()

# Syntax

# Arguments

# Data object

# RequestDeviceOptions object

# LINEBluetoothRequestDeviceFilter object

# Return value

# Data object

# BluetoothDevice object

# BluetoothRemoteGATTServer object

# BluetoothRemoteGATTService object

# BluetoothRemoteGATTCharacteristic object

# Events

# advertisementreceived event

# gattserverdisconnected event

# characteristicvaluechanged event

# liff.bluetooth.referringDevice

# Server API

# Preparing a channel access token

# On a LINE Login channel

# On a Messaging API channel

# Adding the LIFF app to a channel

# HTTP request

# Request headers

# Request body

# Response

# Error response

# Update LIFF app settings

# HTTP request

# Request headers

# Path parameters

# Request body

# Response

# Error response

# Get all LIFF apps

# HTTP request

# Request headers

# Response

# Error response

# Delete LIFF app from a channel