Options for corporate customers API reference

# Options for corporate customers API reference

Use of optional functions requires an application

Only corporate users who have submitted the required applications can use the functions described in this document. To use these functions with your LINE Official Account, contact your sales representative or contact our Sales partners (opens new window).

# Common specifications

# Status codes

For more information, see Status codes in the Messaging API reference.

# Response headers

The following HTTP headers are included in Options for corporate customers API responses:

Response header Description
x-line-request-id Request ID. An ID is issued for each request.

# Mission stickers API

Mission stickers are provided to users upon completion of certain objectives. Using stickers as an incentive, users are encouraged to "link ID information," "register as a member," or "answer a questionnaire."

# Provide mission stickers to the users

Grants permission for users who have completed a certain objective to download your mission sticker.

Example request

# HTTP request

POST https://api.line.me/shop/v3/mission

# Request headers

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

# Request body

to

String

Required

User ID of a user to grant download permission

productType

String

Required

STICKER

productId

String

Required

Package ID for a set of stickers

sendPresentMessage

Boolean

Required

false

# Response

Returns status code 200 and an empty response body.

# Error response

An HTTP status code corresponding to the error and this JSON data are returned in the response body when an error occurs.

message

String

Message containing error information. For more information, see Error messages.

# Error messages

The HTTP status code for the main errors and the error message that is found in the message property of the JSON data are as follows:

Code Message Description
400 invalid request The destination user ID specified for to is invalid.
400 illegal argument The sticker set specified for productId isn't set as a mission sticker
400 not_sales_period The sticker set specified for productId is out of validity period.
400 not sale for country The sticker set specified for productId isn't available for purchase in the country of the destination user specified for to.
400 not sale for device The device of the destination user specified for to doesn't support the sticker set specified for productId.
400 not sale for version The version of the LINE app used by the destination user specified for to doesn't support the sticker set specified for productId.
403 not allowed to use the API The channel isn't granted the required permission for the mission sticker API.
404 not found The sticker set specified for productId doesn't exist.

# Mark as read API

# Mark messages from users as read

All messages sent from a specific user can display "Read".

Example request

# HTTP request

POST https://api.line.me/v2/bot/message/markAsRead

# Rate limit

2,000 requests per second

# Request headers

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

# Request body

chat.userId

String

Required

The target user ID

# Response

Returns status code 200 and an empty JSON object.

Example response

# Error response

Returns the following HTTP status code and an error response:

Code Description
400 An invalid user ID is specified.

For more information, see Status codes and Error responses in the Messaging API reference.

Example error response

# Module

Attach the module channel to the LINE Official Account. In order to attach, you most request authorization from the admin of the LINE Official Account and obtain an authorization code. For more information about the module authorization flow, see Attach Module Channel in the module documentation.

When using this API, you need to specify the channel ID and channel secret of the module channel using either the Authorization header or the request body.

Example request

POST https://manager.line.biz/module/auth/v1/token

Content-Type

Required

application/x-www-form-urlencoded

Authorization

Optional

Basic {base64({Channel ID}:{Channel Secret})}

For {base64({Channel ID}:{Channel Secret})}, specify a Base64-encoded string by concatenating "Module Channel ID" and "Module Channel Secret" with :. You can find the module channel's channel ID and channel secret in the LINE Developers Console.

Instead of using client_id and client_secret in request body, you can use this header to specify the channel ID and the channel secret of the module channel.

# Request body

grant_type

String

Required

authorization_code

code

String

Required

Authorization code received from the LINE Platform.

redirect_uri

String

Required

Specify the redirect_uri specified in the URL for authentication and authorization.

code_verifier

String

Optional

Specify when using PKCE (Proof Key for Code Exchange) defined in the OAuth 2.0 extension specification as a countermeasure against authorization code interception attacks.

Compliant with RFC 7636 (opens new window).

client_id

String

Optional

Instead of using Authorization header, you can use this parameter to specify the channel ID of the module channel. You can find the channel ID of the module channel in the LINE Developers Console.

client_secret

String

Optional

Instead of using Authorization header, you can use this parameter to specify the channel secret of the module channel. You can find the channel secret of the module channel in the LINE Developers Console.

region

String

Optional

If you specified a value for region in the URL for authentication and authorization, specify the same value.

basic_search_id

String

Optional

If you specified a value for basic_search_id in the URL for authentication and authorization, specify the same value.

scope

String

Optional

If you specified a value for scope in the URL for authentication and authorization, specify the same value.

brand_type

String

Optional

If you specified a value for brand_type in the URL for authentication and authorization, specify the same value.

Returns a JSON object with status code 200 and this information on success.

bot_id

String

User ID of the bot on the LINE Official Account.

The bot's user ID is used when calling the Messaging API or the Acquire Control API.

Note

The bot's user ID isn't the Your user ID displayed on the Basic Settings tab of the LINE Developers Console for the Messaging API channel.

scope

String

Permissions (scope) granted by the LINE Official Account admin.

Example response

Returns the following HTTP status code:

  • 400 Bad Request
  • 403 Forbidden

The module channel admin calls the Detach API to detach the module channel from a LINE Official Account.

Example request

POST https://api.line.me/v2/bot/channel/detach

2,000 requests per second

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

For {channel access token}, specify the channel access token of your module channel.

# Request body

botId

String

Required

The user ID of the LINE Official Account bot attached to the module channel.

You can get the user ID of the bot from the response of the Attach by operation of the module channel provider or the Attached event.

Returns a 200 status code on success.

Returns the following HTTP status code and an error response:

Code Description
400 Couldn't unlink (detach) the module channel. Consider these reasons:
  • An invalid user ID of the LINE Official Account bot is specified.
  • A non-existent LINE Official Account bot is specified.
  • The module channel isn't linked (attached).
  • A channel access token is specified for a non-module channel.

For more information, see Status codes and Error responses in the Messaging API reference.

Example error response

# Acquire Control API

If the Standby Channel wants to take the initiative (Chat Control), it calls the Acquire Control API.

The channel that was previously an Active Channel will automatically switch to a Standby Channel.

Warning

It isn't necessary to call this API in the currently provided module structure. So, the implementation of this API is optional.

This API is currently used only when the chat initiative switches due to unexpected problems.

Example request

# HTTP request

POST https://api.line.me/v2/bot/chat/{chatId}/control/acquire

# Rate limit

2,000 requests per second

# Request headers

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

For {channel access token}, specify the channel access token of your module channel.

Header specifying the bot's user ID

Required

The user ID of the LINE Official Account bot attached to the module channel.

You can get the user ID of the bot from the response of the Attach by operation of the module channel provider or the Attached event.

The specific header will be provided when after participation

The name (parameter name) of this header is open only to customers who participate in the LINE Marketplace (opens new window) (only available in Japanese).

# Path parameter

chatId

Required

The userId, roomId, or groupId

# Request body

expired

Boolean

Optional
  • True: After the time limit (ttl) has passed, the initiative (Chat Control) will return to the Primary Channel. (Default)
  • False: There's no time limit and the initiative (Chat Control) doesn't change over time.

ttl

Number

Optional

The time it takes for initiative (Chat Control) to return to the Primary Channel (the time that the module channel stays on the Active Channel). The value is specified in seconds. The maximum value is one year (3600 * 24 * 365). The default value is 3600 (1 hour).

* Ignored if the value of expired is false.

# Response

Returns a 200 status code on success.

# Error response

Returns the following HTTP status code and an error response:

Code Description
400 An invalid ID is specified in the chatId parameter.
404 Couldn't take the initiative (Chat Control). Consider these reasons:
  • A user is specified who hasn't added the LINE Official Account attached to the module as a friend.
  • A group is specified that the LINE Official Account attached to the module doesn't participate in.
  • A multi-person chat is specified that the LINE Official Account attached to the module doesn't participate in.
423 Another channel has acquired the initiative (Chat Control) within a certain period of time (a few seconds or so).

For more information, see Status codes and Error responses in the Messaging API reference.

Example error response

# Release Control API

To return the initiative (Chat Control) of Active Channel to Primary Channel, call the Release Control API.

Warning

It isn't necessary to call this API in the currently provided module structure. So, the implementation of this API is optional.

This API is currently used only when the chat initiative switches due to unexpected problems.

Example request

# HTTP request

POST https://api.line.me/v2/bot/chat/{chatId}/control/release

# Rate limit

2,000 requests per second

# Request headers

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

For {channel access token}, specify the channel access token of your module channel.

Header specifying the bot's user ID

Required

The user ID of the LINE Official Account bot attached to the module channel.

You can get the user ID of the bot from the response of the Attach by operation of the module channel provider or the Attached event.

The specific header will be provided when after participation

The name (parameter name) of this header is open only to customers who participate in the LINE Marketplace (opens new window) (only available in Japanese).

# Path parameter

chatId

Required

The userId, roomId, or groupId

# Response

Returns a 200 status code on success.

# Error response

Returns the following HTTP status code and an error response:

Code Description
400 An invalid ID is specified in the chatId parameter.

For more information, see Status codes and Error responses in the Messaging API reference.

Example error response

# Module channel-specific webhook events

# Attached event

This event indicates that the module channel has been attached to the LINE Official Account. Sent to the webhook URL server of the module channel.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

module

module.type

String

attached

module.botId

String

User ID of the bot on the attached LINE Official Account

module.scopes

Array of strings

An array of strings indicating the scope permitted by the admin of the LINE Official Account.

Example Attached event

# Detached event

This event indicates that the module channel has been detached from the LINE Official Account. Sent to the webhook URL server of the module channel.

Detach isn't done when you delete the LINE Official Account

The module channel won't be detached when the LINE Official Account Manager is used to delete the LINE Official Account.

After three months have passed since the operation to delete the account, and all information including the LINE Official Account's analysis data has been completely deleted, the account will automatically be detached.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

module

module.type

String

detached

module.botId

String

Detached LINE Official Account bot user ID

module.reason

String

Reason for detaching

bot_deleted: All information, including analysis data for the LINE Official Account, has been completely deleted.

Example Detached event

# Activated event

This event indicates that the module channel has been switched to Active Channel by calling the Acquire Control API. Sent to the webhook URL server of the module channel.

Note

The activated event won't be sent if the validity period specified in the Acquire Control API has expired and the initiative (Chat Control) has been switched.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

activated

chatControl.expireAt

Number

The time limit for maintaining "active."

Example Activated event

# Deactivated event

This event indicates that the module channel has been switched to Standby Channel by calling Acquire Control API or Release Control API. Sent to the webhook URL server of the module channel.

Note

The deactivated event won't be sent if the validity period specified in the Acquire Control API has expired and the initiative (Chat Control) has been switched.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

deactivated

Example Deactivated event

# botSuspend event

This event indicates that the LINE Official Account has been suspended (Suspend). Sent to the webhook URL server of the module channel.

When you receive this event, it's recommended that you do the following:

  • Display a message such as "This admin screen can't be used because the LINE Official Account is unavailable" on the module channel admin screen, and stop using the admin screen.
  • Even if it goes into the paused state, it may return from the paused state (it may receive a botResume event). It is recommended that all information be kept.
Note

The botSuspend event isn't sent to the Primary Channel.

If you receive the Detached event after receiving the botSuspend event, it means that the LINE Official Account has stopped using the module channel and canceled the contract.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

botSuspended

Example botSuspend event

# botResumed event

This event indicates that the LINE Official Account has returned from the suspended state. Sent to the webhook URL server of the module channel.

When you receive this event, it's recommended that you hide the message "This admin page is unavailable due to the LINE Official Account being unavailable" from the module channel admin page and resume using the admin page.

Note

The botResumed event isn't sent to the Primary Channel.

timestamp, etc.

See Common properties.

However, mode is fixed to active.

type

String

botResumed

Example botResumed event

# Get a list of bots to which the module is attached

Gets a list of basic information about the bots of multiple LINE Official Accounts that have attached module channels.

Example request

# HTTP request

GET https://api.line.me/v2/bot/list?limit={limit}&start={continuationToken}

# Rate limit

2,000 requests per second

# Request headers

Authorization

Required

Bearer {channel access token}

For {channel access token}, specify the channel access token of your module channel.

# Query parameters

limit

Optional

Specify the maximum number of bots that you get basic information from. The default value is 100.
Max value: 100

start

Optional

Value of the continuation token found in the next property of the JSON object returned in the response. If you can't get all basic information about the bots in one request, include this parameter to get the remaining array.

# Response

Returns a JSON object with status code 200 and this information on success.

bots

Array

Array of Bot list Item objects representing basic information about the bot.

bots[].userId

String

Bot's user ID

bots[].basicId

String

Bot's basic ID

bots[].premiumId

String

Not always included

Bot's premium ID. Not included in the response if the premium ID isn't set.

bots[].displayName

String

Bot's display name

bots[].pictureUrl

String

Not always included

Profile image URL. Image URL starting with "https://". Not included in the response if the bot doesn't have a profile image.

next

String

Not always included

Continuation token. Used to get the next array of basic bot information. This property is only returned if there are more unreturned results.

The continuation token expires in 24 hours (86,400 seconds).

Example response

# Error response

Returns the following HTTP status code and an error response:

Code Description
400 An invalid continuation token is specified.

For more information, see Status codes and Error responses in the Messaging API reference.

Error response example

# Quick-fill

Quick-fill is a feature that automatically fills in the necessary profile information by tapping the Auto-fill button on the LINE MINI App. You can easily use the Common Profile information that a user has set in the Account Center in the LINE MINI App. For more information, see Overview of Quick-fill.

# liff.$commonProfile.get()

Gets the information in the Common Profile that the user has set in the Account Center.

When you execute the liff.$commonProfile.get() method, a modal will appear to confirm the user's profile. After confirming the profile in the displayed modal, the user can tap Auto-fill and the profile information will be entered automatically.

Example of a modal display:

Example

# Syntax

liff.$commonProfile.get(scopes);

# Arguments

scopes

Array of strings

Required

Specify the scope of the Common Profile you want to obtain.

For information on the values that can be specified for scopes, see The scopes parameters that can be specified and its return value.

# Return value

Returns Promise object of type Partial<CommonProfile>.

When Promise is resolved, an object of type Partial<CommonProfile> containing the user's Common Profile information is passed.

In the following cases, the property will be undefined or null:

  • Cases where the property value becomes undefined
    • If the target item isn't specified in the scopes parameter
    • If the target item is specified in the scopes parameter, but the user doesn't authorized permission for that item
  • Cases where the property value becomes null
    • If the user hasn't set a value for the target item in the Common Profile
    • If an error occurs when retrieving the target item in the Common Profile

For information on the values of the properties that can be obtained according to the specified scopes, see The scopes parameters that can be specified and its return value.

Example

# Error response

When the Promise is rejected, LiffError is passed.

Example of calling the API without installing the plugin correctly

Example of API being called in a browser other than LIFF browser

# liff.$commonProfile.getDummy()

Gets the dummy data for the Common Profile. There are 10 types of dummy data available, and you can specify the dummy data to get using the caseId.

When you execute the liff.$commonProfile.getDummy() method, a modal will appear to confirm the dummy profile. You can get dummy data for the Common Profile by tapping Auto-fill.

Example of a modal display:

Example

# Syntax

liff.$commonProfile.getDummy(scopes, caseId);

# Arguments

scopes

Array of strings

Required

Specify the scope of the Common Profile you want to obtain.

For information on the values that can be specified for scopes, see The scopes parameters that can be specified and its return value.

caseId

number

Required

Specify the ID of the dummy data you want to get. Dummy data with IDs from 1 to 10 is available.

For information about dummy data for each caseId, see Dummy data for Common Profile that can be obtained.

# Return value

Returns Promise object of type Partial<CommonProfile>.

When Promise is resolved, an object of type Partial<CommonProfile> containing the dummy data of the Common Profile is passed.

In the following cases, the property will be undefined or null:

  • Cases where the property value becomes undefined
    • If the target item isn't specified in the scopes parameter
  • Cases where the property value becomes null
    • If the dummy data doesn't have a value for the target item

For information on the dummy data you can get for the specified ID, see Dummy data for Common Profile that can be obtained.

Example

# Error response

When the Promise is rejected, LiffError is passed.

Example of calling the API without installing the plugin correctly

Example of API being called in a browser other than LIFF browser

# liff.$commonProfile.fill()

Automatically fills the form with the Common Profile information you have obtained. The data-liff-autocomplete attribute is used to link each profile information to the form.

Automatically filling that doesn't match the scope

Automatic input using liff.$commonProfile.fill() is performed using the data-liff-autocomplete attribute of the form. At this time, the value specified in the data-liff-autocomplete attribute of the form must match the scope of the profile information obtained (family-name, tel, bday-year, etc.)

For example, if you want to automatically fill in a form after retrieving the year of birth (bday-year), month of birth (bday-month), and day of birth (bday-day) information and then process it into a format like 20110623, you can use document.getElementById().value or document.querySelector().value instead of liff.$commonProfile.fill().

Example of automatically filling the family name, phone number, and gender as they were obtained

Example of automatically filling some of the common profile information that has been obtained in a slightly different format

# Syntax

liff.$commonProfile.fill(profile);

# Arguments

profile

Partial<CommonProfile>

Required

Specify the profile information that is automatically fill into the form as a Partial<CommonProfile> type.

For information on the scopes, that can be specified, see The scopes parameters that can be specified and its return value.

# Return value

None