# Option API reference for corporate customers
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)
# HTTP request
POST https://api.line.me/shop/v3/mission
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
# Request body
to
String
Destination user ID
productType
String
STICKER
productId
String
Package ID for a set of stickers
sendPresentMessage
Boolean
false
# Response
Returns status code 200
and an empty response body.
# Error response
This JSON data is returned in the response body when an error occurs.
message
String
Message containing error information. For more information, see Error messages.
# Error messages
These are the main error messages that are found in the message
property of the JSON error responses.
Message | Description |
---|---|
invalid request | The destination user ID specified for to is invalid. |
not found | The package ID specified for productId is invalid. |
internal error | The package ID specified for productId is invalid. |
not allowed to use the API | The channel is not granted the required permission for the mission sticker API. |
not_sales_period | The date and time when the sticker set was sent is not within the valid period of the sticker set. |
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 . |
not sale for device | The device of the destination user specified for to doesn't support the sticker set specified for productId . |
not sale for version | The LINE app used by the destination user specified for to doesn't support the sticker set specified for productId . |
# Audience Match API
As of October 31, 2023, the audience match API will no longer be available. For more information, see As of October 31, 2023, the feature for sending messages using phone number will be discontinued in Information (for corporate users).
# Rate limits
The rate limits on API requests for the Audience Match API are the same as the Rate limits for the Messaging API.
# Message types
You can use all Messaging API message types.
You can't set actions other than URI actions for these message types:
Messages won't be sent if an action other than the URI action is set. Also, other messages in the same request aren't sent.
# Unsupported features
These properties and request headers aren't available for the Audience Match API:
- emojis property
- X-Line-Retry-Key request header
- trackingId property
# Send a message using phone number
As of October 31, 2023, the audience match API will no longer be available. For more information, see As of October 31, 2023, the feature for sending messages using phone number will be discontinued in Information (for corporate users).
Serves targeting delivery based on the user's phone number.
The messages will only be sent to users who have agreed to the privacy policy (revised March 2022) (opens new window), the users who haven't agreed to the privacy policy won't receive the message.
Therefore, the number of messages sent may be less than the number of destinations specified.
# HTTP request
POST https://api.line.me/bot/ad/multicast/phone
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
# Request body
to
Array of hashed phone number
Destination of the message (A value obtained by hashing the telephone number, which is another value normalized to E.164 format, with SHA256).
Max message limit: 150
messages
array of message objects
Message to send.
Max message limit: 5
notificationDisabled
Boolean
true
: The user doesn’t receive a push notification when a message is sent.false
: The user receives a push notification when the message is sent (unless they have disabled push notifications in LINE and/or their device).
The default value is false
.
# Response
# Get result of message delivery using phone number
As of October 31, 2023, the audience match API will no longer be available. For more information, see As of October 31, 2023, the feature for sending messages using phone number will be discontinued in Information (for corporate users).
Gets the delivery result of the message delivered in Send message using phone number.
# HTTP request
GET https://api.line.me/v2/bot/message/delivery/ad_phone?date={date}
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
# Query parameters
date
Date the message was sent
- Format:
yyyyMMdd
(e.g.20190831
) - Time Zone: UTC+9
# Response
Returns status code 200
and a JSON object with these properties:
status
String
Aggregation process status. One of:
ready
: The number of messages can be obtained.unready
: We haven't finished calculating the number of sent messages for the specified indate
. For example, this property is returned when the delivery date or a future date is specified. Calculation usually takes about a day.unavailable_for_privacy
: The total number of messages on the specified day is less than 20.out_of_service
: The specifieddate
is earlier than the date on which we first started calculating sent messages (March 31, 2018).
success
Long
The number of messages delivered using the phone number on the date specified in date
. The response has this property only when the value of status
is ready
.
# Mark as read API
# Mark messages from users as read
# HTTP request
POST https://api.line.me/v2/bot/message/markAsRead
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
# Request body
chat.userId
String
The target user ID
# 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, Taiwan, and Indonesia, 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.
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).
# HTTP request
POST https://api.line.me/bot/pnp/push
# Request header
The LINE notification messages API doesn't allow API request retries using retry keys (X-Line-Retry-Key
).
Content-Type
application/json
Authorization
Bearer {channel access token}
X-Line-Delivery-Tag
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
# Request body
to
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.
- 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
Message to be sent. Max: 5
For more information, see Messages that can be sent via the LINE notification messages API.
# 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).
# 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.
# HTTP request
GET https://api.line.me/v2/bot/message/delivery/pnp
# Request header
Authorization
Bearer {channel access token}
# Query parameter
date
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 indate
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 indate
is before the aggregation system operation's start date (03/31/2018).
success
Number
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
.
# 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.
# HTTP request
POST https://manager.line.biz/module/auth/v1/token
# Request headers
Content-Type
application/x-www-form-urlencoded
Authorization
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
authorization_code
code
String
Authorization code received from the LINE Platform.
redirect_uri
String
Specify the redirect_uri
specified in the URL for authentication and authorization.
code_verifier
String
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
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
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
If you specified a value for region
in the URL for authentication and authorization, specify the same value.
basic_search_id
String
If you specified a value for basic_search_id
in the URL for authentication and authorization, specify the same value.
scope
String
If you specified a value for scope
in the URL for authentication and authorization, specify the same value.
brand_type
String
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.
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.
# 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.
# HTTP request
POST https://api.line.me/v2/bot/channel/detach
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
For {channel access token}
, specify the channel access token of your module channel.
# Request body
botId
String
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.
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.
# HTTP request
POST https://api.line.me/v2/bot/chat/{chatId}/control/acquire
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
For {channel access token}
, specify the channel access token of your module channel.
Header specifying the bot's user ID
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 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
The userId
, roomId
, or groupId
# Request body
expired
Boolean
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
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.
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.
# HTTP request
POST https://api.line.me/v2/bot/chat/{chatId}/control/release
# Request headers
Content-Type
application/json
Authorization
Bearer {channel access token}
For {channel access token}
, specify the channel access token of your module channel.
Header specifying the bot's user ID
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 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
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.
# 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.
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.
# 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.
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."
# 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.
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
# 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.
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
# 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.
The botResumed event isn't sent to the Primary Channel.
timestamp, etc.
See Common properties.
However, mode
is fixed to active
.
type
String
botResumed
# 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.
# HTTP request
GET https://api.line.me/v2/bot/list?limit={limit}&start={continuationToken}
# Request headers
Authorization
Bearer {channel access token}
For {channel access token}
, specify the channel access token of your module channel.
# Query parameters
limit
Specify the maximum number of bots that you get basic information from. The default value is 100
.
Max value: 100
start
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
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
Profile image URL. Image URL starting with "https://". Not included in the response if the bot doesn't have a profile image.
next
String
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).