API reference for the JavaScript SDK

You can develop your Channel Web Application using standard webpage building tools like HTML, JavaScript, and CSS. You can integrate your application with LINE using the JavaScript SDK. This page explains how to use the APIs provided by the JavaScript SDK.

Getting access tokens

An access token is required when using REST APIs. Access token strings cannot be retrieved directly from the JavaScript SDK. To retrieve access tokens, the encrypted string with the access token must be retrieved and decoded on the server.

Getting encrypted strings

An encrypted string sets the cookie named “cc”. The encrypted string is sent implicitly to your web server when accessing the entry URL page.

Getting Channel secret strings

A Channel secret string is required to decode the encrypted string and retrieve access tokens. To get a Channel secret string, follow the steps below:

  1. Click Channels at the top right and log in to the Channel Console.
  2. Select your Channel from the list on the left.
  3. Copy the string found in the Channel secret column.

Getting access tokens

The encrypted string will be decoded using the Channel secret as a symmetric-key. The algorithm used is AES, the block size is 128 bit, the encryption mode is ECB, and the padding is PKCS#5. The Channel secret string will be interpreted as a hexadecimal byte string and used as the symmetric-key. The encrypted string follows Base64 encoding and will be restored once it has been decoded.

The following is an example of how the decoding process works.

Java
import org.apache.commons.codec.binary.Base64;

private byte[] hexToBytes(String hex) throws Exception {
  byte[] bytes = new byte[hex.getBytes("UTF-8").length / 2];
  for (int i = 0; i < bytes.length; i++) {
    bytes[i] = (byte)Integer.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
  }
  return bytes;
}
String source = ...; // encrypted string
SecretKeySpec secretKey = new SecretKeySpec(hexToBytes("YOUR_CHANNEL_SECRET"), "AES");
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, secretKey);
byte[] decoded = Base64.decodeBase64(source);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");
// Do something...
Ruby
source = ... # encrypted string
cipher = OpenSSL::Cipher::Cipher.new('AES-128-ECB')
cipher.decrypt
cipher.key = ['YOUR_CHANNEL_SECRET'].pack('H*')
decoded = Base64.decode64(source)
decrypted = cipher.update(decoded) + cipher.final
# Do something...
PHP
$source = ...; // encrypted string
$secretKey = pack('H*', "YOUR_CHANNEL_SECRET");
$decoded = base64_decode($source);
$decrypted = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $secretKey, $decoded, MCRYPT_MODE_ECB);
// Do something...

The decoded string (the value for the “decrypted” variable in the example above) is made up of the MID, access token string, access token expiration date (UNIX timestamp), and the refresh token string. Each part of the string is separated by a period. Use the periods to separate the string into pieces, then use the access token obtained to access the REST API.

After retrieving the access token, you can use REST APIs from your server. For more information, see REST APIs.

Getting the JavaScript SDK version number

This function retrieves the version number of the JavaScript SDK.

Function specifications

Function LCS.Interface.getLCSVersion
Parameters None
Return value Version number

Example

var version = LCS.Interface.getLCSVersion();
// Do something...

Checking the LINE app version number

The LCS.Interface.checkAppEnv checks the version of the LINE app. Set the desired version of the LINE app in the second parameter. If the version of the LINE app is older than what is set, a pop-up will prompt the user to update their LINE app.

Function specifications

Function LCS.Interface.checkAppEnv
Parameters 1 Callback function that receives the result.
Parameters 2 Object that sets the version number to be used for the app version check.
Return value None

The second parameter is used to set an object that determines the version of the LINE app that your application requires. The details of that object are as follows.

{
  type: "VERSION_CHECK",
  value: {
    reqVersion: "4.0.0"
  }
}

If the version of the LINE app installed on the user’s device is the same or later than the version set in the reqVersion property of the object above, the callback function set in the first parameter will be called. An object containing the version number of the LINE app will be passed as a parameter to the callback function.

Example

LCS.Interface.checkAppEnv(function(data)	{
  var result = data.result; // Always true
  var type = data.type; // Always "VERSION_CHECK"
  var version = data.value.appVersion; // the version number of LINE app
  // Do something...
}, {
  type: "VERSION_CHECK",
  value: {
    reqVersion: "4.0.0"
  }
});
// Do something...

Getting profiles

The LCS.Interface.getProfile function retrieves profile information for users logged in to the LINE app.

Function specifications

Function LCS.Interface.getProfile
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Return value None
Permission required PROFILE

The callback function set in the first parameter is called once the data has been retrieved. An object containing information about the user logged in to the LINE app is passed to the callback function. The object’s properties are listed below.

Property Description
id MID – ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.
pictureUrl URL of the user’s profile image.

If the data is not retrieved and an error occurs, the callback function set in the second parameter is called. Make sure proper error handling has been implemented inside this callback function.

Example

LCS.Interface.getProfile(function(data) {
  var mid = data.id;
  var displayName = data.displayName;
  var statusMessage = data.statusMessage;
  var pictureUrl = data.pictureUrl;
  // Do something...
}, function() {
  // Do something for this error...
});

Getting friend lists

This function is used to get a list of information about the friends the user has added on LINE.

Function specifications

Function LCS.Interface.getLineFriendList
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object used to set the conditions for retrieving the desired information.
Return value None
Permission required FRIEND_LIST

The third parameter is used to set the number of friends to retrieve in the list and the sorting method for the list. The properties which can be set are listed below.

Property Description Value applied when omitted
sort Sort order of the list. Use “asc” for ascending order, and “desc” for descending order. "asc"
start Location from which to start retrieving the list of user’s friends 1
display Number of friends whose data you want to retrieve. The max value is 50. 10
bot Boolean used to set whether or not to include Bots in the list of retrieved friends. false

The callback function set in the first parameter is called once the list has been successfully retrieved. An object containing the friends’ information will be passed to the callback function. The object’s properties are listed below.

Property Description
total Total number of friends.
start Location to start retrieving friends from. The first location is 1.
display The number of friends retrieved.
contacts An array of objects contains the profile information for each friend.

The following properties belong to each object in the contacts property array. Each object contains a friend’s profile info.

Property Description
id MID – ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getLineFriendList(function(data) {
  var total = data.total;
  var start = data.start;
  var display = data.display;
  // Do something...
  var contacts = data.contacts;
  for (var i = 0; i < contacts.length; i++) {
    var mid = contacts[i].id;
    var displayName = contacts[i].displayName;
    var statusMessage = contacts[i].statusMessage;
    // Do something...
  }
}, function() {
  // Do something for this error...
}, {
  sort: "asc",
  start: 1,
  display: 10,
  bot: false
});

Getting friend counts

This function is used to get the number of friends a user has added on LINE.

Function specifications

Function LCS.Interface.getTotalLineFriendListCount
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Return value None
Permission required FRIEND_LIST

If the data is properly retrieved, the callback function set in the first parameter will be called. The number of friends the user has added will be passed to that callback function as a parameter.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getTotalLineFriendListCount(function(friendListCount) {
  // Do something with the friendListCount...
}, function() {
  // Do something for this error...
});

Getting friend profiles

This function is used to get the profile information from a specific friend of the user.

Function specifications

Function LCS.Interface.getLineFriend
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object containing the MID of the retrieved friend.
Return value None
Permission required FRIEND_LIST

The third parameter is used to define the object that contains the MID of the friend you wish to retrieve.

Property Description
mid MID of the friend you want to retrieve.

The callback function set in the first parameter will be called when the data has been retrieved. An object containing the friend’s information will be passed to the callback function. The object’s properties are listed below.

Property Description
id MID - An ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getLineFriend(function(data) {
  var mid = data.id;
  var displayName = data.displayName;
  var statusMessage = data.statusMessage;
  // Do something...
}, function() {
  // Do something for this error...
}, {
  mid: "u12345abcde..."
});

Searching for friends

This function is used to search for friends by name, and retrieve the profile information of the friends who match the search conditions.

Function specifications

Function LCS.Interface.searchLineFriend
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object that defines the conditions used to retrieve the data.
Return value None
Permission required FRIEND_LIST

The third parameter is used to set the number of friends to obtain in the list as well as the sorting method for the list. The properties that can be set are listed below.

Property Description Value applied When omitted
name Condition to search friends by a name.
sort Sort order of the list. Use “asc” for ascending order, and “desc” for descending order. "asc"
start Location from which to start retrieving the list of user’s friends 1
display Number of friends whose data you wish to obtain. The max value is 50. 10
bot Boolean used to set whether or not to include bots in the list of retrieved friends. false

The callback function set in the first parameter will be called when the data has been retrieved. An object containing the friends’ information will be passed to the callback function. The object’s properties are listed below.

Property Description
total Total number of friends.
start Location to start retrieving friends from. The first location is 1.
display Number of friends retrieved.
contacts An array of objects contains the profile information for each friend.

The following properties belong to each object in the contacts property array. Each object contains a friend’s profile info.

Property Description
id MID – An ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getSearchLineFriend(function(data) {
  var total = data.title;
  var start = data.start;
  var display = data.display;
  // Do something...
  var contacts = data.contacts;
  for (var i = 0; i < contacts.length; i++) {
    var mid = contacts[i].id;
    var displayName = contacts[i].displayName;
    var statusMessage = contacts[i].statusMessage;
    // Do something...
  }
}, function() {
  // Do something for this error...
}, {
  name: "John",
  sort: "asc",
  start: 1,
  display: 10,
  bot: false
});

Getting friend lists using MID lists

This function is used to get friends’ profile information using their MIDs.

Function specifications

Function LCS.Interface.getLineFriendListFromMIDs
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object that defines the conditions used to retrieve the data.
Return value None
Permission required FRIEND_LIST

The third parameter is used to set the array of MIDs of the friends you want to retrieve. The properties that can be set are listed below.

Property Description
aMid Array of MIDs of the friends to be retrieved

The callback function set in the first parameter will be called when the data has been retrieved. An array of the object containing the friends’ information will be passed to the callback function. Each object contains a friend’s profile info.

Property Description
id MID – An ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getLineFriendListFromMIDs(function(data) {
  var total = data.title;
  var start = data.start;
  var display = data.display;
  // Do something...
  var contacts = data.contacts;
  for (var i = 0; i < contacts.length; i++) {
    var mid = contacts[i].id;
    var displayName = contacts[i].displayName;
    var statusMessage = contacts[i].statusMessage;
    // Do something...
  }
}, function() {
  // Do something for this error...
}, {
  aMid: ["u1345abcde", ...]
});

Getting group lists

This function is used to retrieve lists of groups.

Function specifications

Function LCS.Interface.getLineGroupList
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object that defines the conditions used to retrieve the data.
Return value None
Permission required GROUP

The third parameter is used to set the number of groups to retrieve in the list as well as the sorting method for the list. The properties that can be set are listed below.

Property Description Value applied when omitted
sort Sort order of the list. Use “asc” for ascending order, and “desc” for descending order. "asc"
start Location from which to start retrieving groups from the list. 1
display Number of groups whose data you want to retrieve. The max value is 50. 10

The callback function set in the first parameter is called when the data has been retrieved. An object containing the groups information will be passed to the callback function. The object’s properties are listed below.

Property Description
total Total number of groups.
start Location to start retrieving groups from. The first location is 1.
display The number of groups retrieved.
groups An array of objects contains the profile information for each group.

The following properties belong to each object in the groups property array. Each object contains info about that group.

Property Description
id MID - ID string used to identify groups
name Name of the group
isAccepted Flag showing whether user has already accepted the group or not.
membersCount Count of members who joined the group.
members Array of the object representing the profile information of the member.
inviteesCount Count of users invited to the group.
invitees Array of the object representing the profile information of the users invited.

The following properties belong to each object in the members and invitees property array. Each object contains a user's profile info.

Property Description
id MID - ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getLineGroupList(function(data) {
  var total = data.title;
  var start = data.start;
  var display = data.display;
  // Do something...
  var groups = data.groups;
  for (var i = 0; i < groups.length; i++) {
    var mid = groups[i].id;
    var name = groups[i].name;
    // Do something...
  }
}, function() {
  // Do something for this error...
}, {
  sort: "asc",
  start: 1,
  display: 10
});

Getting group counts

This function is used to get the total number of groups on LINE.

Function specifications

Function LCS.Interface.getTotalLineGroupListCount
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Return value None
Permission required GROUP

The callback function set in the first parameter is called when the data has been retrieved. The number of groups will be passed to the callback function as a parameter.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getTotalLineGroupListCount(function(groupListCount) {
  // Do something with the groupListCount...
}, function() {
  // Do something for this error...
});

Getting group member lists

This function is used to get a list of information about a group's members.

Function specifications

Function LCS.Interface.getLineGroupMemberList
Parameters 1 Callback function that receives the result.
Parameters 2 Callback function called when an error occurs.
Parameters 3 Object that defines the conditions used to retrieve the data.
Return value None
Permission required GROUP

The third parameter is used to set the ID of the group you want to retrieve, the number of group members you want to retrieve, and the sorting method for the list. The properties that can be set are listed below.

Property Description Value applied when omitted
id ID string of the group you want to retrieve.
sort Sort order of the list. Use “asc” for ascending order, and “desc” for descending order. "asc"
start Location from which to start retrieving group members from the list of members 1
display Number of group members whose data you want to retrieve. The max value is 50. 10

The callback function set in the first parameter is called when the data has been retrieved. An object containing the users' information will be passed to the callback function. The object's properties are listed below.

Property Description
total Total number of users in the group.
start Location to start retrieving users from the group. The first location is 1.
display The number of users retrieved.
contacts An array of objects containing the profile information of each user.

The following properties belong to each object in the contacts property array. Each object contains a user's profile info.

Property Description
id MID - ID string used to identify users.
displayName Nickname
statusMessage Status message registered by the user.

If the data is unable to be properly retrieved and an error occurs, the callback function set in the second parameter will be called. Make sure you have implemented proper error handling inside this callback function.

Example

LCS.Interface.getLineGroupMemberList(function(data) {
  var total = data.title;
  var start = data.start;
  var display = data.display;
  // Do something...
  var contacts = data.contacts;
  for (var i = 0; i < contacts.length; i++) {
    var mid = contacts[i].id;
    var displayName = contacts[i].displayName;
    var statusMessage = contacts[i].statusMessage;
    // Do something...
  }
}, function() {
  // Do something for this error...
}, {
  id: "u12345abcde...",
  sort: "asc",
  start: 1,
  display: 10
});