Option API reference for corporate customers

# Option API reference for corporate customers

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

# Send mission stickers (v3)

Sends a 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

String

Required

Destination user ID

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

# 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

# LINE notification messages API

# Rate limits

The LINE Notification Message API complies with the Rate limits of the Messaging API.

# Conditions for sending LINE notification messages

The LINE Notification Message API sends a message to the user if all of the following conditions are met:

The phone number you specify as the destination of a LINE notification message matches the phone number registered in the user's LINE account
The phone number registered in the user's LINE account is valid (the user has authenticated the phone number by SMS within a certain period of time)
User agrees to receive LINE notification messages
User hasn't blocked your LINE Official Account
The phone number is issued in Japan, Thailand, and Taiwan, and the phone number can be used to authenticate by phone number in the LINE app (opens new window)
User agrees to LINE's Privacy Policy (revised March 2022) (opens new window)

For more information on setting up LINE notification messages in the LINE app, see How to receive LINE notification messages (opens new window) (only available in Japanese) in the LINE user's guide.

# Send LINE notification message

An API that sends a LINE notification message by specifying the user's phone number.

Restrictions on request source IP addresses

When sending LINE notification messages, don't register the IP address of the server that can call the API of the LINE Platform in the [Security Settings] tab of the Messaging API channel. Sending a LINE notification message with the requestor's IP address restricted may result in sending failure. For more information on how to set it up, see Configure security settings (optional).

Example request

# HTTP request

POST https://api.line.me/bot/pnp/push

# Request header

Unsupported features

The LINE notification messages API doesn't allow API request retries using retry keys (X-Line-Retry-Key).

Content-Type

Required

application/json

Authorization

Required

Bearer {channel access token}

X-Line-Delivery-Tag

Optional

String returned in the delivery.data property of the delivery completion event via Webhook. For more information, see Get message delivery notifications.
Minimum character count: 16
Max character count: 100

Example X-Line-Delivery-Tag

# Request body

Required

Message destination. Specify a phone number that has been normalized to E.164 format and hashed with SHA256.

For more information about conditions for sending a message, see Conditions for sending LINE notification messages.

Note

You can't specify group chats and chats with multiple users.
You can't specify multiple phone numbers as the transmission target.

messages

Array of message objects

Required

Message to be sent. Max: 5

For more information, see Messages that can be sent via the LINE notification messages API.

# Response

Returns status code 200 and an empty JSON object.

Example response

# Error response

Returns a JSON object containing error information along with a 4xx HTTP status code. See Error responses in Common specifications.

The error that occurs with the 422 HTTP status code below is an error specific to the LINE Notification Message API.

message

String

Failed to send a LINE notification message using the LINE notification messages API. These are possible reasons:

There is no LINE user associated with the phone number specified as the target for sending messages.
The phone number specified as the message sending target wasn't issued in LINE notification message service target country.
The LINE user associated with the phone number specified as the message sending target has refused to receive LINE notification messages.
The LINE user associated with the phone number specified as the message sending target hasn't agreed to LINE's Privacy Policy (revised March 2022) (opens new window).

Example error response

# Get number of sent LINE notification messages

Gets the number of LINE notification messages sent using the /bot/pnp/push endpoint.

For more information, see Get the number of sent LINE notification messages in the LINE notification message documentation.

Example request

# HTTP request

GET https://api.line.me/v2/bot/message/delivery/pnp

# Request header

Authorization

Required

Bearer {channel access token}

# Query parameter

date

Required

Date the message was sent

Format: yyyyMMdd (Example:20211231)
Time zone: UTC+9

# Response

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

status

String

Aggregation processing status. One of:

ready: You can get the number of messages.
unready: The total number of messages for the date specified in date isn't yet complete. Try the request again after a short time. The aggregation process is usually completed within the next day.
out_of_service: The date specified in date is before the aggregation system operation's start date (03/31/2018).

success

Number

Not always included

Number of messages sent using the LINE notification messages API on the date specified in date. Only included in the response if the value of status is ready.

Example response

# Error response

Returns a JSON object containing error information along with a 4xx HTTP status code. See Error responses in Common specifications.

# Module

# Attach by operation of the module channel provider

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

# HTTP request

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

# Request headers

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.

# Response

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

# Error response

Returns the following HTTP status code:

400 Bad Request
403 Forbidden

# Unlink (detach) the module channel by the operation of the module channel administrator

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

Example request

# HTTP request

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

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

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

# Response

Returns a 200 status code on success.

# Error Response

Returns a 400 HTTP status code.

# 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

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

400 Bad Request
403 Forbidden
404 Not Found
423 Locked
- This error occurs when another channel obtains initiative (Chat Control) within a certain period of time (a few seconds or so).

# 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

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

400 Bad Request
403 Forbidden
404 Not Found

# 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

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}

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