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 and iOS 8.x uses UIWebView.
  • 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 SDK errors

LIFF SDK errors are returned in LiffError objects.

LiffError object

Property	Type	Description
code	String	Code
message	String	Message. Returned when the defined message exists.

Error details

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

{
  "code":"INIT_FAILED",
  "message":"Failed to init LIFF SDK"
}

liff.init()

Initializes a LIFF app. This method will allow you to execute the other methods of the LIFF SDK.

Syntax

liff.init(successCallback, errorCallback)

Arguments

Property	Type	Required	Description
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

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.init(
  data => {
    // Now you can call LIFF API
    const userId = data.context.userId;
  },
  err => {
    // LIFF initialization failed
  }
);

Return value

A data object that contains the information necessary to make various API calls is passed to the first argument of the callback.

Data object

Property	Type	Description
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.

{
  "language":"ja-JP",
  "context":{
    "userId":"U4af498...",
    "type":"group",
    "groupId":"Ca5637c...",
    "viewType":"full"
  }
}

liff.openWindow()

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

Syntax

liff.openWindow(params)

Arguments

params object

Property	Type	Required	Description
url	String	Required	URL. Specify the absolute path to the URL.
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

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.openWindow({
  url: "https://line.me",
  external: true
});

liff.getAccessToken()

Gets the current user's access token.

Syntax

liff.getAccessToken()

Arguments

None

Return value

Returns the current user's access token as a string.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

const accessToken = liff.getAccessToken();
if (accessToken) {
  fetch("https://api...", {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`
    }
    //...
  });
}

liff.getProfile()

Gets the current user's profile.

Syntax

liff.getProfile()

Arguments

None

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.getProfile()
.then(profile => {
  const name = profile.displayName
})
.catch((err) => {
  console.log('error', err);
});

Return value

Returns a Promise object that contains the user's profile information.

Property	Type	Description
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 the Social API using axios. For error handling, refer to the axios documentation and Status codes in the Social API reference documentation.

{
  "userId":"U4af4980629...",
  "displayName":"Brown",
  "pictureUrl":"https://example.com/abcdefghijklmn",
  "statusMessage":"Hello, LINE!"
}

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.

Syntax

liff.sendMessages(messages)

Arguments

Property	Type	Required	Description
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 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. 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.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.sendMessages([
  {
    type:'text',
    text:'Hello, World!'
  }
])
.then(() => {
  console.log('message sent');
})
.catch((err) => {
  console.log('error', err);
});

liff.closeWindow()

Closes the LIFF app.

Syntax

liff.closeWindow()

Arguments

None

Return value

None

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.closeWindow();

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.

Syntax

liff.initPlugins(pluginList: Array<String>): Promise<void>

Arguments

Property	Type	Required	Description
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

There is no return value if the plugin is enabled successfully.

If you fail to enable the plugins, a Promise object containing the error information is returned.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.initPlugins(['bluetooth']).then(() => {
    liffCheckAvailablityAndDo(() => liffRequestDevice());
}).catch(error => {
    console.log(error);
});

liff.bluetooth.getAvailability()

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.

Syntax

liff.bluetooth.getAvailability(): Promise<Boolean>

Arguments

None

Return value

A Promise object is returned. The Promise object contains a Boolean object indicating whether or not the Bluetooth plugin can be used.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

liff.bluetooth.getAvailability().then(available => {
    alert('available?' + available);
});

liff.bluetooth.requestDevice()

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

Syntax

liff.bluetooth.requestDevice(options?: RequestDeviceOptions): Promise<BluetoothDevice>;

Arguments

Property	Type	Required	Description
options	Object	Optional	RequestDeviceOptionsobject expressing the filter. Omit to retrieve advertisement packets from all devices.

Data object

RequestDeviceOptions object

Property	Type	Required	Description
filters	Array of Object	Required	Array of the LINEBluetoothRequestDeviceFilter object

LINEBluetoothRequestDeviceFilter object

Property	Type	Required	Description
deviceId	String	Required	Device ID of the device that receives the advertisement packet

Return value

A Promise object is returned. The Promise object contains the BluetoothDeviceobject indicating information about the devices.

Data object

BluetoothDevice object

Property	Type	Required	Description
id	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.

Property	Type	Required	Description
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: string )	Promise <BluetoothRemoteGATTService>	Acquires the primary service of the GATT server. Specify a 128-bit UUID 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.

Property	Type	Required	Description
device	Object	Required	BluetoothDevice object
uuid	String	Required	GATT Service UUID

Method	Return value	Description
getCharacteristic( characteristicUUID: string )	Promise <BluetoothRemoteGATTCharacteristic>	Acquires the characteristics. Specify a 128-bit UUID 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.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// Don't filter devices receiving advertisement packets
liff.bluetooth.requestDevice().then(device => {
    const listener = (e) => {
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

    device.watchAdvertisements();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

// Filter devices receiving advertisement packets
liff.bluetooth.requestDevice({
        filters: [
            {
                deviceId: 't99137fe055dd4980b40f6ac526da7b0b' // ID of desired bluetooth device (BluetoothDevice.id)
            }
        ]
    }).then(device => {
    const listener = (e) => {
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

    device.watchAdvertisements();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

BluetoothRemoteGATTCharacteristic object

The BluetoothRemoteGATTCharacteristic object is used to read or write the characteristic of the devices, and also to start or stop a notification.

Property	Type	Required	Description
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: BufferSource )	Promise <void>	Writes the 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 characteristicvaluechangedevent 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.

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.

Property	Type	Required	Description
device	Object	Required	BluetoothDevice object
name	String	Optional	device name
rssi	Number	Optional	RSSI
manufacturerData	Object	Optional	Mapobject. Data in which the Company Identifier Code is mapped to the DataView object.

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// Read and write characteristic values from LIFF app
device.gatt
    .connect()
    .then(async () => {
        const service = await device.gatt.getPrimaryService(
            '01234567-0123-0123-0123-012345678901'
        );
        const characteristic = await service.getCharacteristic(
            '01234567-0123-0123-0123-012345678902'
        );
        const value = await characteristic.readValue();

        // suppose we know it is a string, we can decode it
        // here we use TextDecoder for simplicity, you should add a polyfill for compatibility
        const stringValue = new TextDecoder().decode(value);

        // to write string 'liff' into the characteristic
        // here we use TextEncoder for simplicity, you should add a polyfill for compatibility
        await characteristic.writeValue(new TextEncoder().encode('liff'));
    })
    .catch(e => {
        console.log(e.code + ':' + e.message);
    });

// Notify change in characteristic value from LINE Things device
device.gatt.connect().then(async () => {
    const service = await device.gatt.getPrimaryService('01234567-0123-0123-0123-012345678901');
    const characteristic = await service.getCharacteristic('01234567-0123-0123-0123-012345678903');
    characteristic.addEventListener('characteristicvaluechanged', (e) => {
        // suppose we know it is a 16-bit integer value
        console.log('value changed to:' + e.target.value.getInt16();
    });

    await characteristic.startNotifications();
}).catch(e => {
    console.log(e.code + ':' + e.message);
});

gattserverdisconnected event

If the Bluetooth connection is disconnected due to various reasons, the gattserverdisconnected event occurs. Be sure to register the event listener.

characteristicvaluechanged event

If a characteristic is changed, the characteristicvaluechanged event occurs.

liff.bluetooth.referringDevice

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

// No sample code available

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// Register event listener for gattserverdisconnected event
liff.bluetooth
    .requestDevice()
    .then(device => {
        device.addEventListener('gattserverdisconnected', () => {
            console.log('device gatt is disconnected');
        });

        window.gatt.connect();
    })
    .catch(e => {
        console.log(e.code + ':' + e.message);
    });

Server API

Preparing a channel access token

You need a channel access token to use the LIFF server API.

On a Messaging API channel

Issue a channel access token on the LINE Developers console.

Go to your Messaging API channel settings and select the Messaging API tab. Then, under Channel access token (long-lived), click Issue. The access token is displayed in the console.

This token has a very long lifetime, so don't worry about it expiring.

On a LINE Login channel

Send an HTTP POST request to the /v2/oauth/accessToken endpoint to issue a channel access token for your LINE Login channel.

For more information, see Issue channel access token in the Messaging API reference.

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.

HTTP request

POST https://api.line.me/liff/v1/apps

Request headers

Request header	Description
Authorization	Bearer {channel access token} For more information on channel access tokens, see Preparing a channel access token.
Content-Type	application/json

Request body

Property	Type	Required	Description
view.type	String	Required	Size of the LIFF app view. Specify one of the following values: compact: 50% of device screen height. tall: 80% of device screen height. full: 100% of device screen height.
view.url	String	Required	URL of the server on which the LIFF app is deployed (endpoint URL). The URL scheme must be https.
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.

curl -X POST https://api.line.me/liff/v1/apps \
-H "Authorization: Bearer {channel access token}" \
-H "Content-Type: application/json" \
-d '{
  "view":{
    "type":"full",
    "url":"https://example.com/myservice"
  },
  "description": "Service Example",
  "features": {
    "ble": true
  }
}'

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// No sample code available

Response

Returns the status code 200 and a JSON object with the following properties.

Property	Type	Description
liffId	String	LIFF app ID

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.

{
  "liffId":"{liffId}"
}

Update LIFF app settings

Partially updates LIFF app settings.

HTTP request

PUT https://api.line.me/liff/v1/apps/{liffId}

Request headers

Request header	Description
Authorization	Bearer {channel access token} For more information on channel access tokens, see Preparing a channel access token.
Content-Type	application/json

Path parameters

Parameter	Description
liffId	ID of the LIFF app to be updated

Request body

Property	Type	Required	Description
view.type	String	Optional	Size of the LIFF app view. Specify one of the following values: compact: 50% of the screen height of the device. tall: 80% of the screen height of the device. full: 100% of the screen height of the device.
view.url	String	Optional	URL of the LIFF app (endpoint URL). The URL scheme must be https.
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.

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.

curl -X PUT https://api.line.me/liff/v1/apps/{liffId} \
-H "Authorization: Bearer {channel access token}" \
-H "Content-Type: application/json" \
-d '{
  "view": {
    "url":"https://new.example.com"
  }
}'

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// No sample code available

Get all LIFF apps

Gets information on all the LIFF apps registered in the channel.

HTTP request

GET https://api.line.me/liff/v1/apps

Request headers

Request header	Description
Authorization	Bearer {channel access token} For more information on channel access tokens, see Preparing a channel access token.

curl -X GET https://api.line.me/liff/v1/apps \
-H "Authorization: Bearer {channel access token}"

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// No sample code available

Response

Returns the status code 200 and a JSON object with the following properties.

Property	Type	Description
apps	Array of objects	Array of LIFF app objects

LIFF app object

Property	Type	Description
liffId	String	LIFF app ID
view.type	String	Size of the LIFF app view. One of the following values is contained: compact: 50% of the screen height of the device. tall: 80% of the screen height of the device. full: 100% of the screen height of the device.
view.url	String	URL of the LIFF app (endpoint URL)
description	String	Name of the LIFF app
features.ble	Boolean	true if the LIFF app supports Bluetooth® Low Energy for LINE Things. false otherwise.

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.

{
  "apps":[
    {
      "liffId":"{liffId}",
      "view":{
        "type":"full",
        "url":"https://example.com/myservice"
      },
      "description": "Happy New York"
    },
    {
      "liffId":"{liffId}",
      "view":{
        "type":"tall",
        "url":"https://example.com/myservice2"
      },
      "features": {
        "ble": true
      }
    }
  ]
}

Delete LIFF app from a channel

Deletes a LIFF app from a channel.

HTTP request

DELETE https://api.line.me/liff/v1/apps/{liffId}

Request headers

Request header	Description
Authorization	Bearer {channel access token} For more information on channel access tokens, see Preparing a channel access token.

Path parameters

Parameter	Description
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.

curl -X DELETE https://api.line.me/liff/v1/apps/{liffId} \
-H "Authorization: Bearer {channel access token}"

// No sample code available

# No sample code available

// No sample code available

// No sample code available

# No sample code available

# No sample code available

// No sample code available