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

Tip

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

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

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.

Note

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

Required

application/json

X-Line-ChannelId

Required

Channel ID. You can check this property in the LINE Developers Console.

X-Line-ChannelSecret

Required

Channel secret. You can check this property in the LINE Developers Console.

X-Line-Trusted-User-With-ACL

Required

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 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: 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 isn't registered on the "Security settings" tab in the LINE Developers Console.
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.

Unavailable actions

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.

Only for users who have agreed to the LINE Privacy Policy (revised March 2022)

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

Required

application/json

Authorization

Required

Bearer {channel access token}

# Request body

Array of hashed phone number

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

Required

application/json

Authorization

Required

Bearer {channel access token}

# Query parameters

date

Required

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

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

# 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

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 or change unit names.

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 customAggregationUnits property to these 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.

You can also get statistics on a per-message and per-message bubble basis.

message and bubbles

On recorded statistics

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 get statistics per message

Use this endpoint to get statistics per narrowcast message or broadcast message.

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 (e.g. 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 (e.g. 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 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, 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 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

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

The maximum number of aggregation units you can get per request. The default value is 100.
Max value: 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 weren't returned in customAggregationUnits in the original request.

Example response

# LINE notification messages

# Rate limits

Note

The documentation for this section is only available in Japanese.

# Send LINE notification message

Note

The documentation for this section is only available in Japanese.

# Get number of sent LINE notification messages　

Note

The documentation for this section is only available in Japanese.