# Option API reference for corporate customers

Use of optional functions requires an application

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

# Common specifications

# Status code

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

# Mission stickers API

Mission stickers are provided to user 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.

Tip

Unlike "Send mission stickers (v2)", it is not 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

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

The following 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

The main error messages that are found in the message property of the JSON error responses are shown below.

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.

Note

It is 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

String

Required

Destination user ID

messages

Array

Required

An array that has an object that includes the packageId and isPresent properties. Only one object can be specified.

messages[].packageId

String

Required

Package ID for a set of stickers

messages[].isPresent

Boolean

Required

false

# Response

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

ticketId

String

Value used inside LINE.
Returns ticketId if the API call is successful.

Example response

# Error response

The following 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

The main error messages that are found in the message property of the JSON error responses are shown below.

Message	Description
authentication failed	This message is returned in either or both cases below: Any of the `X-Line-ChannelId`, `X-Line-ChannelSecret`, or `X-Line-Trusted-User-With-ACL` headers are incorrect. The server that connects this endpoint is not registered on the "Security settings" tab in the LINE Developers Console.
CHANNEL_MISSION_STICKER_NOT_USABLE	The channel is not granted the required permission for the mission sticker feature.

# Audience Match API

# Rate limits

The limits on API requests for the Audience Match API are the same as the Rate limits for the Messaging API.

# Message types

All message types of Messaging API can be used.

Unavailable actions

Actions other than URI actions can't be set for the following message types:

If an action other than the URI action is set, no message will be sent. Also, no other messages in the same request are 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 mobile advertising ID

Performs targeting delivery based on mobile advertising IDs (IFA: Identifier for Advertisers) owned by users.

Example request

# HTTP request

POST https://api.line.me/v2/bot/ad/message/multicast

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Request body

Object

Required

The destination of the message (IFA)

to.type

String

Required

ifa

to.ids

Array

Required

An array of IFA strings
Max message limit: 150

messages

Array

Required

An array of message objects for the messages to be sent
Max message limit: 5

notificationDisabled

Boolean

Optional

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 message delivery result using mobile advertising ID

Gets the delivery result of the message delivered in "Send message using mobile advertising ID".

Example request

# HTTP request

GET https://api.line.me/v2/bot/message/delivery/ad_ifa?date={date}

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date the message was sent

Format: yyyyMMdd (Example: 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 in date. 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 specified date is earlier than the date on which we first started calculating sent messages (March 31, 2018).

success

Long

Number of messages delivered using mobile advertising ID on the date specified in date. The response has this property only when the value of status is ready.

# Send a message using phone number

Serves targeting delivery based on the user's phone number.

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

Array of hashed phone numbers

Required

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

Required

Message to send.
Max message limit: 5

notificationDisabled

Boolean

Optional

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

Required

Date the message was sent

Format: yyyyMMdd (Example: 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 in date. 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 specified date 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

Required

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, simply by specifying any unit name when sending the message.

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

On assigning unit names later or changing unit names

Once you send a message, you can't retroactively assign unit names or change them.

When assigning unit names, make the contents of the message bubble consistent

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 property, customAggregationUnits, to the following endpoint request bodies.

customAggregationUnits

Array of string

Optional

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.

In addition, statistics can be obtained on a per-message and per-message bubble basis.

message and bubbles

On the recorded statistics recorded

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.

To obtain statistics per message

To obtain statistics per narrowcast message or broadcast message, use the following endpoint.

Get user interaction statistics

Example request

# HTTP request

GET https://api.line.me/v2/bot/insight/message/event/aggregation?customAggregationUnit={customAggregationUnit}&from={from}&to={to}

# Request headers

Authorization

Required

Bearer {channel access token}

# Query parameters

customAggregationUnit

String

Required

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

Required

Start date of aggregation period.

Format: yyyyMMdd (ex: 20210301)
Time zone: UTC+9

String

Required

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 (ex: 20210301)
Time zone: UTC+9

# Response

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

Note

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 the following 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, but messages[].uniqueMediaPlayed is 15, both will be displayed as null

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.

Limit to the number of units that can be used

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 get 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 will not take effect.

Example request

# HTTP request

GET https://api.line.me/v2/bot/message/aggregation/info

# Request headers

Authorization

Required

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

Required

Bearer {channel access token}

# Query parameters

limit

String

Optional

Maximum number of aggregation units you can get per request. If you don't specify a value, or if you specify a value greater than or equal to 100, the maximum is 100.

start

String

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

String

A continuation token to get the next array of unit names. Returned only when there are remaining aggregation units that were not returned in customAggregationUnits in the original request.

Example response