LINE Things API reference

LIFF Bluetooth LE plugin API

liff.bluetooth.getAvailability()

Checks the following requirements that determine if the Bluetooth plugin can be used:

  • Existence of Bluetooth support for the channel
  • Bluetooth settings
  • Consent is given to the LINE Things Terms of Use
  • Acquisition role of location information (Android only)

Syntax

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

Return value

The Promise object containing whether or not the Bluetooth plugin can be used (Boolean object) is returned.

Example

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

liff.bluetooth.requestDevice()

Scans the LINE Things-compatible devices that have already been linked.

If an advertisement packet is received from a device that meets the requirements, the information about the LINE Things-compatible device can be acquired.

Syntax

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

Argument

Property Type Required Description
options RequestDeviceOptions Optional The RequestDeviceOptions object for restricting the devices receiving the advertisement packets
Omit to retrieve advertisement packets from all devices.

Return value

The Promise object containing information about the LINE Things-compatible device (BluetoothDevice object) is returned.

Usage example of requestDevice() (when the filter is not specified) and the BluetoothDevice object:

liff.bluetooth.requestDevice().then(device => {
    const listener = (e) => {
      const key = e.manufacturerData.keys().next();
      console.log('compnay identifyer: 0x0' + id.value.toString(16) + ' rssi:' + e.rssi);
      const value = e.manufacturerData.get(key);
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

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

Usage example of requestDevice() (when the filter is specified) and the BluetoothDevice object:

liff.bluetooth.requestDevice({
        filters: [
            {
                deviceId: 't99137fe055dd4980b40f6ac526da7b0b' // ID of desired bluetooth device (BluetoothDevice.id)
            }
        ]
    }).then(device => {
    const listener = (e) => {
      const key = e.manufacturerData.keys().next();
      console.log('compnay identifyer: 0x0' + id.value.toString(16) + ' rssi:' + e.rssi);
      const value = e.manufacturerData.get(key);
      device.removeEventListener('advertisementreceived', listener);
    };
    device.addEventListener('advertisementreceived', listener);

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

Objects

RequestDeviceOptions object
Property Type Required Description
filters Array of LINEBluetoothRequestDeviceFilter 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
BluetoothDevice object
Property Type Required Description
id string Required Device ID of the LINE Things-compatible device
name string Optional Device name that the LINE Things-compatible device sends by the advertisement packet
gatt BluetoothRemoteGATTServer 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 Registers the event listener. Supports advertisementreceived event(*) and gattserverdisconnectedevent.
removeEventListener Deletes the already-registered event listener. Supports advertisementreceived event(*) and gattserverdisconnected event.

* The watchingAdvertisements property, and watchAdvertisements(), unwatchAdvertisements(), advertisementreceived events are functions that are implemented on experiment basis. These functions may be changed or stopped without prior notice.

BluetoothRemoteGATTServer object

To communicate with LINE Things-compatible 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 BluetoothDevice Required BluetoothDevice object
connected boolean Required true if connected, false if not connected.
Method Return value Description
connect Promise<BluetoothRemoteGATTService> Connects with the LINE Things-compatible device.
disconnect void Disconnects from the LINE Things-compatible device (GATT server).
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 BluetoothDevice 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 LINE Things-compatible devices, and also to start or stop a notification.

Property Type Required Description
service BluetoothRemoteGATTService Optional BluetoothRemoteGATTService object
uuid string Required UUID
value DataView Optional DataView
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 Registers the event listener. The characteristicvaluechanged event that includes the target property is supported.
removeEventListener Deletes the already-registered event listener. The characteristicvaluechanged eventis supported.

Note: readValue(), writeValue(), startNotifications(), and stopNotifications() verify the UUID and properties. If a UUID or property that does not exist is specified, an error occurs.

Example showing reading and writing of characteristics

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);
    });

Example showing a notification of a change in the value of a characteristic

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);
});

Events

advertisementreceived event

If an advertisement packet is received, the advertisementreceived event occurs.

Note: The advertisementreceived event is a function that is implemented on an experiment basis. This function may be changed or stopped without prior notice.

Property Type Required Description
device BluetoothDevice Required BluetoothDevice object
name string Optional LINE Things-compatible device name
rssi number Optional RSSI
manufacturerData Map<number, DataView> Optional Data set in the LINE Things-compatible device
gattserverdisconnected event

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

Example of registering the event listener of the 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);
    });
characteristicvaluechanged event

If a characteristic is changed, the characteristicvaluechanged event occurs.

Error

An error in the LIFF Bluetooth LE plugin API is returned by the LIFFError object.

LiffError object

Property Type Required Description
code String Required Code
message String Optional 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 Could not authenticate LIFF app The JWT token is either disabled or does not exist. Start LIFF on LINE. Also, be sure to specify the JWT token.
INVALID_ARGUMENT - The argument is invalid.
INTERNAL_ERROR - An internal error has occurred.
THINGS_NO_LINKED_DEVICES There are no linked devices. There is no LINE Things-compatible device.
BLUETOOTH_CONNECT_FAILED Failed to connect to device. Failed to connect to the LINE Things-compatible device.
BLUETOOTH_ALREADY_CONNECTED The device is already connected. The LINE Things-compatible device is already connected.
BLUETOOTH_CONNECTION_LOST The device has been disconnected. No LINE Things-compatible 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 charactersitic is not found in the service. The specified characteristic does not exist in the service.

Example

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

LINE Things-compatible device management API

Note: If you can't use curl, for instance because you're using Windows 10, you'll need to use another tool. For tips, see Using the REST API.

Get product ID and PSDI by device ID

Specify the device ID, and acquire the product ID and PSDI. Used when acquiring the product ID and PSDI from the device ID acquired by the device link/unlink event.

For more information about the device ID, product ID, and PSDI, see High-level workflow.

HTTP request

GET https://api.line.me/things/v1/devices/{deviceId}

Request header

Request header Description
Authorization Bearer {channel access token}

Path parameters

Parameter Description
deviceId Device ID

Request example

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

Response

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

Property Type Description
id String Device ID
productId Number Product ID
productSpecificDeviceId String PSDI. PSDI is a value that is set for each device by the developer of the LINE Things-compatible device.

Response example

{
  "id": "{deviceId}",
  "productId": {productId},
  "productSpecificDeviceId": "{PSDI}"
}

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:
  • Device not found.
  • There is no access permission.

Get device information by device ID and user ID

Specify the device ID and user ID, and acquire the device information.

HTTP request

GET https://api.line.me/things/v1/devices/{deviceId}/users/{userId}/link

Request header

Request header Description
Authorization Bearer {channel access token}

Path parameters

Parameter Description
deviceId Device ID
userId User ID
User ID is a string matching the regular expression pattern U[0-9a-f]{32}.

Request example

curl -X GET https://api.line.me/things/v1/devices/{deviceId}/users/{userId}/link \
-H "Authorization: Bearer {channel access token}" \

Response

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

Property Type Description
userId String User ID
User ID is a string matching the regular expression pattern U[0-9a-f]{32}.
device.id String Device ID
device.productId Number Product ID
device.productSpecificDeviceId String PSDI
PSDI is a value that is set for each device by the developer of the LINE Things-compatible device.
deviceDisplayName String Product name
The trial product name set in Creating a trial product in LINE Things Developer Trial.

Response example

{
  "userId": "{userId}",
  "device": {
    "id": "{deviceId}",
    "productId": {productId},
    "productSpecificDeviceId": "{PSDI}"
  },
  "deviceDisplayName": "{Product Name}"
}

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:
  • Device not found.
  • There is no access permission.

Get device information by product ID and user ID

Specify the product ID and user ID, and acquire the device information.

HTTP request

GET https://api.line.me/things/v1/products/{productId}/users/{userId}/links

Request header

Request header Description
Authorization Bearer {channel access token}

Path parameters

Parameter Description
productId Product ID
userId User ID. User ID is a string matching the regular expression pattern U[0-9a-f]{32}.

Request example

curl -X GET https://api.line.me/things/v1/products/{productId}/users/{userId}/links \
-H "Authorization: Bearer {channel access token}" \

Response

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

Property Type Description
items[].userId String User ID
User ID is a string matching the regular expression pattern U[0-9a-f]{32}.
items[].device.id String Device ID
items[].device.productId Number Product ID
items[].device.productSpecificDeviceId String PSDI
PSDI is a value that is set for each device by the developer of the LINE Things-compatible device.
items[].deviceDisplayName String Product name
The trial product name set in Creating a trial product in LINE Things Developer Trial.

Response example

{
  "items": [
    {
      "userId": "{userId}",
      "device": {
        "id": "{deviceId}",
        "productId": {productId},
        "productSpecificDeviceId": "{PSDI}"
      },
      "deviceDisplayName": "{Product Name}"
    },
    {
      "userId": "{userId}",
      "device": {
        "id": "{deviceId}",
        "productId": {productId},
        "productSpecificDeviceId": "{PSDI}"
      },
      "deviceDisplayName": "{Product Name}"
    }
  ]
}

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:
  • Device not found.
  • There is no access permission.

Create trial product

Specify the product name and LIFF app ID, and create the trial product.

HTTP request

POST https://api.line.me/things/v1/trial/products

Request header

Request header Description
Authorization Bearer {channel access token}
Content-Type application/json

Request body

Field Type Description
name String Product name
liffId String LIFF app ID

Request example

curl -X POST https://api.line.me/things/v1/trial/products \
-H "Authorization: Bearer {channel access token}" \
-H "Content-Type: application/json" \
-d '{
  "name": "{trial product name}",
  "liffId": "{LIFF APP ID}"
}'

Response

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

Property Type Description
id Number Product ID
ID for identifying the trial product created in the LINE Platform.
name String Product name
type String Product type ("BLE" only)
channelID Number Channel ID of the channel for Messaging API associated with the product
actionUri String URL of the LIFF app
serviceUuid String Service UUID for service search
Include it in the packet advertised by the LINE Things-compatible devices for pairing. This UUID is automatically numbered.
psdiServiceUuid String The service UUID for device identification (to which the characteristic belongs) that has the value for identifying the device on a product basis.*
psdiCharacteristicUuid String The characteristic UUID for device identification that has the value for identifying the device on a product basis.*

* In the characteristics that can be identified in psdiServiceUuid and psdiCharacteristicUuid, record the value for uniquely identifying a LINE Things-compatible device on a product basis.

Response example

{
  "id": {productId},
  "name": "{trial product name}",
  "actionUri": "{LIFF APP URL}",
  "channelId": {channelId},
  "type": "BLE",
  "serviceUuid": "{serviceUuid}",
  "psdiServiceUuid": "{psdiServiceUuid}",
  "psdiCharacteristicUuid": "{psdiCharacteristicUuid}"
}

Error response

One of the following status codes is returned.

Status code Description
400 The request contains an invalid value.
401 Authentication failed.
403 You've reached the maximum of 10 trial products. Delete the unnecessary trial products.

Get trial product

Acquire the trial product.

HTTP request

GET https://api.line.me/things/v1/trial/products

Request header

Request header Description
Authorization Bearer {channel access token}

Request example

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

Response

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

Property Type Description
[].id Number Product ID
[].name String Product
[].actionUri String URL of the LIFF app.
[].channelId Number Channel ID of the channel for Messaging API associated with the product
[].type String Product type (BLE only)
[].serviceUuid String Service UUID for service search of the product. This UUID is automatically numbered.
[].psdiServiceUuid String The service UUID for device identification (to which the characteristic belongs) that has the value for identifying the device on a product basis.*
[].psdiCharacteristicUuid String The characteristic UUID for device identification that has the value for identifying the device on a product basis.*

* In the characteristics that can be identified in psdiServiceUuid and psdiCharacteristicUuid, record the value for uniquely identifying a LINE Things-compatible device on a product basis.

Response example

[
  {
    "id": {productId},
    "name": "{trial product name}",
    "actionUri": "{LIFF APP URL}",
    "channelId": {channelId},
    "type": "BLE",
    "serviceUuid": "{serviceUuid}",
    "psdiServiceUuid": "{psdiServiceUuid}",
    "psdiCharacteristicUuid": "{psdiCharacteristicUuid}"
  }
]

Error response

One of the following status codes is returned.

Status code Description
401 Authentication failed.

Delete trial product

Specify the product ID, and delete the trial product.

HTTP request

DELETE https://api.line.me/things/v1/trial/products/{productId}

Request header

Request header Description
Authorization Bearer {channel access token}

Path parameters

Parameter Description
productId Product ID

Example request

curl -X DELETE https://api.line.me/things/v1/trial/products/{productId} \
-H "Authorization: Bearer {channel access token}" \

Response

Status code 204 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:
  • Trial product not found.
  • There is no access permission.