# LIFF v2 API reference

# Common specifications

# 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 a LIFF 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 SDK errors

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

# LiffError object

# Error details

# LIFF SDK properties

# liff.id

const liffId = "my-liff-id";
liff.init({ liffId });

// liff.id equals to liffId

# liff.ready

liff.ready.then(() => {
  // do something you want when liff.init finishes
});

# Initialization

# liff.init()

liff
  .init({
    liffId: "1234567890-AbcdEfgh", // Use own liffId
  })
  .then(() => {
    // Redirect to another page after the returned Promise object has been resolved
    window.location.replace(location.href + "/entry/");
  });

liff
  .init({
    liffId: "1234567890-AbcdEfgh", // Use own liffId
  })
  .then(() => {
    ga("send", "pageview");
  });

// Using a Promise object
liff
  .init({
    liffId: "123456-abcedfg", // Use own liffId
  })
  .then(() => {
    // Start to use liff's api
  })
  .catch((err) => {
    // Error happens during initialization
    console.log(err.code, err.message);
  });

// Using a callback
liff.init({ liffId: "123456-abcedfg" }, successCallback, errorCallback);

# Syntax

liff.init(config, successCallback, errorCallback);

# Arguments

# Return value

Returns a Promise object.

# Error response

When the Promise is rejected, LiffError is passed.

# Getting environment

# liff.getOS()

# Syntax

liff.getOS();

# Arguments

None

# Return value

The environment in which the user is running the LIFF app is returned as a string. Since the return value is based on the name of the OS in the user agent string, the return value is independent of the browser type (LIFF browser, LINE's in-app browser, external browser).

For example, if the user is using iOS, ios will be returned, regardless of whether the user is using LIFF browser or Safari.

For more information about LIFF app supported operating systems and browsers, see Operating environment.

# liff.getAppLanguage()

Gets the language setting of the LINE app running the LIFF app.

# Conditions of use

LIFF SDK versions v2.24.0 or later

# Operating conditions

All of the following conditions must be met for the liff.getAppLanguage() method to work correctly:

• The LIFF application is running on the LIFF browser.
• The LINE app version is 14.11.0 or later.

If the above conditions aren't met, the liff.getAppLanguage() method behaves the same as the liff.getLanguage() method.

# Syntax

liff.getAppLanguage();

# Arguments

None

# Return value

The language setting of the LINE app running the LIFF app is returned as a string that follows RFC 5646 (opens new window).

# liff.getLanguage()

Gets the language setting 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()

# Syntax

liff.getVersion();

# Arguments

None

# Return value

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

# liff.getLineVersion()

# Syntax

liff.getLineVersion();

# Arguments

None

# Return value

If a user opens the LIFF app using a LIFF browser, the LINE version of the user is returned as a string. If a user opens the LIFF app using an external browser, null is returned.

# liff.getContext()

const context = liff.getContext();
console.log(context);

# Syntax

liff.getContext();

# Arguments

None

# Return value

{
  "type": "utou",
  "utouId": "e2bff570-...",
  "userId": "U850014438e...",
  "liffId": "123456-abcedfg",
  "viewType": "full",
  "endpointUrl": "https://example.com/",
  "accessTokenHash": "EVWYWo1yYA...",
  "availability": {
    "shareTargetPicker": {
      "permission": true,
      "minVer": "10.3.0"
    },
    "multipleLiffTransition": {
      "permission": true,
      "minVer": "10.18.0"
    },
    "subwindowOpen": {
      "permission": true,
      "minVer": "11.7.0"
    },
    "scanCode": {
      "permission": false,
      "minVer": "9.4.0",
      "unsupportedFromVer": "9.19.0"
    },
    "scanCodeV2": {
      "permission": true,
      "minVer": "11.7.0",
      "minOsVer": "14.3.0"
    },
    "getAdvertisingId": {
      "permission": false,
      "minVer": "7.14.0"
    },
    "addToHomeScreen": {
      "permission": false,
      "minVer": "9.16.0"
    },
    "bluetoothLeFunction": {
      "permission": false,
      "minVer": "9.14.0",
      "unsupportedFromVer": "9.19.0"
    },
    "skipChannelVerificationScreen": {
      "permission": false,
      "minVer": "11.14.0"
    },
    "addToHomeV2": {
      "permission": false,
      "minVer": "13.20.0"
    },
    "addToHomeHideDomain": {
      "permission": false,
      "minVer": "13.20.0"
    },
    "addToHomeLineScheme": {
      "permission": false,
      "minVer": "13.20.0"
    }
  },
  "scope": [
    "chat_message.write",
    "openid",
    "profile"
  ],
  "menuColorSetting": {
    "adaptableColorSchemes": [
      "light"
    ],
    "lightModeColor": {
      "iconColor": "#111111",
      "statusBarColor": "black",
      "titleTextColor": "#111111",
      "titleSubtextColor": "#B7B7B7",
      "titleButtonColor": "#111111",
      "titleBackgroundColor": "#FFFFFF",
      "progressBarColor": "#06C755",
      "progressBackgroundColor": "#FFFFFF"
    },
    "darkModeColor": {
      "iconColor": "#FFFFFF",
      "statusBarColor": "white",
      "titleTextColor": "#FFFFFF",
      "titleSubtextColor": "#949494",
      "titleButtonColor": "#FFFFFF",
      "titleBackgroundColor": "#111111",
      "progressBarColor": "#06C755",
      "progressBackgroundColor": "#111111"
    }
  },
  "miniDomainAllowed": false,
  "permanentLinkPattern": "concat"
}

{
  "type": "external",
  "liffId": "123456-abcedfg",
  "endpointUrl": "https://example.com/",
  "accessTokenHash": "EVWYWo1yYA...",
  "availability": {
    "shareTargetPicker": {
      "permission": true,
      "minVer": "10.3.0"
    },
    "multipleLiffTransition": {
      "permission": true,
      "minVer": "10.18.0"
    },
    "subwindowOpen": {
      "permission": true,
      "minVer": "11.7.0"
    },
    "scanCode": {
      "permission": true,
      "minVer": "9.4.0",
      "unsupportedFromVer": "9.19.0"
    },
    "scanCodeV2": {
      "permission": true,
      "minVer": "11.7.0",
      "minOsVer": "14.3.0"
    },
    "getAdvertisingId": {
      "permission": false,
      "minVer": "7.14.0"
    },
    "addToHomeScreen": {
      "permission": false,
      "minVer": "9.16.0"
    },
    "bluetoothLeFunction": {
      "permission": false,
      "minVer": "9.14.0",
      "unsupportedFromVer": "9.19.0"
    },
    "skipChannelVerificationScreen": {
      "permission": false,
      "minVer": "11.14.0"
    },
    "addToHomeV2": {
      "permission": false,
      "minVer": "13.20.0"
    },
    "addToHomeHideDomain": {
      "permission": false,
      "minVer": "13.20.0"
    },
    "addToHomeLineScheme": {
      "permission": false,
      "minVer": "13.20.0"
    }
  },
  "scope": [
    "chat_message.write",
    "openid",
    "profile"
  ],
  "menuColorSetting": {
    "adaptableColorSchemes": [
      "light"
    ],
    "lightModeColor": {
      "iconColor": "#111111",
      "statusBarColor": "black",
      "titleTextColor": "#111111",
      "titleSubtextColor": "#B7B7B7",
      "titleButtonColor": "#111111",
      "titleBackgroundColor": "#FFFFFF",
      "progressBarColor": "#06C755",
      "progressBackgroundColor": "#FFFFFF"
    },
    "darkModeColor": {
      "iconColor": "#FFFFFF",
      "statusBarColor": "white",
      "titleTextColor": "#FFFFFF",
      "titleSubtextColor": "#949494",
      "titleButtonColor": "#FFFFFF",
      "titleBackgroundColor": "#111111",
      "progressBarColor": "#06C755",
      "progressBackgroundColor": "#111111"
    }
  },
  "miniDomainAllowed": false,
  "permanentLinkPattern": "concat"
}

# availability object

{
  "shareTargetPicker": {
    "permission": true,
    "minVer": "10.3.0"
  }
}

# Common properties of the availability object

# menuColorSetting object

{
  "adaptableColorSchemes": [
    "light"
  ],
  "lightModeColor": {
    "iconColor": "#111111",
    "statusBarColor": "black",
    "titleTextColor": "#111111",
    "titleSubtextColor": "#B7B7B7",
    "titleButtonColor": "#111111",
    "titleBackgroundColor": "#FFFFFF",
    "progressBarColor": "#06C755",
    "progressBackgroundColor": "#FFFFFF"
  },
  "darkModeColor": {
    "iconColor": "#FFFFFF",
    "statusBarColor": "white",
    "titleTextColor": "#FFFFFF",
    "titleSubtextColor": "#949494",
    "titleButtonColor": "#FFFFFF",
    "titleBackgroundColor": "#111111",
    "progressBarColor": "#06C755",
    "progressBackgroundColor": "#111111"
  }
}

# Common properties of the menuColorSetting object

# liff.isInClient()

# Syntax

liff.isInClient();

# Arguments

None

# Return value

• true: Running in LIFF browser
• false: Running in external browser or LINE's in-app browser

# liff.isLoggedIn()

if (liff.isLoggedIn()) {
  // The user can use an API that requires an access token, such as liff.getProfile().
}

# Syntax

liff.isLoggedIn();

# Arguments

None

# Return value

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

# liff.isApiAvailable()

// Check if shareTargetPicker is available
if (liff.isApiAvailable('shareTargetPicker')) {
  liff.shareTargetPicker([
    {
      type: "text",
      text: "Hello, World!"
    }
  ])
    .then(
      console.log("ShareTargetPicker was launched")
    ).catch(function(res) {
      console.log("Failed to launch ShareTargetPicker")
    })
}

// Check if multiple liff transtion feature is available
if (liff.isApiAvailable('multipleLiffTransition')) {
  window.location.href = "https://line.me/{liffId}", // URL for another LIFF app
}

# Syntax

liff.isApiAvailable(apiName);

# Arguments

# Return value

Returns whether the specified API is available in the current environment. If available, true is returned. If not, false is returned. Examples of false returned are as follows:

• If the LIFF app was launched with a LINE version that doesn't support the API
• If the LIFF app was launched in an external browser, even though the API isn't available in an external browser
• If the terms and conditions haven't been accepted, even though you must accept them to use the API
• If the user isn't logged in, even though the user must be logged in to use the API
• If the access token is expired, even though the access token must be valid to use the API

# Authentication

# liff.login()

if (!liff.isLoggedIn()) {
  liff.login({ redirectUri: "https://example.com/path" });
}

# Syntax

liff.login(loginConfig);

# Arguments

# Return value

None

# liff.logout()

if (liff.isLoggedIn()) {
  liff.logout();
}

# Syntax

liff.logout();

# Arguments

None

# Return value

None

# liff.getAccessToken()

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

# Syntax

liff.getAccessToken();

# Arguments

None

# Return value

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

# liff.getIDToken()

liff
  .init({
    liffId: "123456-abcedfg", // Use own liffId
  })
  .then(() => {
    const idToken = liff.getIDToken();
    console.log(idToken); // print idToken object
  });

# Syntax

liff.getIDToken();

# Argument

None

# Return value

Returns an ID token.

# liff.getDecodedIDToken()

liff
  .init({
    liffId: "123456-abcedfg", // Use own liffId
  })
  .then(() => {
    const idToken = liff.getDecodedIDToken();
    console.log(idToken); // print decoded idToken object
  });

# Syntax

liff.getDecodedIDToken();

# Arguments

None

# Return value

{
  "iss": "https://access.line.me",
  "sub": "U1234567890abcdef1234567890abcdef ",
  "aud": "1234567890",
  "exp": 1504169092,
  "iat": 1504263657,
  "amr": ["pwd"],
  "name": "Taro Line",
  "picture": "https://sample_line.me/aBcdefg123456"
}

# liff.permission.query()

liff.permission.query("profile").then((permissionStatus) => {
  // permissionStatus = { state: 'granted' }
});

# Syntax

liff.permission.query(permission);

# Arguments

# Return value

Promise object returned.

When Promise is resolved, an object containing the following properties is returned.

# liff.permission.requestAll()

Displays the "Verification screen" for the permissions requested by LINE MINI Apps.

liff.permission.query("profile").then((permissionStatus) => {
  if (permissionStatus.state === "prompt") {
    liff.permission.requestAll();
  }
});

# Syntax

liff.permission.requestAll();

# Arguments

None

# Return value

Returns a Promise object.

# Error response

If Channel consent simplification isn't turned on, and the user has already consented to all the permissions, Promise will be rejected and LiffError will be returned.

# Profile

# liff.getProfile()

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

# Syntax

liff.getProfile();

# Arguments

None

# Return value

{
  "userId": "U4af4980629...",
  "displayName": "Brown",
  "pictureUrl": "https://profile.line-scdn.net/abcdefghijklmn",
  "statusMessage": "Hello, LINE!"
}

# liff.getFriendship()

liff.getFriendship().then((data) => {
  if (data.friendFlag) {
    // something you want to do
  }
});

# Syntax

liff.getFriendship();

# Arguments

None

# Return value

{
  "friendFlag": true
}

# Window

# liff.openWindow()

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

# Syntax

liff.openWindow(params);

# Arguments

# Return value

None

# liff.closeWindow()

liff.closeWindow();

# Syntax

liff.closeWindow();

# Arguments

None

# Return value

None

# Message

# liff.sendMessages()

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

# Syntax

liff.sendMessages(messages);

# Arguments

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

liff
  .shareTargetPicker(
    [
      {
        type: "text",
        text: "Hello, World!",
      },
    ],
    {
      isMultiple: true,
    }
  )
  .then(function (res) {
    if (res) {
      // succeeded in sending a message through TargetPicker
      console.log(`[${res.status}] Message sent!`);
    } else {
      // sending message canceled
      console.log("TargetPicker was closed!");
    }
  })
  .catch(function (error) {
    // something went wrong before sending a message
    console.log("something wrong happen");
  });

# Syntax

liff.shareTargetPicker(messages, options);

# Arguments

# Return value

Returns a Promise object.

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

  status

  String

  success

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

# Camera

# liff.scanCodeV2()

liff
  .scanCodeV2()
  .then((result) => {
    // result = { value: "" }
  })
  .catch((error) => {
    console.log("error", error);
  });

# Syntax

liff.scanCodeV2();

# Arguments

None

# Return value

Returns a Promise object.

When the string is read by the 2D code reader, Promise is resolved and the object containing the character string is passed.

# Error response

When the Promise is rejected, LiffError is passed.

# liff.scanCode()

if (liff.scanCode) {
  liff.scanCode().then((result) => {
    // result = { value: "" }
  });
}

# Syntax

liff.scanCode();

# Arguments

None

# Return value

Returns a Promise object.

When reading a string by a 2D code reader, the Promise is resolved and the object containing the string read is passed.

# Permanent link

# liff.permanentLink.createUrlBy()

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

// For example, if the endpoint URL of the LIFF app
// is https://example.com/path1?q1=v1
// and its LIFF ID is 1234567890-AbcdEfgh
liff.permanentLink
  .createUrlBy("https://example.com/path1?q1=v1")
  .then((permanentLink) => {
    // https://liff.line.me/1234567890-AbcdEfgh
    console.log(permanentLink);
  });

liff.permanentLink
  .createUrlBy("https://example.com/path1/path2?q1=v1&q2=v2")
  .then((permanentLink) => {
    // https://liff.line.me/1234567890-AbcdEfgh/path2?q=2=v2
    console.log(permanentLink);
  });

liff.permanentLink
  .createUrlBy("https://example.com/")
  .catch((error) => {
  // Error: currentPageUrl must start with endpoint URL of LIFF App.
  console.log(error);
});

# Syntax

liff.permanentLink.createUrlBy(url);

# Arguments

# Return value

Returns a Promise object.

Returns the string of the permanent link when Promise is resolved.

# Error responsee

If the URL to get the permanent link doesn't begin with the URL specified for Endpoint URL on the LINE Developers Console, Promise will be rejected and LiffError will be returned.

For example, if the URL to get the permanent link (e.g. https://example.com/) is above Endpoint URL (e.g. https://example.com/path1?q1=v1), Promise will be rejected.

# liff.permanentLink.createUrl()

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

// For example, if current location is
// /shopping?item_id=99#details
// (LIFF ID = 1234567890-AbcdEfgh)
const myLink = liff.permanentLink.createUrl();

// myLink equals "https://liff.line.me/1234567890-AbcdEfgh/shopping?item_id=99#details"

# Syntax

liff.permanentLink.createUrl();

# Arguments

None

# Return value

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

A LiffError exception is thrown if the current page URL doesn't start with the URL specified in Endpoint URL of the LINE Developers console.

# liff.permanentLink.setExtraQueryParam()

// For example, if current location is
// /food?menu=pizza
// (LIFF ID = 1234567890-AbcdEfgh)
liff.permanentLink.setExtraQueryParam("user_tracking_id=8888");
const myLink = liff.permanentLink.createUrl();

// myLink equals "https://liff.line.me/1234567890-AbcdEfgh/food?menu=pizza&user_tracking_id=8888"

# Syntax

liff.permanentLink.setExtraQueryParam(extraString);

# Arguments

# Return value

None

# LIFF plugin

# liff.use()

import liff from "@line/liff/core";
import GetOS from "@line/liff/get-os";

liff.use(new GetOS());

liff.init({
  liffId: "123456-abcedfg", // Use own liffId
});

class greetPlugin {
  constructor() {
    this.name = "greet";
  }

  install() {
    return {
      hello: this.hello,
    };
  }

  hello() {
    console.log("Hello, World!");
  }
}

liff.use(new greetPlugin());

# Syntax

liff.use(module, option);

# Arguments

# Return value

Returns the liff object.

# Internationalization

# liff.i18n.setLang()

liff.i18n.setLang("en");

# Syntax

liff.i18n.setLang(language);

# Arguments

# Return value

Returns a Promise object.

# Error response

When the Promise is rejected, LiffError is passed.

# Others

# liff.createShortcutOnHomeScreen()

// If the endpoint URL of the LINE MINI App
// is https://example.com/path1/path2
// and its LIFF ID is 1234567890-AbcdEfgh

// Example of specifying the LIFF URL
liff
  .createShortcutOnHomeScreen({
    url: "https://miniapp.line.me/1234567890-AbcdEfgh",
  })
  .then(() => { /* ... */ });

liff
  .createShortcutOnHomeScreen({
    url: "https://liff.line.me/1234567890-AbcdEfgh",
  })
  .then(() => { /* ... */ });

// Example of specifying a permanent link
liff
  .createShortcutOnHomeScreen({
    url: "https://liff.line.me/1234567890-AbcdEfgh/path3",
  })
  .then(() => { /* ... */ });

// Example of specifying the endpoint URL of the LINE MINI App
liff
  .createShortcutOnHomeScreen({
    url: "https://example.com/path1/path2",
  })
  .then(() => { /* ... */ });

// Example of specifying a URL that begins with the endpoint URL of the LINE MINI App
liff
  .createShortcutOnHomeScreen({
    url: "https://example.com/path1/path2/path3",
  })
  .then(() => { /* ... */ });

// Example of specifying a URL that results in an error
liff
  .createShortcutOnHomeScreen({
    url: "https://example.com/invalid-path",
  })
  .then(() => { /* ... */ })
  .catch((error) => {
    // invalid URL.
    console.log(error.message);
  });

# Conditions of use

To use the liff.createShortcutOnHomeScreen() method, all of the following conditions must be met:

• It's a LINE MINI App.
• The LIFF SDK version of the LINI MINI App is v2.23.0 or later.
• The LINE app version on the user's device is 13.20.0 or later.

# Operating conditions

If the OS of the user's device is iOS, the conditions for the liff.createShortcutOnHomeScreen() method to work are as follows. If this method is executed in a non-working environment, an error page will be displayed.

For example, if you execute the liff.createShortcutOnHomeScreen() method in Chrome on earlier than iOS 16.4, the following error page will be displayed:

# Syntax

liff.createShortcutOnHomeScreen(params);

# Arguments

# Return value

Returns a Promise object.

When the Add Shortcut screen is displayed, the Promise is resolved. No value is passed.

You can't confirm whether the user has actually added a shortcut to your LINE MINI app to the home screen of the user's device.

# Error response

When the Promise is rejected, LiffError is passed.