# LIFF v2 API reference

# Client API

# Operating environment

For more information about supported operating environments for LIFF v2, see Overview in the LIFF documentation.

Which functions you can use depends on whether the LIFF app is opened in LINE's in-app browser or an external browser. For example, you can't use liff.scanCode() in an external browser. For more information, see the descriptions for each client API.

LIFF apps are not compatible with OpenChat

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	Description
400	Problem with the request. Check the request parameters and JSON format.
401	Check that the authorization header is correct.
403	Not authorized to use the API. Confirm that your account or plan is authorized to use the API.
429	Make sure that you are within the rate limit for requests.
500	Temporary error on the API server.
INIT_FAILED	Failed to init LIFF SDK.
INVALID_ARGUMENT	An invalid argument was specified.
UNAUTHORIZED	The user did not authorize. Call the server api without access token. Call the share target picker before LINE Login is used.
FORBIDDEN	You don't have the required permission. You attempted to use a feature in an environment that's not supported.
INVALID_CONFIG	An invalid setting. Specify the liffId to use LINE login. The URL of the page that executes the `liff.permanentLink.createUrl()` method doesn't start with the URL specified in the Endpoint URL.
INVALID_ID_TOKEN	Failed to verify the ID token.
EXCEPTION_IN_SUBWINDOW	Problem with subwindow. For example, if the target picker (group or friend selection screen) is displayed and has been idle for more than 10 minutes, for example.
THINGS_NO_LINKED_DEVICES	No linked device is available.
BLUETOOTH_SETTING_OFF	Bluetooth is off.
THINGS_TERMS_NOT_AGREED	LINE Things TOS is not agreed.
BLUETOOTH_NO_LOCATION_PERMISSION	Location permission is not granted.
BLUETOOTH_LOCATION_DISABLED	Location setting is off.
BLUETOOTH_LE_API_UNAVAILABLE	The BLE API for LIFF is not available on this device.
BLUETOOTH_CONNECT_FAILED	Failed to connect to the device.
BLUETOOTH_ALREADY_CONNECTED	The device is already connected.
BLUETOOTH_CONNECTION_LOST	No device is connected.
BLUETOOTH_UNSUPPORTED_OPERATION	The specified operation is not supported for the specified characteristic.
BLUETOOTH_SERVICE_NOT_FOUND	The specified service does not exist in the GATT server.
BLUETOOTH_CHARACTERISTIC_NOT_FOUND	The specified characteristic does not exist in the service.
UNKNOWN	Unknown error.

# LIFF SDK properties

# liff.ready

A property holding the Promise object that resolves when you run liff.init() for the first time after starting the LIFF app. When you run liff.init() for the first time after starting the LIFF app, the Promise is resolved.

If you use liff.ready, you can execute any process after the completion of liff.init().

liff.ready can be used before liff.init() finishes initializing the LIFF app.

Example request

Note

If liff.init() fails, liff.ready will not be rejected. Also, it doesn't return a LiffError object.

# liff.id

The property that holds the LIFF app ID (String type) passed to liff.init().

The value of liff.id is null until you run liff.init().

Example

# liff.init()

Initializes a LIFF app. You can only call other LIFF SDK methods after calling liff.init(). The LIFF SDK obtains the access token and ID token of the user from the LINE platform when you initialize the LIFF app.

To use the access token obtained by the LIFF SDK, call liff.getAccessToken().
To use the ID token payload obtained by the LIFF SDK, call liff.getDecodedIDToken().

Note the timing when you call liff.init() method

When users are first redirected to the endpoint URL (primary redirect URL), execute the liff.init() method. If executing the liff.init() method, except for the above timing, INIT_FAILED is returned and the LIFF app can't be opened. For more information, see Behaviors from accessing the LIFF URL to opening the LIFF app.

Example request

# Syntax

liff.init(
  config,
  successCallback,
  errorCallback
)

# Arguments

config

Object

Required

LIFF app configurations

config.liffId

String

Required

LIFF app ID. Can be obtained when you add the LIFF app to your channel. For more information, see Adding a LIFF app.
The LIFF app ID specified here can be obtained with liff.id.
Note: If the user isn't logging in through LINE, you must specify liffId.

successCallback

Function

Optional

Callback to return a data object upon successful initialization of the LIFF app.
Note: Required when a callback is used.

errorCallback

Function

Optional

Callback to return an error object upon failure to initialize the LIFF app.
Note: Required when a callback is used.

# Return value

Returns a Promise object.

# Error response

When the Promise is rejected, LiffError is passed.

# liff.getOS()

Gets the environment in which the user is running the LIFF app.

# Syntax

liff.getOS()

# Arguments

None

# Return value

The environment in which the user is running the LIFF app is returned as a string.

Return value	Description
ios	LINE in-app browser for iOS
android	LINE in-app browser for Android
web	External browser

# liff.getLanguage()

Gets the language settings of the environment in which the LIFF app is running.

# Syntax

liff.getLanguage()

Example request

# Syntax

liff.isLoggedIn()

# Arguments

None

# Return value

true: The user is logged in
false: The user is not logged in

# liff.isApiAvailable()

Checks whether the specified API is available in the environment where you started the LIFF app. Specifically, it verifies whether the current LINE version supports the API and whether the terms and conditions for the API have been accepted.

Example request

# Syntax

liff.isApiAvailable(apiName)

# Arguments

apiName

String

Required

The name of the LIFF client API. You can currently specify these API names:

shareTargetPicker

# Return value

Returns whether the specified API is available in the current environment.

Return value	Description
`true`	Available
`false`	Unavailable. Returns `false` in these situations: If the LIFF app was launched with a LINE version that doesn't support the API If the terms and conditions for the API haven't been accepted

Note

Always returns true if the LIFF app is launched in an external browser.

Performs the LINE Login process (web login) for the Web app.

Note

You cannot use liff.login() in LINE's in-app browser.

Example request

# Syntax

liff.login(loginConfig)

# Arguments

loginConfig

Object

Optional

LINE login configurations

loginConfig.redirectUri

String

Optional

URL to open in the LIFF app after LINE Login. The default value is the endpoint URL set when you added the LIFF app to the channel. For details on how to set the endpoint URL, see Adding the LIFF app to your channel.

# Return value

None

# liff.logout()

Logs out.

Example request

# Syntax

liff.logout()

# Arguments

None

# 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 LINE's in-app 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.getIDToken()

Get the raw ID token of the current user obtained by the LIFF SDK. An ID token is a JSON Web Token (JWT) that contains user information.

You can use the ID token obtained with this API when sending the 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.

Getting an ID token

If the user starts the LIFF app in LINE's in-app browser, the LIFF SDK will get an ID token when you call liff.init()
If the user starts the LIFF app in an external browser, the LIFF SDK will get an ID 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.getIDToken()

# Argument

None

# Return value

Returns a raw ID token

May return null

If you don't select the openid scope when adding the LIFF app to your channel, null is returned.

# liff.getDecodedIDToken()

Gets the payload of the ID token that's acquired by the LIFF SDK. The payload includes the user display name, profile image URL, and email address.

Use this API when you want to use the display name of the user in the LIFF app.

Don't send user info to server

Don't send the user information obtained by this API to the server. For more information, see Using user information in LIFF apps and servers in the LIFF documentation.

Getting an ID token

If the user starts the LIFF app in LINE's in-app browser, the LIFF SDK will get an ID token when you call liff.init()
If the user starts the LIFF app in an external browser, the LIFF SDK will get an ID 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.getDecodedIDToken()

# Arguments

None

# Return value

Gets the ID token payload.

For more information on ID token payloads, see the Payload section of Getting profile information and email address based on ID token in the Integrate LINE Login documentation.

Returned null

If you didn't select the openid scope when adding the LIFF app to a channel, null is returned.

Example ID token payload

# liff.getContext()

Gets the screen type (1-on-1 chat, group, room, or external browser) from which the LIFF app is launched. For 1-on-1 chats, groups, and rooms, you also get a unique ID.

Example request

# Syntax

liff.getContext()

# Arguments

None

# Return value

A data object that contains the information necessary to make various API calls.

type

String

The type of screen from where the LIFF app was launched. One of:

utou: 1-on-1 chat
group: Group
room: Room
external: External browser
none: A screen other than a 1-on-1 chat, room, group, or external browser. For example, Wallet tab.

viewType

String

Size of the LIFF app view, only returned if the type property is utou, room, or group. One of:

compact
tall
full

For more information, see Adding the LIFF app to a channel.

userId

String

User ID

utouId

String

1-on-1 chat ID. Included when the type property is utou.

groupId

String

Group ID. Included when the type property is group.

roomId

String

Room ID. Included when the type property is room.

availability.shareTargetPicker.permission

Boolean

Specifies whether liff.shareTargetPicker() is available in the environment in which the LIFF app was launched.

true: liff.shareTargetPicker() is available
false: not available

availability.shareTargetPicker.minVer

String

The minimum LINE version that supports liff.shareTargetPicker().

Method may return null object

null is returned in the following cases:

The LIFF app is launched on an external browser.
The LIFF app is launched on the LINE's in-app browser and LINE login is used.

Example response

# 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.

# Error response

When the Promise is rejected, LiffError is passed.

Example user profile information

# liff.getFriendship()

Gets the friendship status of the LINE Official Account that's linked to the LINE Login channel to which the LIFF app is added.

Learn more on how to link a LINE Official Account to a LINE Login channel.

Example request

# Syntax

liff.getFriendship()

# Arguments

None

# Return value

Returns a Promise object.

When acquiring the status of friendship, the Promise is resolved and the information about friendship is passed.

friendFlag

Boolean

true: The user has added the LINE Official Account as a friend and has not blocked it.
Otherwise, false.

# Error response

When the Promise is rejected, LiffError is passed.

Example return value

# liff.permanentLink.createUrl()

Gets the permanent link for the current page.

Permanent link format:

https://liff.line.me/{liffId}/{path}?{query}#{URL fragment}

Example request

# Syntax

liff.permanentLink.createUrl()

# Arguments

None

# Return value

Returns the current page's permanent link as a string.

An exception is thrown if the current page URL doesn't start with the URL specified in Endpoint URL.

Note

When setting Methods for converting additional information in the LIFF URL to Replace (Backward compatibility mode), the paths and query parameters (/2020campaign/?key=value) specified in Endpoint URL may not be included in the secondary redirect URL. In this case, you can't get a permanent link because the liff.permanentLink.createUrl() method meets the above conditions.

# liff.permanentLink.setExtraQueryParams()

You can add any query parameter to a permanent link on the current page.

Each time you execute liff.permanentLink.setExtraQueryParams(), the query parameters added last time are overwritten.

Delete added query parameters

To delete the added query parameters, execute liff.permanentLink.setExtraQueryParams("").
The added query parameters will be discarded when the user navigates to another page.

Example request

# Syntax

liff.permanentLink.setExtraQueryParams(extraString)

# Arguments

extraString

String

Required

Query parameters to add

# Return value

None

# 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.

Note

liff.sendMessages() cannot be used with an external browser.

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

Returns a Promise object.

If the message is sent successfully, the Promise is resolved. No value is passed.
If you fail to send the message, the Promise is rejected and LiffError is passed.

# liff.openWindow()

Opens the specified URL in the in-app browser of LINE or external browser.

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 in-app browser of LINE.

# Return value

None

Displays the target picker (screen for selecting a group or friend) and sends the message created by the developer to the selected target. This message appears to your group or friends as if you had sent it.

Note

To view the target picker, turn on the share target picker in the Console. For more information, see Using share target picker.
When using an external browser, call liff.login(), complete the LINE Login process (web login), then call liff.shareTargetPicker().

Target picker operating environment

Target picker is supported on LINE 10.3.0 or later for iOS and Android.
Before executing liff.shareTargetPicker(), you can confirm that the target picker is available in the environment where the LIFF app is started by executing liff.isApiAvailable().

Example request

# Syntax

liff.shareTargetPicker(messages)

# Arguments

messages

Array of objects

Required

Message objects
Max: 5
You can send the following types of Messaging API messages:

Text message
Image message
Video message
Audio message
Location message
Template message. However, only a URI action can be set as an action.
Flex Message

# Return value (LINE 10.3.0-10.10.0)

Returns a Promise object.

When the target picker is displayed, the Promise resolves.

If a problem occurs before the target picker is displayed, Promise is rejected and LiffError is passed. For more information on the LiffError object, see LIFF SDK errors.

Note

Situations after the target picker is displayed can't be detected, such as when the user doesn't select a destination in the displayed target picker.
In the callback function where Promise has been resolved and rejected, the LIFF app won't work on some devices if the developer uses alert().

# Return value (LINE 10.11.0-)

Returns a Promise object.

If the message is sent correctly, Promise is resolved and an object with these properties will be passed.

<ParameterTable>

<ParameterTableEntry>

::: slot name
status
:::

::: slot type
String
:::

`success`

</ParameterTableEntry>

</ParameterTable>

If the user cancels and closes the target picker before sending the message, Promise is resolved but the object isn't passed.

If a problem occurs before the target picker is displayed, Promise is rejected and LiffError is passed. For more information on the LiffError object, see LIFF SDK errors.

Note

In the callback function where Promise has been resolved and rejected, the LIFF app won't work on some devices if the developer uses alert().

# liff.scanCode()

Starts LINE's QR code reader and gets the string read by the user. To start the QR code reader, grant ScanQR permission to the LIFF app in the LINE Developers Console.

Not available on LINE for iOS v9.19.0 or later

Due to a technical limitation, liff.scanCode() will be undefined on LINE for iOS version 9.19.0 and later. Check the existence of the function as shown in the sample code before using it.

Note

You cannot use liff.scanCode() in an external browser.

Example request

# Syntax

liff.scanCode()

# Arguments

None

# Return value

Returns a Promise object.

When reading a string by LINE's QR code reader, the Promise is resolved and the object containing the string read is passed.

value

String

String read by the QR code reader

# 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 for iOS v9.19.0 and later, 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 for iOS v9.19.0 or later

Due to a technical issue, liff.bluetooth.getAvailability() has been suspended on LINE for iOS v9.19.0 and later.

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 for iOS v9.19.0 or later

Due to a technical issue, liff.bluetooth.requestDevice() has been suspended on LINE for iOS v9.19.0 and later.

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

Method	Return value	Description
readValue	Promise <DataView>	Reads the value of the characteristic.
writeValue(value)	Promise <void>	Writes the BufferSource 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 for iOS v9.19.0 or later

Due to a technical issue, liff.bluetooth.referringDevice has been suspended on LINE for iOS v9.19.0 and later.

When the LIFF app is launched via a device, liff.bluetooth.referringDevice is set to a BluetoothDevice object that indicates device information.

# LIFF v2 API reference

# Client API

# Operating environment

# LIFF SDK errors

# LiffError object

# Error details

# LIFF SDK properties

# liff.ready

# liff.id

# liff.init()

# Syntax

# Arguments

# Return value

# Error response

# liff.getOS()

# Syntax

# Arguments

# Return value

# liff.getLanguage()

# Syntax

# Arguments

# Return value

# liff.getVersion()

# Syntax

# Arguments

# Return value

# liff.getLineVersion()

# Syntax

# Arguments

# Return value

# liff.isInClient()

# Syntax

# Arguments

# Return value

# liff.isLoggedIn()

# Syntax

# Arguments

# Return value

# liff.isApiAvailable()

# Syntax

# Arguments

# Return value

# liff.login()

# Syntax

# Arguments

# Return value

# liff.logout()

# Syntax

# Arguments

# Return value

# liff.getAccessToken()

# Syntax

# Arguments

# Return value

# liff.getIDToken()

# Syntax

# Argument

# Return value

# liff.getDecodedIDToken()

# Syntax

# Arguments

# Return value

# liff.getContext()

# Syntax

# Arguments

# Return value

# liff.getProfile()

# Syntax

# Arguments

# Return value

# Error response

# liff.getFriendship()

# Syntax

# Arguments

# Return value

# Error response

# liff.permanentLink.createUrl()

# Syntax

# Arguments

# Return value