# 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)
Sends a mission sticker.
Unlike "Send mission stickers (v2)", it isn't necessary to register the IP or network address of the server that connects this endpoint in the LINE Developers Console.
Example request
# 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 . |
# Send mission stickers (v2)
Sends a push mission sticker to a user at any time.
It's necessary to register the IP or network address of the server that connects this endpoint in the LINE Developers Console. Add the server IP address or network address to the Security Management tab of the target channel.
Example request
# HTTP request
POST https://api.line.me/v2/missionSticker/send
# Request headers
Content-Type
application/json
X-Line-ChannelId
Channel ID. You can check this property in the LINE Developers Console.
X-Line-ChannelSecret
Channel secret. You can check this property in the LINE Developers Console.
X-Line-Trusted-User-With-ACL
Value assigned when the permission to use the Mission Stickers API is granted. For more information, contact your LINE representative.
# Request body
to
String
Destination user ID
messages
Array
An array that has an object that includes the packageId
and isPresent
properties. Only one object can be specified.
messages[].packageId
String
Package ID for a set of stickers
messages[].isPresent
Boolean
false
# Response
Returns status code 200
and a JSON object with these properties.
ticketId
String
Value used inside LINE.
Returns ticketId
if the API call is successful.
Example response
# 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 |
---|---|
authentication failed | This message is returned in either or both cases below:
|
CHANNEL_MISSION_STICKER_NOT_USABLE | The channel isn't granted the required permission for the mission sticker feature. |
# Audience Match API
# 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
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.
Example request
# 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
Returns status code 200
and an empty JSON object.
Example response
# Get result of message delivery using phone number
Gets the delivery result of the message delivered in Send message using phone number.
Example request
# 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
# Mark messages from users as read
All messages sent from a specific user can display "Read" at any time.
Example request
# 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
Returns status code 200
and an empty JSON object.
Example response
# Get statistics per aggregation unit
Enables aggregation of statistics when sending push messages or multicast messages with the same content to multiple end users. "Unit" refers to the aggregation unit. There is no procedure to creating a unit. You can view statistics on a per-unit basis by specifying any unit name when sending the message.
- Assign a unit name to any aggregation unit when sending messages
- Get statistics per unit
- Get number of units used this month
- Get name list of units used this month
# Assign a unit name to any aggregation unit when sending messages
When sending push messages or multicast messages, assign names to aggregation units. For information on sending push messages or multicast messages, see Message under the Messaging API reference.
Once you send a message, you can't retroactively assign or change unit names.
If you send messages with the same unit name, the statistics are aggregated together, regardless of message contents or the number and order of message bubbles. When sending multiple messages with the same unit name, make sure the contents of the message bubbles are consistent.
# Request body
You can specify the customAggregationUnits
property to these endpoint request bodies.
customAggregationUnits
Array of string
Name of aggregation unit. Case-sensitive. For example, Promotion_a
and Promotion_A
are regarded as different unit names.
- Maximum unit number: 1
- Maximum length: 30 characters
- Supported character types: Half-width alphanumeric characters (
a-z
,A-Z
,0-9
) and underscore (_
)
Example request
# Get statistics per unit
You can check the per-unit statistics of how users interact with push messages and multicast messages sent from your LINE Official Account.
You can also get statistics on a per-message and per-message bubble basis.
Interactions are updated for only 14 days (1,209,600 seconds) from the time a message was sent. After that time, interactions aren't updated.
For example, if you send a message at 15:00 on February 1, 2021, interactions will be updated until 15:00 on February 15, 2021.
Use this endpoint to get statistics per narrowcast message or broadcast message.
Example request
# HTTP request
GET https://api.line.me/v2/bot/insight/message/event/aggregation?customAggregationUnit={customAggregationUnit}&from={from}&to={to}
# Request headers
Authorization
Bearer {channel access token}
# Query parameters
customAggregationUnit
String
Name of aggregation unit specified when sending the message. Case-sensitive. For example, Promotion_a
and Promotion_A
are regarded as different unit names.
from
String
Start date of aggregation period.
- Format:
yyyyMMdd
(e.g.20210301
) - Time zone: UTC+9
to
String
End date of aggregation period. The end date can be specified for up to 30 days later. For example, if the start date is 20210301
, the latest end date is 20210331
.
- Format:
yyyyMMdd
(e.g.20210301
) - Time zone: UTC+9
# Response
Returns a 200
HTTP status code and a JSON object with this information.
The statistical data may contain some errors.
To protect users' privacy, the values of some properties related to user interactions will be displayed as null
in these cases:
- The property value is 20 or lower
- Even if the property value is higher than 20, the actual number of users who generated the event is less than 20 (for example, if
messages[].mediaPlayed
is 30, butmessages[].uniqueMediaPlayed
is 15, both will be displayed asnull
overview
Object
Statistics related to messages.
overview.uniqueImpression
Number
Number of users who opened the message, meaning they displayed at least 1 bubble.
overview.uniqueClick
Number
Number of users who opened any URL in the message.
overview.uniqueMediaPlayed
Number
Number of users who started playing any video or audio in the message.
overview.uniqueMediaPlayed100Percent
Number
Number of users who played the entirety of any video or audio in the message.
messages
Array
Array of information about individual message bubbles.
messages[].seq
Number
Bubble's serial number.
messages[].impression
Number
Number of times the bubble was displayed.
messages[].mediaPlayed
Number
Number of times audio or video in the bubble started playing.
messages[].mediaPlayed25Percent
Number
Number of times audio or video in the bubble was played from start to 25%.
messages[].mediaPlayed50Percent
Number
Number of times audio or video in the bubble was played from start to 50%.
messages[].mediaPlayed75Percent
Number
Number of times audio or video in the bubble was played from start to 75%.
messages[].mediaPlayed100Percent
Number
Number of times audio or video in the bubble was played in its entirety.
messages[].uniqueMediaPlayed
Number
Number of users that started playing audio or video in the bubble.
messages[].uniqueMediaPlayed25Percent
Number
Number of users that played audio or video in the bubble from start to 25%.
messages[].uniqueMediaPlayed50Percent
Number
Number of users that played audio or video in the bubble from start to 50%.
messages[].uniqueMediaPlayed75Percent
Number
Number of users that played audio or video in the bubble from start to 75%.
messages[].uniqueMediaPlayed100Percent
Number
Number of users that played audio or video in the bubble in its entirety.
clicks
Array
Array of information about opened URLs in the message.
clicks[].seq
Number
The URL's serial number.
clicks[].url
String
URL.
clicks[].click
Number
Number of times the URL in the bubble was opened.
clicks[].uniqueClick
Number
Number of users that opened the URL in the bubble.
clicks[].uniqueClickOfRequest
Number
Number of users who opened this url
through any link in the message. If another message bubble contains the same URL and a user opens both links, it's counted only once.
Example response
# Get number of units used this month
Get the number of aggregation units used this month.
With the feature for getting statistics per aggregation unit, you can use up to 1,000 different unit names per channel in a given month. Unit numbers are reset on the first day of every month and are counted from 1 again. If you assign the 1,001st unit name within a given month, you can still send a message, but the new unit name won't take effect.
Example request
# HTTP request
GET https://api.line.me/v2/bot/message/aggregation/info
# Request headers
Authorization
Bearer {channel access token}
# Response
Returns a 200
HTTP status code and a JSON object with this information.
numOfCustomAggregationUnits
Number
Number of aggregation units used this month.
Example response
# Get name list of units used this month
You can get the name list of units used this month for statistics aggregation.
Example request
# HTTP request
GET https://api.line.me/v2/bot/message/aggregation/list
# Request headers
Authorization
Bearer {channel access token}
# Query parameters
limit
String
The maximum number of aggregation units you can get per request. The default value is 100
.
Max value: 100
start
String
Value of the continuation token found in the next
property of the JSON object returned in the response. If you can't get all the aggregation units in one request, include this parameter to get the remaining array.
# Response
Returns a 200
HTTP status code and a JSON object with this information.
customAggregationUnits
Array of string
Name list of aggregation units used this month.
next
String
A continuation token to get the next array of unit names. Returned only when there are remaining aggregation units that weren't returned in customAggregationUnits
in the original request.
Example response
# LINE notification messages
# Rate limits
The documentation for this section is only available in Japanese.
# Send LINE notification message
The documentation for this section is only available in Japanese.
# Get number of sent LINE notification messages 
The documentation for this section is only available in Japanese.