# 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

    Code

    message

    String

    Message. Returned when the defined message exists.

    # Error details

    Code Description
    INIT_FAILED Failed to init LIFF SDK.
    INVALID_ARGUMENT The argument is invalid.
    UNAUTHORIZED
    • The user did not authorize.
    • Try call server api without access token.
    FORBIDDEN You don't have enough permission.
    INVALID_CONFIG You need to define liffId for LINE login.
    INVALID_ID_TOKEN Failed to verify the ID token.
    INVALID_ARGUMENT An invalid argument was specified.
    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.

    # liff.init()

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

    Note

    When the LIFF app is started, it immediately opens the endpoint URL specified in Adding a LIFF app to your channel. Call liff.init() before changing the URL. If you call liff.init() after changing the URL, INIT_FAILED will be returned.

    Example request

      # Syntax

      liff.init(
  config: { liffId: string },
  successCallback?: Function,
  errorCallback?: Function
)

      # Arguments

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

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

      # Arguments

      None

      # Return value

      String containing language settings specified in navigator.language in the LIFF app's running environment.

      # liff.getVersion()

      Gets the version of the LIFF SDK.

      # Syntax

      liff.getVersion()

      # Arguments

      None

      # Return value

      The version of the LIFF SDK is returned as a string.

      # liff.isInClient()

      Determines whether the LIFF app is running in LINE's in-app browser.

      # Syntax

      liff.isInClient()

      # Arguments

      None

      # Return value

      • true: Running in LINE browser
      • false: Running in external browser

      # liff.isLoggedIn()

      Checks whether the user is logged in.

      Example request

        # Syntax

        liff.isLoggedIn()

        # Arguments

        None

        # Return value

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

        # liff.login()

        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?: {
    redirectUri?: string
  }
)

          # Arguments

          loginConfig.redirectUri

          String

          Optional

          URL to open in the LIFF app after LINE Login. If omitted, the user is redirected to the page that displays when the LIFF app is opened (front page).

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

            Note

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

              Gets the screen type (1-on-1 chat, group, or room) and the ID that identifies the screen from which the LIFF application is launched.

              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
                • room: Room
                • group: Group
                • none: A screen other than a 1-on-1 chat, room, or group. For example, Wallet tab.

                viewType

                String

                Size of the LIFF app view. One of:

                • compact
                • tall
                • full

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

                userId

                String

                User ID. Included when the type property is utou, room, or group.

                utouId

                String

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

                roomId

                String

                Room ID. Included when the type property is room.

                groupId

                String

                Group ID. Included when the type property is group.

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

                  Gets the payload of the ID token that's automatically acquired by liff.init(). The payload includes the user display name, profile image URL, and email address.

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

                  # Syntax

                  liff.getDecodedIDToken()

                  # Arguments

                  None

                  # Return value

                  Gets a Promise object containing 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 Promise object containing null

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

                  Example ID token payload

                    # liff.getProfile()

                    Gets the current user's profile.

                    Example request

                      # Syntax

                      liff.getProfile()

                      # Arguments

                      None

                      # Return value

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

                      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.

                      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

                          Gets a Promise object that specifies the status of the friendship.

                          friendFlag

                          Boolean

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

                          Example return value

                            # 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:  Array<Message>
)

                              # Arguments

                              messages

                              Array of objects

                              Required

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

                              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

                              There is no return value if the message is sent successfully.

                              This method internally calls the LINE platform using Fetch. For error handling, refer to the Fetch 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.openWindow()

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

                              Example request

                                # Syntax

                                liff.openWindow(params)

                                # Arguments

                                # params object

                                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

                                # 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

                                  A Promise object containing the string read by LINE's QR code reader is returned.

                                  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(pluginList: Array<String>): Promise<void>

                                      # 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

                                      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.

                                      # 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(): Promise<Boolean>

                                        # Arguments

                                        None

                                        # Return value

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

                                        # 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?: RequestDeviceOptions): Promise<BluetoothDevice>;

                                          # 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. The Promise object contains the BluetoothDeviceobject indicating information about the devices.

                                          # Data object
                                          # BluetoothDevice object

                                          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.

                                          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.

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

                                          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.