# Messaging API reference

# Common specifications

Common specifications for Messaging API, such as response and rate limit when a request succeeds or fails.

# Rate limits

The Messaging API applies the following rate limits for each endpoint. Rate limits depend on your plan and endpoint.

Note

If you continue to send requests exceeding the rate limit for an extended period of time, we may block incoming requests.

Endpoint	Rate limit
Send a narrowcast message Send a broadcast message Get number of sent messages Get number of friends Get friend demographics Get user interaction statistics Test webhook endpoint	60 requests per hour
Create audience for uploading user IDs (by JSON) Create audience for uploading user IDs (by file) Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by JSON) Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by file) Create audience for click-based retargeting Create audience for impression-based retargeting Rename an audience Delete audience Get audience data Get data for multiple audiences Get the authority level of the audience Change the authority level of the audience	60 requests per minute
Set webhook endpoint URL Get webhook endpoint information	1,000 requests per minute
Other API endpoints	100,000 requests per minute 1,700 requests per second*

*The rate limit in seconds is a guideline for mass transmission.

# Status codes

The following status codes are returned by the Messaging API.

Status code	Description
200 OK	Request successful
400 Bad Request	Problem with the request
401 Unauthorized	Valid channel access token is not specified
403 Forbidden	Not authorized to access the resource. Confirm that your account or plan is authorized to access the resource.
429 Too Many Requests	Exceeded the rate limit for requests. Exceeded your monthly message limit. You can check the limit (opens new window) for your account in the LINE Official Account Manager.
500 Internal Server Error	Error on the internal server

# Response headers

The following HTTP headers are included in Messaging API responses.

Response headers	Description
X-Line-Request-Id	Request ID. A unique ID is generated for each request
X-Line-Accepted-Request-Id	If the request has already been accepted using the same retry key, the `x-line-request-id` of the accepted request is shown.

# Error responses

The following JSON data is returned in the response body when an error occurs.

message

String

Message containing information about the error. For more details, see Error messages.

details[].message

String

Details of the error. Not returned in certain situations.

details[].property

String

Location of where the error occurred. Not returned in certain situations.

Example error response

# Error messages

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

Message	Description
The request body has X error(s)	An error was found in the JSON data of the request body. The number of errors is displayed for "X". Further details are shown in the `details[].message` and `details[].property` properties.
Invalid reply token	An invalid reply token was used in the reply message
The property, XXX, in the request body is invalid (line: XXX, column: XXX)	An invalid property was specified in the request body. The specific property is displayed for "XXX".
The request body could not be parsed as JSON (line: XXX, column: XXX)	The JSON in the request body could not be parsed. The specific line and column are displayed.
The content type, XXX, is not supported	A content type not supported by the API is requested.
Authentication failed due to the following reason: XXX	Authentication failed when the API was called. The reason is displayed for "XXX".
Access to this API is not available for your account	Appears when calling an API that you do not have permission to use.
Failed to send messages	Appears when the message fails to be sent. One reason this may appear is if the user ID specified does not exist.
You have reached your monthly limit.	You have exceeded the target limit for additional messages.

# Webhooks

When an event occurs, such as when a user adds your LINE Official Account as a friend or sends a message, the LINE Platform sends an HTTPS POST request to the webhook URL (bot server).

The webhook URL is configured for each channel in the LINE Developers Console.

# Webhook Event Objects

These are JSON objects containing events generated by the LINE platform.

Some properties of these event objects might not have any value. Generated event objects don't contain properties without any value.

The structure of these event objects might be changed when the Messaging API feature is updated. Such changes can include adding properties, changing the order of properties, adding or deleting spaces and newlines between data elements, and so on. Implement your server so as not to fail in receiving event objects whose structure has changed in the future.

Example webhook event object

# Common properties

The following properties are found in webhook event objects.

type

String

Identifier for the type of event

mode

String

Channel state.

active: The channel is active. You can send a reply message or push message from the bot server that received this webhook event.
standby (under development): The channel is waiting. The bot server that received this webhook event shouldn't send any messages.

timestamp

Number

Time of the event in milliseconds

source

Object

Source user, group, or room object with information about the source of the event.

What causes the mode property to change

The mode property's value can change to standby if the channel administrator starts using channel multiplexing (under development). The value of mode never automatically changes to standby.

There is currently no way to multiplex incoming channels.

# Source user

type

String

user

userId

String

ID of the source user

Source user example

# Source group

type

String

group

groupId

String

ID of the source group

userId

String

ID of the source user. Only included in message events. Only users of LINE for iOS and LINE for Android are included in userId. For more information, see User consent.

Source group example

# Source room

type

String

room

roomId

String

ID of the source room

userId

String

ID of the source user. Only included in message events. Only users of LINE for iOS and LINE for Android are included in userId. For more information, see User consent.

Source room example

# Message event

Webhook event object which contains the sent message. The message property contains a message object which corresponds with the message type. You can reply to message events.

timestamp, source etc.

Please refer to Common Properties.

type

String

message

replyToken

String

Token for replying to the event

message

Object

Object containing the contents of the message. Message types include:

Text
Image
Video
Audio
File
Location
Sticker

# Text

Message object which contains the text sent from the source.

String

Message ID

type

String

text

text

String

Message text. If text contains LINE emojis, the emojis property will contain an array of LINE emoji objects.

emojis

Array of LINE emoji objects

One or more LINE emojis. Unicode-defined emojis and older versions of LINE emojis may not be retrieved correctly.

emojis[].index

Number

Index position for a character in text, with the first character being at position 0.

emojis[].length

Number

The length of the LINE emoji string. For LINE emoji (hello), 7 is the length.

emojis[].productId

String

Product ID for a LINE emoji set. See Sendable LINE emoji list (opens new window) for an example of a product ID.

emojis[].emojiId

String

ID for a LINE emoji inside a set. See Sendable LINE emoji list (opens new window) for an example of a emoji ID.

Text message example

# Image

Message object which contains the image content sent from the source.

String

Message ID

type

String

image

contentProvider.type

String

Provider of the image file.

line: The image was sent by a LINE user. The binary image data can be retrieved from the content endpoint.
external: The image was sent using the LIFF liff.sendMessages() method. For more information, see liff.sendMessages() in the LIFF API reference.

contentProvider.originalContentUrl

String

URL of the image file. Only included when contentProvider.type is external.

contentProvider.previewImageUrl

String

URL of the preview image. Only included when contentProvider.type is external.

Image message example

# Video

Message object which contains the video content sent from the source. The preview image is displayed in the chat and the video is played when the image is tapped.

String

Message ID

type

String

video

duration

Number

Length of video file (milliseconds)

contentProvider.type

String

Provider of the video file.

line: The video was sent by a LINE user. The binary video data can be retrieved from the content endpoint.
external: The video was sent using the LIFF liff.sendMessages() method. For more information, see liff.sendMessages() in the LIFF API reference.

contentProvider.originalContentUrl

String

URL of the video file. Only included when contentProvider.type is external.

contentProvider.previewImageUrl

String

URL of the preview image. Only included when contentProvider.type is external.

Video message example

# Audio

Message object which contains the audio content sent from the source.

String

Message ID

type

String

audio

duration

Number

Length of audio file (milliseconds)

contentProvider.type

String

Provider of the audio file.

line: The audio file was sent by a LINE user. The binary audio data can be retrieved from the content endpoint.
external: The audio file was sent using the LIFF liff.sendMessages() method. For more information, see liff.sendMessages() in the LIFF API reference.

contentProvider.originalContentUrl

String

URL of the audio file. Only included when contentProvider.type is external.

Audio message example

# File

Message object which contains the file sent from the source. The binary data can be retrieved from the content endpoint.

String

Message ID

type

String

file

fileName

String

File name

fileSize

Number

File size in bytes

File message example

# Location

Message object which contains the location data sent from the source.

String

Message ID

type

String

location

title

String

Title

address

String

Address

latitude

Decimal

Latitude

longitude

Decimal

Longitude

Location message example

# Sticker

Message object which contains the sticker data sent from the source. For a list of basic LINE stickers and sticker IDs, see sticker list.

Sticker image

You can't get the image of stickers sent by users.

String

Message ID

type

String

sticker

packageId

String

Package ID

stickerId

String

Sticker ID

stickerResourceType

String

Sticker resource type. One of:

STATIC: Still image
ANIMATION: Animated sticker
SOUND: Sticker with sound
ANIMATION_SOUND: Animated sticker with sound
POPUP: Pop-up sticker or Effect sticker
POPUP_SOUND: Pop-up sticker with sound or Effect sticker with sound
NAME_TEXT: Custom sticker. You can't retrieve the sticker's custom text with the Messaging API.
PER_STICKER_TEXT: Message sticker. You can't retrieve the sticker's custom text with the Messaging API.

About sticker resource types

In the future, we may add new types without notice. Make sure your implementation can handle both current and future sticker resource types.

Sticker message example

# Unsend event

Event object for when the user unsends a message in a group or room.

timestamp, source etc.

Please refer to Common Properties.

type

String

unsend

unsend.messageId

String

The message ID of the unsent message

Unsend event example

# Follow event

Event object for when your LINE Official Account is added as a friend (or unblocked). You can reply to follow events.

timestamp, source etc.

Please refer to Common Properties.

type

String

follow

replyToken

String

Token for replying to this event

Follow event example

# Unfollow event

Event object for when your LINE Official Account is blocked.

timestamp, source etc.

Please refer to Common Properties.

type

String

unfollow

Unfollow event example

# Join event

Event object for when your LINE Official Account joins a group or room. You can reply to join events.

A join event is triggered at different times for groups and rooms.

For groups: A join event is sent when a user invites your LINE Official Account.
For rooms: A join event is sent when the first event (for example when a user sends a message or is added to the room) occurs after your LINE Official Account is added.

timestamp, source etc.

Please refer to Common Properties.

type

String

join

replyToken

String

Token for replying to this event

Join event example

# Leave event

Event object for when a user removes your LINE Official Account from a group or when your LINE Official Account leaves a group or room.

timestamp, source etc.

Please refer to Common Properties.

type

String

leave

Leave event example

# Member join event

Event object for when a user joins a group or room that the LINE Official Account is in.

timestamp, source etc.

Please refer to Common Properties.

type

String

memberJoined

joined.members

Array of source user objects

User ID of users who joined

replyToken

String

Token for replying to this event

Member join event example

# Member leave event

Event object for when a user leaves a group or room that the LINE Official Account is in.

timestamp, source etc.

Please refer to Common Properties.

type

String

memberLeft

left.members

Array of source user objects

User ID of users who left

Member leave event example

# Postback event

Event object for when a user performs a postback action which initiates a postback. You can reply to postback events.

timestamp, source etc.

Please refer to Common Properties.

type

String

postback

replyToken

String

Token for replying to this event

postback.data

String

Postback data

postback.params

Object

JSON object with the date and time selected by a user through a datetime picker action.
Only returned for postback actions via a datetime picker action.

Postback event example

# `postback.params` object

Object with the date and time selected by a user through a datetime picker action. The full-date, time-hour, and time-minute formats follow the RFC3339 protocol (opens new window).

Property	Format	Description
date	full-date	Date selected by user. Only included in the `date` mode.
time	time-hour ":" time-minute	Time selected by the user. Only included in the `time` mode.
datetime	full-date "T" time-hour ":" time-minute	Date and time selected by the user. Only included in the `datetime` mode.

postback.params object example

# Video viewing complete event

Event for when a user finishes viewing a video at least once with the specified trackingId sent by the LINE Official Account.

The number of video views

A video viewing complete event doesn't necessarily indicate the number of times a user has watched a video.

Watching a video multiple times in a single session in a chat room doesn't result in a duplicate event. However, if you close the chat room and reopen it to watch the video again, the event may reoccur.

type

String

videoPlayComplete

replyToken

String

Token for replying to this event.

videoPlayComplete.trackingId

String

ID used to identify a video. Returns the same value as the trackingId assigned to the video message.

Video viewing complete event example

# Beacon event

Event object for when a user enters the range of a LINE Beacon. You can reply to beacon events.

timestamp, source etc.

Please refer to Common Properties.

type

String

beacon

replyToken

String

Token for replying to this event

beacon.hwid

String

Hardware ID of the beacon that was detected

beacon.type

String

Type of beacon event. See Beacon event types.

beacon.dm

String

Device message of beacon that was detected. This message consists of data generated by the beacon to send notifications to bot servers. Only included in webhook events from devices that support the "device message" property.
For more information, see the LINE Simple Beacon specification (opens new window).

Beacon event example

# Beacon event types

beacon.type	Description
`enter`	Entered beacon's reception range
~~`leave`~~	[To be deprecated at the end of 2020] ~~Left beacon's reception range.~~
`banner`	Tapped beacon banner
`stay`	A user is within the range of the beacon's reception. This event is sent repeatedly at a minimum interval of 10 seconds.

If you are interested in using the banner and stay event, make an inquiry through the LINE for Business (opens new window) website.

# Account link event

Event object for when a user has linked his/her LINE account with a provider's service account. You can reply to account link events.

If the link token has expired or has already been used, no webhook event will be sent and the user will be shown an error.

timestamp, source etc.

Please refer to Common Properties.

type

String

accountLink

replyToken

String

Token for replying to this event. This value will not be included if the link has failed.

link

Object

link object. This will include whether the account link was successful or not and a nonce (number used once) generated from the user ID on the provider's service.

Account link event example

# `link` object

result

String

One of the following values to indicate whether the link was successful or not.

ok: Indicates the link was successful.
failed: Indicates the link failed for any reason, such as due to a user impersonation.

nonce

String

Specified nonce when verifying the user ID

Example link object

# Device link event

Indicates that a user linked a device with LINE.

timestamp, source etc.

Please refer to Common Properties.

type

String

things

replyToken

String

Token for replying to this event

things.deviceId

String

Device ID of the device that has been linked with LINE.

things.type

String

link

If you use the LINE Things API, you can identify the device that has been linked or unlinked by the user from the device ID acquired by the Webhook event. For more information about the API, see Getting the product ID and PSDI by specifying the device ID in the LINE Things API reference.

Device link event example

# Device unlink event

Indicates that the user unlinked a device from LINE.

timestamp, source etc.

Please refer to Common Properties.

type

String

things

replyToken

String

Token for replying to this event

things.deviceId

String

Device ID of the device that was unlinked from LINE.

things.type

String

unlink

Device unlink event example

# LINE Things scenario execution event

This event indicates that an automatic communication scenario has been executed.

Rather than returning an aggregated result for a scenario set, an execution result is returned for each individual scenario.

Note

The order in which execution results are returned is independent of the order of the scenarios.

timestamp, source etc.

Please refer to Common Properties.

type

String

things

replyToken

String

Token for replying to this event

things.deviceId

String

Device ID of the device that executed the scenario

things.type

String

scenarioResult

things.result.scenarioId

String

Scenario ID executed

things.result.revision

Number

Revision number of the scenario set containing the executed scenario

things.result.startTime

Number

Timestamp for when execution of scenario action started (milliseconds, LINE app time)

things.result.endTime

Number

Timestamp for when execution of scenario was completed (milliseconds, LINE app time)

things.result.resultCode

String

Scenario execution completion status
See also things.result.resultCode definitions.

things.result.actionResults

Array

Execution result of individual operations specified in action
Note that an array of actions specified in a scenario has the following characteristics

The actions defined in a scenario are performed sequentially, from top to bottom.
Each action produces some result when executed.
Even actions that do not generate data, such as SLEEP, return an execution result of type void.
The number of items in an action array may be 0.

Therefore, things.result.actionResults has the following properties:

The number of items in the array matches the number of actions defined in the scenario.
The order of execution results matches the order in which actions are performed. That is, in a scenario set with multiple GATT_READ actions, the results are returned in the order in which each individual GATT_READ action was performed.
If 0 actions are defined in the scenario, the number of items in things.result.actionResults will be 0.

things.result.actionResults[].type

String

void, binary

Depends on type of the executed action.
This property is always included if things.result.actionResults is not empty.

things.result.actionResults[].data

String

Base64-encoded binary data
This property is always included when things.result.actionResults[].type is binary.

things.result.bleNotificationPayload

String

Data contained in notification
The value is Base64-encoded binary data. Only included for scenarios where trigger.type = BLE_NOTIFICATION.

things.result.errorReason

String

Error reason

Example of LINE Things scenario execution event

# things.result.resultCode definition

resultCode	Description
success	Indicates that the execution has completed successfully
gatt_error	Indicates that the execution of the GATT operation failed GATT Service UUID is incorrect. GATT Characteristic UUID is incorrect. Attempted to write to a characteristic that cannot be written to.
runtime_error	Indicates that an unexpected error has occurred When an unexpected error has occurred

# Webhook settings

You can configure, test, and get information on channel webhook endpoints.

# Set webhook endpoint URL

Sets the webhook endpoint URL. It may take up to 1 minute for changes to take place due to caching.

Webhook URL validation rules

Please ensure these webhook URL validation rules are met:

Enter a valid HTTPS URL.
Must be 500 characters or less.

Example request

# HTTP request

PUT https://api.line.me/v2/bot/channel/webhook/endpoint

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

endpoint

String

Required

A valid webhook URL.

# Response

Returns status code 200 and an empty JSON object.

Example response

# Error response

Returns a 400 HTTP status code if the webhook URL is invalid.

Example error response

# Get webhook endpoint information

Gets information on a webhook endpoint.

Example request

# HTTP request

GET https://api.line.me/v2/bot/channel/webhook/endpoint

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Response

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

endpoint

String

Webhook URL

active

Boolean

Webhook usage status. Send a webhook event from the LINE platform to the webhook URL only if enabled.

true: Webhook usage is enabled.
false: Webhook usage is disabled.

Example response

# Test webhook endpoint

Checks if the configured webhook endpoint can receive a test webhook event.

Webhook URL validation rules

Please ensure these webhook URL validation rules are met:

Enter a valid HTTPS URL.
Must be 500 characters or less.

Example request

# HTTP request

POST https://api.line.me/v2/bot/channel/webhook/test

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

endpoint

String

Optional

A webhook URL to be validated.

Behaviors with/without endpoint parameter

The behavior of this API endpoint will differ depending on if the endpoint parameter is included in, or excluded from, the Request body.

With endpoint parameter

Validates that the endpoint URL specified in the endpoint parameter is valid and, if valid, sends a test webhook event to the specified endpoint URL.

Without endpoint parameter

Sends a test webhook event to a webhook endpoint that is already set to the channel. 404 is returned if the channel doesn't have a webhook endpoint configured.

# Response

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

Return status code 200 for the communication request

The LINE Platform sends an HTTP POST request that doesn't include a webhook event to the webhook URL (bot server) to confirm communication. Design your bot server to return status code 200.

Example HTTP POST request without a webhook event:
```
{
    "destination": "xxxxxxxxxx",
    "events": []
}
```

success

Boolean

Result of the communication from the LINE platform to the webhook URL.

true: Success
false: Failure

timestamp

String

Please refer to Common Properties.

statusCode

Int

The HTTP status code. If the webhook response isn't received, the status code is set to zero or a negative number.

reason

String

Reason for the response. See table below for more information.

detail

String

Details of the response. See table below for more information.

`reason`	`detail`	Description
OK	`200`	Successfully sent the webhook
COULD_NOT_CONNECT	Failure to connect message (Example: Connection failed: {webhook endpoint url})	Failed to connect
ERROR_STATUS_CODE	HTTP status code (Example: `400`)	HTTP status code error response
REQUEST_TIMEOUT	Request timeout	Request time out
UNCLASSIFIED	N/A	Unknown error

Example response

# Error response

Returns a 400 HTTP status code if the webhook URL isn't valid.
Returns a 404 HTTP status code if the webhook URL isn't set.

# OAuth

You can issue, get, or revoke the channel access token required when calling the Messaging API from the app.

# Issue channel access token v2.1

Issues a channel access token. This method lets you use JWT assertion for authentication.

You can issue up to 30 tokens. If you reach the maximum limit, additional requests of issuing channel access tokens are blocked.

Example request

# HTTP request

POST https://api.line.me/oauth2/v2.1/token

# Request headers

Content-Type

application/x-www-form-urlencoded

# Request body

grant_type

String

client_credentials

client_assertion_type

String

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion

String

A JSON Web Token the client needs to create and sign with the private key created when issuing an assertion signing key.

JWT expiration

The JSON Web Token will expire 30 minutes after being created.

Learn how to Generate a JWT.

# Response

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

access_token

String

Channel access token.

expires_in

Number

Amount of time in seconds from issue to expiration of the channel access token

token_type

String

Bearer

key_id

String

Unique key ID for identifying the channel access token.

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

error

String

Error summary

error_description

String

Details of the error. Not returned in certain situations.

Example error response

# Get all valid channel access token key IDs v2.1

Gets all valid channel access token key IDs.

Example request

# HTTP request

GET https://api.line.me/oauth2/v2.1/tokens/kid

# Request body

client_assertion_type

String

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion

String

A JSON Web Token (JWT) (opens new window) the client needs to create and sign with the private key.

# Response

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

kids

Array of strings

Array of channel access token key IDs.

Example response

# Error response

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

error

String

Error summary

error_description

String

Details of the error. Not returned in certain situations.

Example error response

# Revoke channel access token v2.1

Revokes a channel access token.

Example request

# HTTP request

POST https://api.line.me/oauth2/v2.1/revoke

# Request body

client_id

String

Channel ID

client_secret

String

Channel Secret

access_token

String

Channel access token

# Response

Returns status code 200 and an empty response body.

Note

No error occurs if an invalid channel access token is specified.

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

error

String

Error summary

error_description

String

Details of the error. Not returned in certain situations.

Example error response

# Issue channel access token

Issues a short-lived channel access token that's valid for 30 days.

You can issue up to 30 tokens. If the maximum is exceeded, the oldest existing channel access token is revoked.

Tip

For Messaging API channels, you can issue a long-term channel access token or a channel access token (channel access token v2.1) that allows you to specify an expiration time.
For more information, see Channel access tokens in the Messaging API documentation.
Channel access tokens for LINE Login channels can also be issued with this API.
The channel access token for the LINE Login channel is available in the LIFF v1 Server API.

Example request

# HTTP request

Try

# Request headers

Content-Type

application/x-www-form-urlencoded

# Request body

grant_type

String

Required

client_credentials

client_id

String

Required

Channel ID. Found on the LINE Developers Console.

client_secret

String

Required

Channel secret. Found on the LINE Developers Console.

# Response

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

access_token

String

Short-lived channel access token. Valid for 30 days.

Note

Channel access tokens cannot be refreshed.

expires_in

Number

Time until channel access token expires in seconds from time the token is issued

token_type

String

Bearer

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

error

String

Error summary

error_description

String

Details of the error. Not returned in certain situations.

Example error response

# Revoke channel access token

Revokes a channel access token.

Example request

# HTTP request

Try

# Request headers

Content-Type

application/x-www-form-urlencoded

# Request body

access_token

String

Required

Channel access token

# Response

Returns status code 200 and an empty response body. No error occurs if an invalid channel access token is specified.

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

error

String

Error summary

error_description

String

Details of the error. Not returned in certain situations.

Example error response

# Message

You can send a message and obtain information about the sent message.

# Send reply message

Sends a reply message in response to an event from a user, group, or room.

To send reply messages, you must have a reply token which is included in a webhook event object.

Webhooks are used to notify you when an event occurs. For events that you can respond to, a reply token is issued for replying to messages.

Because the reply token becomes invalid after a certain period of time, responses should be sent as soon as a message is received. Reply tokens can only be used once.

Example request

# HTTP request

POST https://api.line.me/v2/bot/message/reply

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Request body

replyToken

String

Required

Reply token received via webhook

messages

Array of message objects

Required

Messages to send
Max: 5

notificationDisabled

Boolean

Optional

true: The user doesn't receive a push notification when the 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).

Default: false

# Response

Returns status code 200 and an empty JSON object.

Example response

# Send push message

Sends a push message to a user, group, or room at any time.

Example request

# HTTP request

POST https://api.line.me/v2/bot/message/push

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Request body

String

Required

ID of the target recipient. Use a userId, groupId, or roomId value returned in a webhook event object. Do not use the LINE ID found on LINE.

messages

Array of message objects

Required

Messages to send
Max: 5

notificationDisabled

Boolean

Optional

true: The user doesn't receive a push notification when the 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).

Default: false

# Response

Returns status code 200 and an empty JSON object.

Example response

# Send multicast message

Sends push messages to multiple users at any time. Messages cannot be sent to groups or rooms.

Example request

# HTTP request

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

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Request body

Array of strings

Required

Array of user IDs. Use userId values which are returned in webhook event objects. Do not use LINE IDs found on LINE.
Max: 500 user IDs

messages

Array of message objects

Required

Messages to send
Max: 5

notificationDisabled

Boolean

Optional

true: The user doesn't receive a push notification when the 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).

Default: false

# Response

Returns status code 200 and an empty JSON object.

Example response

# Send narrowcast message

Some audiences for impression-based retargeting have been disabled

Audiences created for impression-based retargeting using messages delivered between March 30, 2020 00:00 and April 22, 2020 21:30 have been disabled. For details, see Notice about service outage in the aggregation of some APIs for 'Audience' and 'Insight'.

Sends a push message to multiple users. You can specify recipients using attributes (such as age, gender, OS, and region) or by retargeting (audiences). Messages cannot be sent to groups or rooms.

Usage restrictions of narrowcast messages

To prevent someone from guessing the recipients' attributes, narrowcast messages can't be sent when the number of recipients is below the required minimum amount.

Please take note of the following:

To use attribute data, your "Target reach" number must be 100 or more.
Combine audience and attribute data so that the number of recipients is 50 or more. If this criterion isn't met, you can't send narrowcast messages. However, you can send to less than 50 people if:
- You use an audience for uploading the user ID without using attribute data
- You use the chat tag audience
When sending narrowcast messages, you can specify up to 10 audiences (recipient objects).

Message delivery caps

When you send a narrowcast message, the number of individual messages scheduled for delivery is temporarily calculated as if every single friend will receive them regardless of the values you have set for the recipient and filter.demographic properties. If the number of messages scheduled for delivery exceeds your soft limit for the month, you won't be able to send the narrowcast message.

However, if the maximum number of outgoing messages set in limit.max is under your soft limit for the month, you will be able to send the narrowcast message.

Also, by setting the limit.upToRemainingQuota property to true, even if the number of messages scheduled for delivery exceeds the maximum number of deliverable messages, an error will not occur. It will be delivered within the maximum limit.

You can see the current month’s target limit for additional messages by using the Get the target limit for additional messages endpoint.

For more information on how to set the approximate target limit, see Messaging API pricing.

# HTTP request

POST https://api.line.me/v2/bot/message/narrowcast

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

messages

Array of message objects

Required

Messages to send
Max: 5

recipient

Object

Optional

Recipient object. You can specify recipients of the message using up to 10 audiences or the request IDs of the narrowcast messages previously sent.
If this is omitted, messages will be sent to all users who have added your LINE Official Account as a friend.

filter.demographic

Object

Optional

Demographic filter object. You can use friends' attributes to filter the list of recipients.
If this is omitted, messages are sent to everyone—including users with attribute values of "unknown".

limit.max

Number

Optional

The maximum number of narrowcast messages to send. Use this parameter to limit the number of narrowcast messages sent. The recipients will be chosen at random.

limit.upToRemainingQuota

Boolean

Optional

If true, the message will be sent within the maximum number of deliverable messages. The default value is false.

Targets will be selected at random.

notificationDisabled

Boolean

Optional

true: The user doesn't receive a push notification when the 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 on their device).

Default: false

Example request

# Recipient objects

Recipient objects represent audience objects or redelivery objects. You can specify recipients based on a combination of criteria using logical operator objects. You can specify up to 10 recipient objects per request.

Audience objects

type

String

Required

audience

audienceGroupId

Number

Required

The audience ID. Create audiences with the manage audience API.
Redelivery object

type

String

Required

redelivery

requestId

String

Required

The request ID of the narrowcast message previously sent. The request IDs is an ID issued for each Messaging API request. It is included in the response header.
Conditions for specifying the request ID
The request ID specified in the requestId property must satisfy all of these conditions:
- The request ID was issued by the delivering a narrowcast message
- The narrowcast message was delivered within the past seven days
- The delivery process is completed (The value of the phase property is succeeded in the response of the Get narrowcast message status endpoint)
Logical operator objects

Use logical AND, OR, and NOT operators to combine multiple recipient objects together.

type

String

Required

operator

and

Array of recipient objects

*

Create a new recipient object by taking the logical conjunction (AND) of the specified array of recipient objects.

or

Array of recipient objects

*

Create a new recipient object by taking the logical disjunction (OR) of the specified array of recipient objects.

not

Recipient object

*

Create a new recipient object that excludes the specified recipient object.

* Be sure to specify only one of these three properties (and, or, or not). You cannot specify an empty array.

Example recipient object

# Demographic filter objects

Demographic filter objects represent criteria (e.g. age, gender, OS, region, and friendship duration) on which to filter the list of recipients. You can filter recipients based on a combination of different criteria using logical operator objects.

Using attribute data

The attribute data used for demographic filters is always 3 days old.
If you don't specify any attributes, messages are sent to everyone—even users with attribute values of "unknown".
Your "Target reach" number must be at least 20 to retrieve demographic information.

Gender
type

String

Required

gender
oneOf

Array of strings

Required
Send messages to users of a given gender. One of:
- male
- female
Age

This lets you filter recipients with a given age range.
type

String

Required

age
gte

String

*
Send messages to users at least as old as the specified age.
One of:
- age_15
- age_20
- age_25
- age_30
- age_35
- age_40
- age_45
- age_50
lt

String

*

Send messages to users younger than the specified age.
You can specify the same values as for the gte property.
* Be sure to specify either gte, lt, or both.
Operating system
type

String

Required

appType
oneOf

Array of strings

Required
Send messages to users with the specified OS. One of:
- ios
- android
Region
type

String

Required

area
oneOf

Array of strings

Required
Send messages to users in the specified region. One of:
日本 // JP (country code=392)
- jp_01: 北海道 // Hokkaido
- jp_02: 青森県 // Aomori
- jp_03: 岩手県 // Iwate
- jp_04: 宮城県 // Miyagi
- jp_05: 秋田県 // Akita
- jp_06: 山形県 // Yamagata
- jp_07: 福島県 // Fukushima
- jp_08: 茨城県 // Ibaraki
- jp_09: 栃木県 // Tochigi
- jp_10: 群馬県 // Gunma
- jp_11: 埼玉県 // Saitama
- jp_12: 千葉県 // Chiba
- jp_13: 東京都 // Tokyo
- jp_14: 神奈川県 // Kanagawa
- jp_15: 新潟県 // Niigata
- jp_16: 富山県 // Toyama
- jp_17: 石川県 // Ishikawa
- jp_18: 福井県 // Fukui
- jp_19: 山梨県 // Yamanashi
- jp_20: 長野県 // Nagano
- jp_21: 岐阜県 // Gifu
- jp_22: 静岡県 // Shizuoka
- jp_23: 愛知県 // Aichi
- jp_24: 三重県 // Mie
- jp_25: 滋賀県 // Shiga
- jp_26: 京都府 // Kyoto
- jp_27: 大阪府 // Osaka
- jp_28: 兵庫県 // Hyougo
- jp_29: 奈良県 // Nara
- jp_30: 和歌山県 // Wakayama
- jp_31: 鳥取県 // Tottori
- jp_32: 島根県 // Shimane
- jp_33: 岡山県 // Okayama
- jp_34: 広島県 // Hiroshima
- jp_35: 山口県 // Yamaguchi
- jp_36: 徳島県 // Tokushima
- jp_37: 香川県 // Kagawa
- jp_38: 愛媛県 // Ehime
- jp_39: 高知県 // Kouchi
- jp_40: 福岡県 // Fukuoka
- jp_41: 佐賀県 // Saga
- jp_42: 長崎県 // Nagasaki
- jp_43: 熊本県 // Kumamoto
- jp_44: 大分県 // Oita
- jp_45: 宮崎県 // Miyazaki
- jp_46: 鹿児島県 // Kagoshima
- jp_47: 沖縄県 // Okinawa
台湾 // TW (country code=158)
- tw_01: 台北市 // Taipei City
- tw_02: 新北市 // New Taipei City
- tw_03: 桃園市 // Taoyuan City
- tw_04: 台中市 // Taichung City
- tw_05: 台南市 // Tainan City
- tw_06: 高雄市 // Kaohsiung City
- tw_07: 基隆市 // Keelung City
- tw_08: 新竹市 // Hsinchu City
- tw_09: 嘉義市 // Chiayi City
- tw_10: 新竹県 // Hsinchu County
- tw_11: 苗栗県 // Miaoli County
- tw_12: 彰化県 // Changhua County
- tw_13: 南投県 // Nantou County
- tw_14: 雲林県 // Yunlin County
- tw_15: 嘉義県 // Chiayi County
- tw_16: 屏東県 // Pingtung County
- tw_17: 宜蘭県 // Yilan County
- tw_18: 花蓮県 // Hualien County
- tw_19: 台東県 // Taitung County
- tw_20: 澎湖県 // Penghu County
- tw_21: 金門県 // Kinmen County
- tw_22: 連江県 // Lienchiang County
タイ // TH (country code=764)
- th_01: バンコク // Bangkok
- th_02: パタヤ // Pattaya
- th_03: 北部 // Northern
- th_04: 中央部 // Central
- th_05: 南部 // Southern
- th_06: 東部 // Eastern
- th_07: 東北部 // NorthEastern
- th_08: 西部 // Western
インドネシア // ID (country code=360)
- id_01: バリ // Bali
- id_02: バンドン // Bandung
- id_03: バンジャルマシン // Banjarmasin
- id_04: ジャボデタベック（ジャカルタ首都圏） // Jabodetabek
- id_06: マカッサル // Makassar
- id_07: メダン // Medan
- id_08: パレンバン // Palembang
- id_09: サマリンダ // Samarinda
- id_10: スマラン // Semarang
- id_11: スラバヤ // Surabaya
- id_12: ジョグジャカルタ // Yogyakarta
- id_05: その他のエリア // Lainnya
Friendship duration

This lets you filter recipients with a given range of friendship durations.
type

String

Required

subscriptionPeriod
gte

String

*
Send messages to users who have been friends of yours for at least the specified number of days.
One of:
- day_7
- day_30
- day_90
- day_180
- day_365
lt

String

*

Send messages to users who have been friends of yours for less than the specified number of days.
You can specify the same values as for the gte property.
* Be sure to specify either gte, lt, or both.
Logical operator objects

Use logical AND, OR, and NOT operators to combine multiple demographic filter objects together. You can specify up to 10 demographic filter objects per request.

type

String

Required

operator

and

Array of demographic filter objects

*

Create a new demographic filter object by taking the logical conjunction (AND) of the specified array of demographic filter objects.

or

Array of demographic filter objects

*

Create a new demographic filter object by taking the logical disjunction (OR) of the specified array of demographic filter objects.

not

Demographic filter object

*

Create a new demographic filter object that excludes the specified array of demographic filter objects.

* Be sure to specify only one of these three properties (and, or, or not). You cannot specify an empty array.

Example demographic filter object for gender

# Response

Returns the 202 HTTP status code.

Narrowcast messages are sent asynchronously

For more information on how to check the status of a narrowcast message, see Get narrowcast message status.

# Get narrowcast message status

Gets the status of a narrowcast message.

Narrowcast messages can't be sent if the number of recipients is less than the required amount

To prevent someone from guessing the recipients' attributes, narrowcast messages can't be sent when the number of recipients is below the required minimum amount.

For more information, see Usage restrictions of narrowcast messages in the Messaging API reference.

Window of availability for status requests

You can get the status of a narrowcast message for up to 7 days after you have requested that it be sent.

Example request

# HTTP request

GET https://api.line.me/v2/bot/message/progress/narrowcast

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

requestId

Required

The narrowcast message's request ID. Each Messaging API request has a request ID. Find it in the response headers.

# Response

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

phase

String

The current status. One of:

waiting: Messages are not yet ready to be sent. They are currently being filtered or processed in some way.
sending: Messages are currently being sent.
succeeded: Messages were sent successfully. This may not mean the messages were successfully received.
failed: Messages failed to be sent. Use the failedDescription property to find the cause of the failure.

successCount

Number

The number of users who successfully received the message. *

failureCount

Number

The number of users who failed to send the message. *
Even if the phase is succeeded, some users may not be able to receive narrowcast messages unless the failureCount is 0. For example, if a user blocks the LINE Official Account while sending a narrowcast message, it will be added to the failureCount.

targetCount

Number

The number of intended recipients of the message. *

failedDescription

String

The reason the message failed to be sent. This is only included with a phase property value of failed.

errorCode

Number

Error summary. One of:

1: An internal error occurred.
2: An error occurred because there weren't enough recipients.
3: A conflict error of requests occurs because a request that has already been accepted is retried.

* Not available when the phase property is waiting.

# Error response

An HTTP 404 status code is returned if you specify an invalid request ID or a request ID that is not associated with a narrowcast message.

# Send broadcast message

Sends push messages to multiple users at any time.

Example request

# HTTP request

POST https://api.line.me/v2/bot/message/broadcast

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Request body

messages

Array of message objects

Required

Messages to send
Max: 5

notificationDisabled

Boolean

Optional

true: The user doesn't receive a push notification when the 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).

Default: false

# Response

Returns status code 200 and an empty JSON object.

Example response

# Get content

Gets images, videos, audio, and files sent by users.

No API for retrieving text

You can't use the Messaging API to retrieve text sent by users.

Example request

# HTTP request

GET https://api-data.line.me/v2/bot/message/{messageId}/content

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

messageId

Message ID

# Response

Returns status code 200 and the content in binary.

Content is automatically deleted after a certain period from when the message was sent. There is no guarantee for how long content is stored.

# Get the target limit for additional messages

Gets the target limit for additional messages in the current month.

The number of messages retrieved by this operation includes the number of messages sent from LINE Official Account Manager.

Set a target limit with LINE Official Account Manager. For the procedures, refer to the LINE Official Account Manager manual.

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Response

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

type

String

One of the following values to indicate whether a target limit is set or not.

none. This indicates that a target limit is not set.
limited. This indicates that a target limit is set.

value

Number

The target limit for additional messages in the current month. This property is returned when the type property has a value of limited.

Example response

# Get number of messages sent this month

Gets the number of messages sent in the current month.

The number of messages retrieved by this operation includes the number of messages sent from LINE Official Account Manager.

The number of messages retrieved by this operation is approximate. To get the correct number of sent messages, use LINE Official Account Manager or execute API operations for getting the number of sent messages.

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Response

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

totalUsage

Number

The number of sent messages in the current month

Example response

# Get number of sent reply messages

Gets the number of messages sent with the /bot/message/reply endpoint.

The number of messages retrieved by this operation does not include the number of messages sent from LINE Official Account Manager.

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date the messages were sent

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

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

status

String

Status of the counting process. One of the following values is returned:

ready: You can get the number of messages.
unready: The message counting process for the date specified in date has not been completed yet. Retry your request later. Normally, the counting process is completed within the next day.
out_of_service: The date specified in date is earlier than March 31, 2018, when the operation of the counting system started.

success

Number

The number of messages sent with the Messaging API on the date specified in date. The response has this property only when the value of status is ready.

Example response

# Get number of sent push messages

Gets the number of messages sent with the /bot/message/push endpoint.

The number of messages retrieved by this operation does not include the number of messages sent from LINE Official Account Manager.

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date the messages were sent

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

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

status

String

Status of the counting process. One of the following values is returned:

ready: You can get the number of messages.
unready: The message counting process for the date specified in date has not been completed yet. Retry your request later. Normally, the counting process is completed within the next day.
out_of_service: The date specified in date is earlier than March 31, 2018, when the operation of the counting system started.

success

Number

The number of messages sent with the Messaging API on the date specified in date. The response has this property only when the value of status is ready.

Example response

# Get number of sent multicast messages

Gets the number of messages sent with the /bot/message/multicast endpoint.

The number of messages retrieved by this operation does not include the number of messages sent from LINE Official Account Manager.

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date the messages were sent

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

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

status

String

Status of the counting process. One of the following values is returned:

ready: You can get the number of messages.
unready: The message counting process for the date specified in date has not been completed yet. Retry your request later. Normally, the counting process is completed within the next day.
out_of_service: The date specified in date is earlier than March 31, 2018, when the operation of the counting system started.

success

Number

The number of messages sent with the Messaging API on the date specified in date. The response has this property only when the value of status is ready.

Example response

# Get number of sent broadcast messages

Gets the number of messages sent with the /bot/message/broadcast endpoint.

The number of messages retrieved by this operation does not include the number of messages sent from LINE Official Account Manager.

Example request

# HTTP request

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

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date the messages were sent

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

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

status

String

Status of the counting process. One of the following values is returned:

ready: You can get the number of messages.
unready: The message counting process for the date specified in date has not been completed yet. Retry your request later. Normally, the counting process is completed within the next day.
out_of_service: The date specified in date is earlier than March 31, 2018, when the operation of the counting system started.

success

Number

The number of messages sent with the Messaging API on the date specified in date. The response has this property only when the value of status is ready.

Example response

# Retrying an API request

By including the X-Line-Retry-Key request header in the HTTP header of a push message, multicast message, narrowcast message, or broadcast message, the same API request can be reattempted to prevent duplicate processing.

Retrying an API request using a retry key

The retry key lets you retry a request while preventing the same request from being accepted in duplicate. For more information, see Retrying a failed API request.
The retry key is valid for 24 hours after attempting the first request.

Example request

# Request headers

X-Line-Retry-Key

Arbitrarily generated UUID in hexadecimal notation (example: 123e4567-e89b-12d3-a456-426614174000)

# Response

Returns the 409 status code, the response header indicating the request ID of the accepted request, and a JSON object containing this information if a request is accepted.

message

String

A message informing the same request has already been accepted

Example request

# Managing Audience

You can create, update, or delete audience. Specify the audience when sending narrowcast messages.

Audiences can also be created using LINE Official Account Manager (opens new window). To learn more, see Audience (opens new window) in LINE for Business.

Audience	How to create
An audience used for uploading user IDs.	Messaging API LINE Official Account Manager (opens new window)
An audience used for click-based retargeting.	Messaging API LINE Official Account Manager (opens new window)
An audience used for impression-based retargeting.	Messaging API LINE Official Account Manager (opens new window)
Chat tag audience.	LINE Official Account Manager (opens new window)
Friend path audience.	LINE Official Account Manager (opens new window)

Note

Only Japanese (JP), Thai (TH), and Taiwanese (TW) users with LINE Official Accounts can create audiences.
You can't create a chat tag audience and a friend path audience with the Messaging API.

# Create audience for uploading user IDs (by JSON)

Creates an audience for uploading user IDs.

For this endpoint, use JSON to specify recipients. You can also use Endpoint that specifies recipients with text file.

You must complete additional application forms to specify recipients using Identifiers for Advertisers (IFAs)

You can use IFAs to specify recipients, but this feature is only available to corporate users who have completed certain applications. To use it with your LINE Official Account, contact your sales representative or contact our Sales partners (opens new window).

Getting User IDs

You can get User IDs by using the following methods:

The source object of Webhook event objects
Get group member user IDs
Get room member user IDs

Audience used for uploading user IDs

Audience specifications are as follows:

Item	Limit
The number of audiences per channel	Max limit: 1,000
Retention period of an audience	Up to 180 days
The number of user IDs or IFAs you can upload to an audience per request	When using JSON: Max limit: 10,000 When using file: Max limit: 1,500,000
The number of users per audience	Audience for uploading user IDs: No limit

For information on narrowcast message restrictions, see Narrowcast message restrictions.

Verifying a valid user ID

If an invalid user ID is specified in the audiences property of JSON, the error response (details: UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT) will be returned, and adding a user ID will fail. Before you execute this endpoint, please check whether all the user IDs specified in the audiences property of JSON are valid.

To confirm whether a user ID is valid, use the Get profile information endpoint. If the user ID is valid, HTTP status code 200 will be returned. If a value other than 200 is returned, the user ID is invalid and should not be included in the audiences property.

Example request

# HTTP request

POST https://api.line.me/v2/bot/audienceGroup/upload

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

description

String

Required

The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120

isIfaAudience

Boolean

Optional

To specify recipients by IFAs: set true.
To specify recipients by user IDs: set false or omit isIfaAudience property.

uploadDescription

String

Optional

The description to register for the job (in jobs[].description).

audiences

Array

Optional

An array of user IDs or IFAs.
Max number: 10,000

audiences[].id

String

Optional

A user ID or IFA. You can specify an empty array.

# Response

Returns an audience along with the 202 HTTP status code.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

audienceGroupId

Number

The audience ID.

type

String

UPLOAD

description

String

The audience's name.

created

Number

When the audience was created (in UNIX time).

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

AUDIENCE_GROUP_COUNT_MAX_OVER: You have already created the maximum number of audiences (1,000).
AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).
UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT: audiences[].id contains an invalid user ID or IFA.
UPLOAD_AUDIENCE_GROUP_TOO_MANY_AUDIENCE_IDS: Exceeded the maximum number of user IDs or IFAs.

If the audiences property contains invalid user IDs

In the case that UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT is returned, use the Get profile information endpoint to get profile information of all user IDs specified in JSON. After excluding all user IDs that return anything other than status code 200, execute the failed endpoint once again.

# Create audience for uploading user IDs (by file)

Creates an audience for uploading user IDs.

For this endpoint, use a text file to specify recipients. You can also use Endpoint that specifies recipients with JSON.

You must complete additional application forms to specify recipients using Identifiers for Advertisers (IFAs)

Getting User IDs

You can get User IDs by using the following methods:

The source object of Webhook event objects
Get group member user IDs
Get room member user IDs

Audience used for uploading user IDs

Audience specifications are as follows:

Item	Limit
The number of audiences per channel	Max limit: 1,000
Retention period of an audience	Up to 180 days
The number of user IDs or IFAs you can upload to an audience per request	When using JSON: Max limit: 10,000 When using file: Max limit: 1,500,000
The number of users per audience	Audience for uploading user IDs: No limit

Example request

Text file example

# HTTP request

POST https://api-data.line.me/v2/bot/audienceGroup/upload/byFile

# Request headers

Authorization

Bearer {channel access token}

Content-Type

multipart/form-data

# Request body

description

String

Required

The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120

isIfaAudience

Boolean

Optional

To specify recipients by IFAs: set true.
To specify recipients by user IDs: set false or omit isIfaAudience property.

uploadDescription

String

Optional

The description to register for the job (in jobs[].description).

file

File

Required

A text file with one user ID or IFA entered per line. Specify text/plain as Content-Type. Max file number: 1
Max number: 1,500,000

# Response

Returns an audience along with the 202 HTTP status code.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

audienceGroupId

Number

The audience ID.

type

String

UPLOAD

description

String

The audience's name.

created

Number

When the audience was created (in UNIX time).

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT: file contains an invalid user ID or IFA.
UPLOAD_AUDIENCE_GROUP_TOO_MANY_AUDIENCE_IDS: Exceeded the maximum number of user IDs or IFAs.
UPLOAD_AUDIENCE_GROUP_NO_VALID_AUDIENCE_IDS: file doesn't contain a valid user ID or IFA.
AUDIENCE_GROUP_COUNT_MAX_OVER: You have already created the maximum number of audiences (1,000).
AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).

# Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by JSON)

Adds new user IDs or IFAs to an audience for uploading user IDs.

For this endpoint, use JSON to specify recipients. You can also use Endpoint that specifies recipients with text file.

Request timeout values

We strongly recommend using request timeout values of 30 seconds or more.

Verifying a valid user ID

If an invalid user ID is specified in the audiences property of JSON, the error response (details: UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT) will be returned, and audience creation will fail. Before you execute this endpoint, please check whether all the user IDs specified in the audiences property of JSON are valid.

You can't switch between user IDs and IFAs

Add the same type of data (user IDs or IFAs) to an audience for uploading user IDs as you originally specified when creating that audience. For example, you can't add user IDs to an audience that originally used IFAs when it was created.

You can use an audience's isIfaAudience property to determine which type of recipient (user IDs or IFAs) was specified when the audience was created. For more details, see Get audience data.

You can't delete user IDs or IFAs

You cannot delete a user ID or IFA after adding it.

Example request

# HTTP request

PUT https://api.line.me/v2/bot/audienceGroup/upload

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

audienceGroupId

Number

Required

The audience ID.

uploadDescription

String

Optional

The description to register with the job (in jobs[].description).

audiences

Array

Required

An array of up to 10,000 user IDs or IFAs.

audiences[].id

String

Required

A user ID or IFA.

# Response

Returns status code 202 and an empty JSON object.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).
UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT: audiences[].id is an invalid user ID or IFA.
UPLOAD_AUDIENCE_GROUP_TOO_MANY_AUDIENCE_IDS: Exceeded the maximum number of user IDs or IFAs.
UPLOAD_AUDIENCE_GROUP_NO_VALID_AUDIENCE_IDS: No valid user IDs or IFAs were given.
AUDIENCE_GROUP_CAN_NOT_UPLOAD_STATUS_EXPIRED: The audience was created more than 180 days ago. This audience cannot be used.

If the audiences property contains invalid user IDs

# Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by file）

Adds new user IDs or IFAs to an audience for uploading user IDs.

For this endpoint, use a text file to specify recipients. You can also use Endpoint that specifies recipients with JSON.

Request timeout values

We strongly recommend using request timeout values of 30 seconds or more.

You can't switch between user IDs and IFAs

You can use an audience's isIfaAudience property to determine which type of recipient (user IDs or IFAs) was specified when the audience was created. For more details, see Get audience data.

You can't delete user IDs or IFAs

You cannot delete a user ID or IFA after adding it.

Example request

Example text

# HTTP request

PUT https://api-data.line.me/v2/bot/audienceGroup/upload/byFile

# Request headers

Authorization

Bearer {channel access token}

Content-Type

multipart/form-data

# Request body

audienceGroupId

Number

Required

The audience ID.

uploadDescription

String

Optional

The description to register with the job (in jobs[].description).

file

File

Required

A text file with one user ID or IFA entered per line. Specify text/plain as Content-Type. Max file number: 1
Max number: 1,500,000

# Response

Returns status code 202 and an empty JSON object.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT: file contains an invalid user ID or IFA.
UPLOAD_AUDIENCE_GROUP_TOO_MANY_AUDIENCE_IDS: Exceeded the maximum number of user IDs or IFAs.
UPLOAD_AUDIENCE_GROUP_NO_VALID_AUDIENCE_IDS: file doesn't contain a valid user ID or IFA.
AUDIENCE_GROUP_CAN_NOT_UPLOAD_STATUS_EXPIRED: The audience was created more than 180 days ago. This audience cannot be used.

# Create audience for click-based retargeting

Creates an audience for click-based retargeting.

A click-based retargeting audience is a collection of users who have clicked a URL contained in a broadcast or narrowcast message. The message is sent to any user who has clicked at least one link.

Use a request ID to specify the message.

An audience used for click-based retargeting

Audience's specifications are as follows:

Item	Limit
The number of audiences per channel	Max limit: 1,000
Retention period of an audience	Up to 180 days
The number of users per audience	Audience for click-based retargeting: Minimum: 100
The period during which the retargeting audience* can be created after the message is sent	Max limit: 60 days

* Audience for click-based retargeting and audience for impression-based retargeting.

Example request

# HTTP request

POST https://api.line.me/v2/bot/audienceGroup/click

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

description

String

Required

The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120

requestId

String

Required

The request ID of a broadcast or narrowcast message sent in the past 60 days. Each Messaging API request has a request ID. Find it in the response headers.

Note

The request IDs of reply messages, push messages, and multicast messages cannot be used.

clickUrl

String

Optional

The URL clicked by the user. If empty, users who clicked any URL in the message are added to the list of recipients.
Max character limit: 2,000

# Response

Returns an audience along with the 202 HTTP status code.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

audienceGroupId

Number

The audience ID.

type

String

CLICK

description

String

The audience's name.

created

Number

When the audience was created (in UNIX time).

requestId

String

The request ID that was specified when the audience was created.

clickUrl

String

The URL that was specified when the audience was created.

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary

details

String

A description of the error. One of:

AUDIENCE_GROUP_COUNT_MAX_OVER: You have already created the maximum number of audiences (1,000).
AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).
AUDIENCE_GROUP_REQUESTID_DUPLICATE: There is already an audience with the specified request ID.
WRONG_BOT_ID: The bot ID in the specified request ID doesn't match the bot linked to the channel that issued the channel access token.
TOO_OLD_MESSAGES: You can't create an audience for a message (request ID) that was sent over 60 days ago.
REQUEST_NOT_FOUND: The specified request ID is incorrect or LINE not ready to create an audience with the specified request ID.

# Create audience for impression-based retargeting

Note

Due to an issue with impression and open counts on some versions of the LINE app, we are limiting audience creation by the delivery dates of the messages.

Delivery date of the message (JST)	Limit to impression retargeting audience creation
Until March 20, 2020 23:59:59	There are no limits. You can create an audience.
Between March 30, 2020 00:00:00 and April 29, 2020 23:59:59	You can't create an audience.
From April 30, 2020 00:00:00	You can create an audience. However, if a user opens a message during this time period in a LINE app with a version subject to this limit, the user will not receive a new message sent using the audience.

Creates an audience for impression-based retargeting.

An impression-based retargeting audience is a collection of users who have viewed a broadcast or narrowcast message. The audience will include any user who has viewed at least one message bubble.

Use a request ID to specify the message.

An audience used for impression-based retargeting

Audience's specifications are as follows:

Item	Limit
The number of audiences per channel	Max limit: 1,000
Retention period of an audience	Up to 180 days
The number of users per audience	Audience for impression-based retargeting: Minimum: 100
The period during which the retargeting audience* can be created after the message is sent	Max limit: 60 days

* Audience for click-based retargeting and audience for impression-based retargeting.

Example request

# HTTP request

POST https://api.line.me/v2/bot/audienceGroup/imp

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

description

String

Required

The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120

requestId

String

Required

The request ID of a broadcast or narrowcast message sent in the past 60 days. Each Messaging API request has a request ID. Find it in the response headers.

# Response

Returns an audience along with the 202 HTTP status code.

Audience is created asynchronously

Before using an audience, Ensure audience can be used for delivery.

audienceGroupId

Number

The audience ID.

type

String

IMP

description

String

The audience's name.

created

Number

When the audience was created (in UNIX time).

requestId

String

The request ID that was specified when the audience was created.

Example response

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary

details

String

A description of the error. One of:

AUDIENCE_GROUP_COUNT_MAX_OVER: You have already created the maximum number of audiences (1,000).
AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).
AUDIENCE_GROUP_REQUESTID_DUPLICATE: There is already an audience with the specified request ID.
WRONG_BOT_ID: The bot ID in the specified request ID doesn't match the bot linked to the channel that issued the channel access token.
TOO_OLD_MESSAGES: You can't create an audience for a message (request ID) that was sent over 60 days ago.
REQUEST_NOT_FOUND: The specified request ID is incorrect or LINE not ready to create an audience with the specified request ID.

# Rename an audience

Renames an existing audience.

Example request

# HTTP request

PUT https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}/updateDescription

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Path parameters

audienceGroupId

The audience ID.

# Request body

description

String

Required

The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120

# Response

Returns the 200 HTTP status code.

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

AUDIENCE_GROUP_NAME_SIZE_OVER: The audience's name is too long.
AUDIENCE_GROUP_NAME_DUPLICATE: There is already an audience with the specified name.
AUDIENCE_GROUP_NAME_WRONG: The audience's name contains an invalid character (such as \n or some other control character).

# Delete audience

Deletes an audience.

You can't undo deleting an audience

Make sure that an audience is no longer in use before you delete it.

Example request

# HTTP request

DELETE https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

audienceGroupId

The audience ID.

# Response

Returns the 202 HTTP status code.

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

AUDIENCE_GROUP_NOT_FOUND: Audience not found.

# Get audience data

Gets audience data.

Example request

# HTTP request

GET https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

audienceGroupId

The audience ID.

# Response

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

audienceGroupId

Number

The audience ID.

type

String

The audience type. One of:

UPLOAD: An audience used for uploading user IDs.
CLICK: An audience used for click-based retargeting.
IMP: An audience used for impression-based retargeting.
CHAT_TAG: Chat tag audience.
FRIEND_PATH: Friend path audience.

For more information, see the Audience (opens new window) page on LINE for Business. This page isn't currently available in English.

description

String

The audience's name.

status

String

The audience's status. One of:

IN_PROGRESS: Pending. It may take several hours for the status to change to READY.
READY: Ready to accept messages.
FAILED: An error occurred while creating the audience.
EXPIRED: Expired. Audiences are automatically deleted a month after they expire.

failedType

String

The reason why the operation failed. This is only included when status is FAILED. One of:

AUDIENCE_GROUP_AUDIENCE_INSUFFICIENT: There weren't enough accounts in the audience that could be used as recipients (at least 100 are needed).
INTERNAL_ERROR: Internal server error.

audienceCount

Number

The number of valid recipients.

created

Number

When the audience was created (in UNIX time).

requestId

String

The request ID that was specified when the audience was created. This is only included when type is CLICK or IMP.

clickUrl

String

The URL that was specified when the audience was created. This is only included when type is CLICK.

isIfaAudience

Boolean

The value specified when creating an audience for uploading user IDs to indicate the type of accounts that will be given as recipients. One of:

true: Accounts are specified with IFAs.
false (default): Accounts are specified with user IDs.

permission

String

Audience's update permission. Audiences linked to the same channel will be READ_WRITE.

READ: Can use only.
READ_WRITE: Can use and update.

createRoute

String

How the audience was created. If omitted, you will get all audiences.

OA_MANAGER: Audience created with LINE Official Account Manager (opens new window).
MESSAGING_API: Audience created with Messaging API.

jobs

Array

An array of jobs. This array is used to keep track of each attempt to add new user IDs or IFAs to an audience for uploading user IDs. null is returned for any other type of audience.

jobs[].audienceGroupJobId

Number

A job ID.

jobs[].audienceGroupId

Number

An audience ID.

jobs[].description

String

The job's description.

jobs[].type

String

The job's type. One of:

DIFF_ADD: Indicates that a user ID or IFA was added via the Messaging API.

jobs[].jobStatus

String

The job's status. One of:

QUEUED: Waiting to run.
WORKING: Running.
FINISHED: Completed.
FAILED: Failed.

jobs[].failedType

String

The reason why the operation failed. This is only included when jobs[].jobStatus is FAILED. One of:

AUDIENCE_GROUP_AUDIENCE_INSUFFICIENT: There weren't enough accounts in the audience that could be used as recipients (at least 100 are needed).
INTERNAL_ERROR: Internal server error.

jobs[].audienceCount

Number

The number of accounts (recipients) that were added or removed.

jobs[].created

Number

When the job was created (in UNIX time).

# Error response

Returns a 400 HTTP status code and a JSON object with the following information.

message

String

Error summary.

details

String

A description of the error. One of:

AUDIENCE_GROUP_NOT_FOUND: Audience not found.

# Get data for multiple audiences

Gets data for more than one audience.

Example request

# HTTP request

GET https://api.line.me/v2/bot/audienceGroup/list

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

page

Required

The page to return when getting (paginated) results. Must be 1 or higher.

description

Optional

The name of the audience(s) to return. You can search for partial matches. This is case-insensitive, meaning AUDIENCE and audience are considered identical.

status

Optional

The status of the audience(s) to return. One of:

IN_PROGRESS: Pending. It may take several hours for the status to change to READY.
READY: Ready to accept messages.
FAILED: An error occurred while creating the audience.
EXPIRED: Expired. Audiences are automatically deleted a month after they expire.

size

Optional

The number of audiences per page. Default: 20
Max: 40

includesExternalPublicGroups

Optional

true: Get public audiences created in all channels linked to the same bot.
false: Get audiences created in the same channel.

createRoute

Optional

How the audience was created. If omitted, all audiences are included.

OA_MANAGER: Return only audiences created with LINE Official Account Manager (opens new window).
MESSAGING_API: Return only audiences created with Messaging API.

# Response

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

audienceGroups

Array

An array of audience data.

audienceGroups[].audienceGroupId

Number

The audience ID.

audienceGroups[].type

String

The audience type. One of:

UPLOAD: An audience used for uploading user IDs.
CLICK: An audience used for click-based retargeting.
IMP: An audience used for impression-based retargeting.
CHAT_TAG: Chat tag audience.
FRIEND_PATH: Friend path audience.

For more information, see the Audience (opens new window) page on LINE for Business. This page isn't currently available in English.

audienceGroups[].description

String

The audience's name.

audienceGroups[].status

String

The audience's status. One of:

IN_PROGRESS: Pending. It may take several hours for the status to change to READY.
READY: Ready to accept messages.
FAILED: An error occurred while creating the audience.
EXPIRED: Expired. Audiences are automatically deleted a month after they expire.

audienceGroups[].failedType

String

The reason why the operation failed. This is only included when audienceGroups[].status is FAILED or EXPIRED. One of:

AUDIENCE_GROUP_AUDIENCE_INSUFFICIENT: There weren't enough accounts in the audience that could be used as recipients (at least 100 are needed).
INTERNAL_ERROR: Internal server error.

audienceGroups[].audienceCount

Number

The number of valid recipients.

audienceGroups[].created

Number

When the audience was created (in UNIX time).

audienceGroups[].requestId

String

The request ID that was specified when the audience was created. This is only included when audienceGroups[].type is CLICK or IMP.

audienceGroups[].clickUrl

String

The URL that was specified when the audience was created. This is only included when audienceGroups[].type is CLICK.

audienceGroups[].isIfaAudience

Boolean

The value specified when creating an audience for uploading user IDs to indicate the type of accounts that will be given as recipients. One of:

true: Accounts are specified with IFAs.
false (default): Accounts are specified with user IDs.

audienceGroups[].permission

String

Audience's update permission. Audiences linked to the same channel will be READ_WRITE.

READ: Can use only.
READ_WRITE: Can use and update.

audienceGroups[].createRoute

String

How the audience was created. If omitted, all audiences are included.

OA_MANAGER: Audience was created with LINE Official Account Manager (opens new window).
MESSAGING_API: Audience was created with Messaging API.

hasNextPage

Boolean

true when this is not the last page.

totalCount

Int

The total number of audiences that can be returned with the specified filter.

readWriteAudienceGroupTotalCount

Int

Of the audiences you can get with the specified condition, the number of audiences with the update permission set to READ_WRITE.

page

Int

The current page number.

size

Int

The number of audiences on the current page.

# Get the authority level of the audience

Get the authority level of the audience

Note

The authority levels are set for each channel. You can't set different authority levels for different audiences.

Example request

# HTTP request

GET https://api.line.me/v2/bot/audienceGroup/authorityLevel

# Request headers

Authorization

Bearer {channel access token}

# Response

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

authorityLevel

String

The authority level for all audiences linked to a channel

PUBLIC: The default authority level. Audiences will be available in channels other than the one where you created the audience. For example, it will be available in LINE Official Account Manager (opens new window), LINE Ad Manager (opens new window), and all channels the bot is linked to.
PRIVATE: Audiences will be available only in the channel where you created the audience.

# Change the authority level of the audience

Change the authority level of all audiences created in the same channel.

Audiences set to PUBLIC will be available in channels other than the one where you created the audience. For example, it will be available in LINE Official Account Manager (opens new window), LINE Ad Manager (opens new window), and all channels the bot is linked to.
Audiences set to PRIVATE will be available only in the channel where you created the audience.

Note

The authority levels are set for each channel. You can't set different authority levels for different audiences.

Example request

# HTTP request

PUT https://api.line.me/v2/bot/audienceGroup/authorityLevel

# Request headers

Authorization

Bearer {channel access token}

Content-Type

application/json

# Request body

authorityLevel

String

Required

The authority level for all audiences linked to a channel

PUBLIC: The default authority level. Audiences will be available in channels other than the one where you created the audience. For example, it will be available in LINE Official Account Manager (opens new window), LINE Ad Manager (opens new window), and all channels the bot is linked to.
PRIVATE: Audiences will be available only in the channel where you created the audience.

# Response

Returns the HTTP 200 status code.

# Insight

You can obtain information on the number of messages sent from the LINE Official Account, number of friends, and other statistical data.

# Get number of message deliveries

Returns the number of messages sent from LINE Official Account on a specified day.

Example request

# HTTP request

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

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date for which to retrieve number of sent messages.

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

Returns status code 200 and a JSON object with these properties:

status

String

Status of the counting process. One of:

ready: Calculation has finished; the numbers are up-to-date.
unready: We haven't finished calculating the number of sent messages for the specified date. Please try again later. Calculation usually takes about a day.
out_of_service: The specified date is earlier than the date on which we first started calculating sent messages (March 1, 2017).

broadcast

Number

Number of push messages sent to all of this LINE Official Account's friends (broadcast messages).

targeting

Number

Number of push messages sent to some of this LINE Official Account's friends, based on specific attributes (targeted/segmented messages).

autoResponse

Number

Number of auto-response messages sent.

welcomeResponse

Number

Number of greeting messages sent.

chat

Number

Number of messages sent from LINE Official Account Manager Chat screen (opens new window).

apiBroadcast

Number

Number of broadcast messages sent with the Send broadcast message Messaging API operation.

apiPush

Number

Number of push messages sent with the Send push message Messaging API operation.

apiMulticast

Number

Number of multicast messages sent with the Send multicast message Messaging API operation.

apiNarrowcast

Number

Number of narrowcast messages sent with the Send narrowcast message Messaging API operation.

apiReply

Number

Number of replies sent with the Send reply message Messaging API operation.

Properties after broadcast contain the number of messages sent on the date specified in date. These extra properties are included only if status is ready.

Example response

# Get number of followers

Returns the number of users who have added the LINE Official Account on or before a specified date.

Example request

# HTTP request

GET https://api.line.me/v2/bot/insight/followers?date={date}

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

date

Required

Date for which to retrieve the number of followers.

Format: yyyyMMdd (Example: 20191231)
Timezone: UTC+9

# Response

Returns status code 200 and a JSON object with these properties:

status

String

Calculation status. One of:

ready: Calculation has finished. The numbers are up-to-date.
unready: We haven't finished calculating followers for the specified date. Please try again later. Calculation usually takes about a day.
out_of_service: The specified date is earlier than the date on which we first started calculating followers (November 1, 2016).

followers

Number

The number of times, as of the specified date, that a user added this LINE Official Account as a friend for the first time. The number doesn't decrease even if a user later blocks the account or when they delete their LINE account.

targetedReaches

Number

The number of users, as of the specified date, that the LINE Official Account can reach through targeted messages based on gender, age, and/or region. This number only includes users who are active on LINE or LINE services and whose demographics have a high level of certainty.

blocks

Number

The number of users blocking the account as of the specified date. The number decreases when a user unblocks the account.

Properties after followers are only returned if status is ready.

Example response

# Get friend demographics

Retrieves the demographic attributes for a LINE Official Account's friends. You can only retrieve information about friends for LINE Official Accounts created by users in Japan (JP), Thailand (TH), Taiwan (TW) and Indonesia (ID).

Not real-time data

It can take up to 3 days for demographic information to be calculated. This means the information the API returns may be 3 days old. Furthermore, your "Target reach" number must be at least 20 to retrieve demographic information.

Example request

# HTTP request

GET https://api.line.me/v2/bot/insight/demographic

# Request headers

Authorization

Bearer {channel access token}

# Response

Returns status code 200 and a JSON object with these properties:

available

Boolean

true if friend demographic information is available.

genders

Array

Percentage per gender

genders[].gender

String

Returns these values based on the users' gender:

male
female
unknown

genders[].percentage

Number

Percentage

ages

Array

Percentage per age group

ages[].age

String

Returns these values based on the users' age:

from0to14
from15to19
from20to24
from25to29
from30to34
from35to39
from40to44
from45to49
from50
unknown

ages[].percentage

Number

Percentage

areas

Array

Percentage per area

areas[].area

String

Returns these values based on the users' country and region:
JP

北海道 (Hokkaido)
青森 (Aomori)
岩手 (Iwate)
宮城 (Miyagi)
秋田 (Akita)
山形 (Yamagata)
福島 (Fukushima)
茨城 (Ibaraki)
栃木 (Tochigi)
群馬 (Gunma)
埼玉 (Saitama)
千葉 (Chiba)
東京 (Tokyo)
神奈川 (Kanagawa)
新潟 (Niigata)
富山 (Toyama)
石川 (Ishikawa)
福井 (Fukui)
山梨 (Yamanashi)
長野 (Nagano)
岐阜 (Gifu)
静岡 (Shizuoka)
愛知 (Aichi)
三重 (Mie)
滋賀 (Shiga)
京都 (Kyoto)
大阪 (Osaka)
兵庫 (Hyogo)
奈良 (Nara)
和歌山 (Wakayama)
鳥取 (Tottori)
島根 (Shimane)
岡山 (Okayama)
広島 (Hiroshima)
山口 (Yamaguchi)
徳島 (Tokushima)
香川 (Kagawa)
愛媛 (Ehime)
高知 (Kochi)
福岡 (Fukuoka)
佐賀 (Saga)
長崎 (Nagasaki)
熊本 (Kumamoto)
大分 (Oita)
宮崎 (Miyazaki)
鹿児島 (Kagoshima)
沖縄 (Okinawa)
unknown

台北市 (Taipei City)
新北市 (New Taipei City)
桃園市 (Taoyuan City)
台中市 (Taichung)
台南市 (Tainan City)
高雄市 (Kaohsiung)
基隆市 (Keelung)
新竹市 (Hsinchu City)
嘉義市 (Chiayi City)
新竹縣 (Hisnchu County)
苗栗縣 (Miaoli County)
彰化縣 (Changhua County)
南投縣 (Nantou County)
雲林縣 (Yunlin County)
嘉義縣 (Chiayi County)
屏東縣 (Pingtung County)
宜蘭縣 (Yilan County)
花蓮縣 (Hualien County)
台東縣 (Taitung County)
澎湖縣 (Penghu County)
金門縣 (Kinmen County)
連江縣 (Lianjiang County)
unknown

Bangkok
Pattaya
Northern
Central
Southern
Eastern
NorthEastern
Western
unknown

Bali
Bandung
Banjarmasin
Jabodetabek
Makassar
Medan
Palembang
Samarinda
Semarang
Surabaya
Yogyakarta
Lainnya
unknown

areas[].percentage

Number

Percentage

appTypes

Array

Percentage by OS

appTypes[].appType

String

Returns these values based on the users' OS:

ios
android
others

appTypes[].percentage

Number

Percentage

subscriptionPeriods

Array

Percentage per friendship duration

subscriptionPeriods[].subscriptionPeriod

String

Returns these values based on the friendship duration with the users:

within7days
within30days
within90days
within180days
within365days
over365days
unknown

subscriptionPeriods[].percentage

Number

Percentage

The elements of each array are included in the response only if the value of available is true.

Example response

# Get user interaction statistics

Note

Due to an issue with impression and open counts on some versions of the LINE app, we are limiting audience creation by the delivery dates of the messages.

Delivery date of the message (JST)	Limit to impression retargeting audience creation
Until March 20, 2020 23:59:59	Normal statistics will be returned.
Between March 30, 2020 00:00:00 and April 29, 2020 23:59:59	Reference values will be returned for `overview.uniqueImpression` and `messages[].impression`.
From April 30, 2020 00:00:00	Normal statistics will be returned. However, the statistics will not include the number of times the user with a LINE version subject to the limit opened the messages sent during this period.

Returns statistics about how users interact with narrowcast messages or broadcast messages sent from your LINE Official Account.

You can get statistics per message or per bubble.

message and bubbles

Understanding the numbers

Interactions are tracked for only 14 days after a message was sent. The statistics are no longer updated after 15 days.

Example request

# HTTP request

GET https://api.line.me/v2/bot/insight/message/event?requestId={requestId}

# Request headers

Authorization

Bearer {channel access token}

# Query parameters

requestId

Required

Request ID of a narrowcast message or broadcast message. Each Messaging API request has a request ID. Find it in the response headers.

# Response

Returns status code 200 and a JSON object with these properties:

Note

The statistical data may contain some errors.

To protect users' privacy, the values of some properties related to user interactions may be displayed as null or -1.

null: overview.uniqueImpression is 20 or lower.
-1: overview.uniqueImpression is 20 or higher, but the value of this property is 20 or lower.

overview

Object

Summary of message statistics.

overview.requestId

String

Request ID.

overview.timestamp

Number

UNIX timestamp for message delivery time.

overview.delivered

Number

Number of messages delivered. This property shows values of less than 20. However, if all messages have not been sent, it will be null.

overview.uniqueImpression

Number

Number of people who opened the message, meaning they displayed at least 1 bubble.

overview.uniqueClick

Number

Number of people who opened any URL in the message.

overview.uniqueMediaPlayed

Number

Number of people who started playing any video or audio in the message.

overview.uniqueMediaPlayed100Percent

Number

Number of people 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 people that started playing audio or video in the bubble.

messages[].uniqueMediaPlayed25Percent

Number

Number of people that played audio or video in the bubble from start to 25%.

messages[].uniqueMediaPlayed50Percent

Number

Number of people that played audio or video in the bubble from start to 50%.

messages[].uniqueMediaPlayed75Percent

Number

Number of people that played audio or video in the bubble from start to 75%.

messages[].uniqueMediaPlayed100Percent

Number

Number of people 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 was opened.

clicks[].uniqueClick

Number

Number of people that opened the URL.

clicks[].uniqueClickOfRequest

Number

Number of people who opened this url through any link in the message. If a message contains two links to the same URL and a user opens both links, they're counted only once.

Example response

# Users

You can get information of users who have added your LINE Official Account as a friend.

# Get profile

Get the profile information of users who have added your LINE Official Account as a friend.

Profile information of group members and chat room members

Use the following APIs to get profile information of group members or chat room members. With these APIs, you can get profile information of members who have not added your LINE Official Account as a friend or blocked your LINE Official Account.

Get Profile Information of Group Members
Get Profile Information of Chat Room Members

Example request

# HTTP request

Try

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

userId

User ID that is returned in a webhook event object. Do not use the LINE ID found on LINE.

# Response

When the specified user ID is valid, status code 200 and a JSON object with the following information will be returned.

displayName

String

User's display name

userId

String

User ID

language

String

User's language, as a BCP 47 (opens new window) language tag. Example: en for English. The language property is returned only in the following situations:

User has a LINE account created in Japan and has agreed to the Privacy Policy of LINE version 8.0.0 or later
User has a LINE account created in Taiwan, Thailand, or Indonesia and has agreed to the Privacy Policy of LINE version 8.9.0 or later

pictureUrl

String

Profile image URL. "https" image URL. Not included in the response if the user doesn't have a profile image.

statusMessage

String

User's status message. Not included in the response if the user doesn't have a status message.

Example response

# Get the user ID of all users who added your LINE Official Accout as a friend

Note

This feature is available only for verified or premium accounts. For more information about account types, see the Account Types of LINE Official Accout (opens new window) page on LINE for Business.

Gets the User ID of users who have added your LINE Official Account as a friend.

Example request

# HTTP request

GET https://api.line.me/v2/bot/followers/ids

# Request headers

Content-Type

application/json

Authorization

Bearer {channel access token}

# Query parameters

start

Optional

Value of the continuation token found in the next property of the JSON object returned in the response. Include this parameter to get the next array of user IDs.

# Response

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

userIds

Array of string

List of user IDs of users that have added the LINE Official Account as a friend. Only users of LINE for iOS and LINE for Android are included in userIds. For more information, see User consent.
Max: 300 user IDs

String

A continuation token to get the next array of user IDs. Returned only when there are remaining user IDs that were not returned in userIds in the original request. The number of user IDs in the userIds element does not have to reach 300 for the next property to be included in the response.

Example response

# Bot

You can obtain basic information on the LINE Official Account's bots.

# Group

You can obtain information on the LINE official account's groups and members of the groups.

# Get group summary

Gets the group ID, group name, and group icon URL of a group where the LINE Official Account is a member.

Example request

# HTTP request

GET https://api.line.me/v2/bot/group/{groupId}/summary

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

groupId

Required

Group ID. Found in the source object of webhook event objects.

# Response

Returns status code 200 and a JSON object with these properties.

groupId

String

Group ID

groupName

String

Group name

pictureUrl

String

Group icon URL

Example response

# Get number of users in a group

Gets the count of users in a group. You can get the user in group count even if the user hasn't added the LINE Official Account as a friend or has blocked the LINE Official Account.

The number returned excludes the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/group/{groupId}/members/count

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

groupId

Required

Group ID. Found in the source object of webhook event objects.

# Response

Returns status code 200 and a JSON object with these properties.

count

Number

The count of members in the group. The number returned excludes the LINE Official Account.

Example response

# Get group member user IDs

Note

This feature is available only for verified or premium accounts. For more information about account types, see the Account Types of LINE Official Accout (opens new window) page on LINE for Business.

Gets the user IDs of the members of a group that the bot is in. This includes user IDs of users who have not added the LINE Official Account as a friend or has blocked the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/group/{groupId}/members/ids

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

groupId

Required

Group ID. Found in the source object of webhook event objects.

# Query parameters

start

Optional

Value of the continuation token found in the next property of the JSON object returned in the response. Include this parameter to get the next array of user IDs for the members of the group.

# Response

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

memberIds

Array of strings

List of user IDs of members in the group. Only users of LINE for iOS and LINE for Android are included in memberIds. For more information, see User consent.
Max: 100 user IDs

String

A continuation token to get the next array of user IDs of the members in the group. Returned only when there are remaining user IDs that were not returned in memberIds in the original request.

Example response

# Get group member profile

Gets the user profile of a member of a group that the LINE Official Account is in if the user ID of the group member is known. You can get user profiles of users who haven't added the LINE Official Account as a friend or have blocked the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/group/{groupId}/member/{userId}

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

groupId

Group ID. Found in the source object of webhook event objects.

userId

User ID. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.

# Response

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

displayName

String

Display name

userId

String

User ID

pictureUrl

String

Profile image URL

Example response

# Leave group

Leaves a group.

Example request

# HTTP request

POST https://api.line.me/v2/bot/group/{groupId}/leave

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

groupId

Group ID. Found in the source object of webhook event objects.

# Response

Returns status code 200 and an empty JSON object.

Example response

# Chat Room

You can obtain information about the LINE official account's chat rooms and their members.

# Get number of users in a room

Gets the count of users in a room. You can get the user in room count even if the user hasn't added the LINE Official Account as a friend or has blocked the LINE Official Account.

The number returned excludes the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/room/{roomId}/members/count

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

roomId

Required

Room ID. Found in the source object of webhook event objects.

# Response

Returns status code 200 and a JSON object with these properties.

count

Number

The count of members in the room. The number returned excludes the LINE Official Account.

Example response

# Get room member user IDs

Note

This feature is available only for verified or premium accounts. For more information about account types, see the Account Types of LINE Official Accout (opens new window) page on LINE for Business.

Gets the user IDs of the members of a room that the LINE Official Account is in. This includes the user IDs of users who have not added the LINE Official Account as a friend or have blocked the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/room/{roomId}/members/ids

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

roomId

Required

Room ID. Found in the source object of webhook event objects.

# Query parameters

start

Optional

Value of the continuation token found in the next property of the JSON object returned in the response. Include this parameter to get the next array of user IDs for the members of the group.

# Response

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

memberIds

Array of strings

List of user IDs of the members in the room. Only users of LINE for iOS and LINE for Android are included in memberIds. For more information, see User consent.
Max: 100 user IDs

String

A continuation token to get the next array of user IDs of the members in the room. Returned only when there are remaining user IDs that were not returned in memberIds in the original request.

Example response

# Get room member profile

Gets the user profile of a member of a room that the LINE Official Account is in if the user ID of the room member is known. You can get user profiles of users who have not added the LINE Official Account as a friend or have blocked the LINE Official Account.

Example request

# HTTP request

GET https://api.line.me/v2/bot/room/{roomId}/member/{userId}

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

roomId

Room ID. Found in the source object of webhook event objects.

userId

User ID. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.

# Response

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

displayName

String

Display name

userId

String

User ID

pictureUrl

String

Profile image URL

Example response

# Leave room

Leaves a room.

Example request

# HTTP request

POST https://api.line.me/v2/bot/room/{roomId}/leave

# Request headers

Authorization

Bearer {channel access token}

# Path parameters

roomId

Room ID. Found in the source object of webhook event objects.

# Response

Returns status code 200 and an empty JSON object.

Example response

Customizable menu that is displayed on your LINE Official Account's chat screen. For more information, see Using rich menus.

Creates a rich menu.

You must upload a rich menu image, and set the rich menu as the default rich menu or link the rich menu to a user for the rich menu to be displayed. You can create up to 1000 rich menus for one LINE Official Account with the Messaging API.

Example request

POST https://api.line.me/v2/bot/richmenu

Authorization

Bearer {channel access token}

Content-Type

application/json

The rich menu represented as a rich menu object.

Returns status code 200 and a JSON object with the rich menu ID.

Example response

Uploads and attaches an image to a rich menu.

You can use rich menu images with the following specifications:

Image format: JPG, JPEG, or PNG
Image width size (pixels): 800 to 2500
Image height size (pixels): 250 or more
Image aspect ratio (width/height): 1.45 or more
Max file size: 10 MB

Note

You cannot replace an image attached to a rich menu. To update your rich menu image, create a new rich menu object and upload another image.

Example request

POST https://api-data.line.me/v2/bot/richmenu/{richMenuId}/content

Authorization

Bearer {channel access token}

Content-Type

image/jpeg or image/png

Content-Length

The length of the request body in octets (8-bit bytes). Must be a non-negative value.

richMenuId

Required

The ID of the rich menu to attach the image to

Returns status code 200 and an empty JSON object.

Example response

Downloads an image associated with a rich menu.

Example request

GET https://api-data.line.me/v2/bot/richmenu/{richMenuId}/content

Authorization

Bearer {channel access token}

richMenuId

Required

ID of the rich menu with the image to be downloaded

Returns status code 200 and the binary data of the rich menu image. The image can be downloaded as shown in the example request.

Gets a list of the rich menu response object of all rich menus created by Create a rich menu.

Note

You can't retrieve rich menus created with LINE Official Account Manager.

Example request

GET https://api.line.me/v2/bot/richmenu/list

Authorization

Bearer {channel access token}

Returns status code 200 and a list of rich menu response objects.

richmenus

Array

Array of rich menu response objects

Example response

Gets a rich menu via a rich menu ID.

Example request

GET https://api.line.me/v2/bot/richmenu/{richMenuId}

Authorization

Bearer {channel access token}

richMenuId

Required

ID of a rich menu

Returns status code 200 and a rich menu response object.

Example response

Deletes a rich menu.

Rich menu limits

If you have reached the maximum of 1,000 rich menus with the Messaging API for your LINE Official Account, you must delete a rich menu before you can create a new one.

Example request

DELETE https://api.line.me/v2/bot/richmenu/{richMenuId}

Authorization

Bearer {channel access token}

richMenuId

Required

ID of a rich menu

Returns status code 200 and an empty JSON object.

Example response

Sets the default rich menu. The default rich menu is displayed to all users who have added your LINE Official Account as a friend and are not linked to any per-user rich menu. If a default rich menu has already been set, calling this endpoint replaces the current default rich menu with the one specified in your request.

The rich menu is displayed in the following order of priority (highest to lowest):

The per-user rich menu set with the Messaging API
The default rich menu set with the Messaging API
The default rich menu set with LINE Official Account Manager

Example request

POST https://api.line.me/v2/bot/user/all/richmenu/{richMenuId}

Authorization

Bearer {channel access token}

richMenuId

Required

ID of a rich menu

Returns status code 200 and an empty JSON object.

Example response

Gets the ID of the default rich menu set with the Messaging API.

Example request

GET https://api.line.me/v2/bot/user/all/richmenu

Authorization

Bearer {channel access token}

Returns status code 200 and a JSON object with the rich menu ID.

Example response

Cancels the default rich menu set with the Messaging API.

Example request

DELETE https://api.line.me/v2/bot/user/all/richmenu

Authorization

Bearer {channel access token}

Returns status code 200 and an empty JSON object.

Example response

Links a rich menu to a user. Only one rich menu can be linked to a user at one time. If a user already has a rich menu linked, calling this endpoint replaces the existing rich menu with the one specified in your request.

The rich menu is displayed in the following order of priority (highest to lowest):

The per-user rich menu set with the Messaging API
The default rich menu set with the Messaging API
The default rich menu set with LINE Official Account Manager

Example request

POST https://api.line.me/v2/bot/user/{userId}/richmenu/{richMenuId}

Authorization

Bearer {channel access token}

richMenuId

Required

ID of a rich menu

userId

Required

User ID. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.

Returns status code 200 and an empty JSON object.

Example response

Links a rich menu to multiple users.

The rich menu is displayed in the following order of priority (highest to lowest):

The per-user rich menu set with the Messaging API
The default rich menu set with the Messaging API
The default rich menu set with LINE Official Account Manager

Example request

POST https://api.line.me/v2/bot/richmenu/bulk/link

Content-Type

application/json

Authorization

Bearer {channel access token}

richMenuId

String

Required

ID of a rich menu

userIds

Array of strings

Required

Array of user IDs. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.
Max: 500 user IDs

Returns status code 202 and an empty JSON object.

Unlike linking a rich menu to a user, this request is processed asynchronously in the background. Normally, the process is completed within a few seconds.

To verify whether the request was processed successfully, get the rich menu ID linked to the users and check if the rich menu is actually linked to the users.

Example response

Gets the ID of the rich menu linked to a user.

Example request

GET https://api.line.me/v2/bot/user/{userId}/richmenu

Authorization

Bearer {channel access token}

userId

Required

User ID. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.

Returns status code 200 and a JSON object with the rich menu ID.

Example response

Unlinks a rich menu from a user.

Example request

DELETE https://api.line.me/v2/bot/user/{userId}/richmenu

Authorization

Bearer {channel access token}

userId

Required

User ID. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.

Returns status code 200 and an empty JSON object.

Example response

Unlinks rich menus from multiple users.

Example request

POST https://api.line.me/v2/bot/richmenu/bulk/unlink

Content-Type

application/json

Authorization

Bearer {channel access token}

userIds

Array of strings

Required

Array of user IDs. Found in the source object of webhook event objects. Do not use the LINE ID used in LINE.
Max: 500 user IDs

Returns status code 202 and an empty JSON object.

Unlike unlinking a rich menu from a user, this request is processed asynchronously in the background. Normally, the process is completed within a few seconds.

To verify whether the request was processed successfully, get the rich menu ID linked to the users and check if the unlinked rich menus are actually not linked to the users.

Example response

# Account link

You can link the service account provided by the provider (corporate and developer) with the account of the LINE user.

# Message objects

JSON object which contains the contents of the message you send.

# Common properties for messages

The following properties can be specified in all the message objects.

# Quick reply

These properties are used for the quick reply feature. Supported on 8.11.0 or later for both LINE for iOS and LINE for Android. For more information, see Using quick replies.

quickReply

Object

Optional

items object

If the user receives multiple message objects, the quickReply property of the last message object is displayed.

# items object

This is a container that contains quick reply buttons.

items

Array of objects

Required

Quick reply button objects. Max: 13 objects

Example items object

# Quick reply button object

This is a quick reply option that is displayed as a button.

type

String

Required

action

imageUrl

String

Optional

URL of the icon that is displayed at the beginning of the button

Max character limit: 1000
URL scheme: https
Image format: PNG
Aspect ratio: 1:1
Data size: Up to 1 MB

There is no limit on the image size.
If the action property has a camera action, camera roll action, or location action, and the imageUrl property is not set, the default icon is displayed.

action

Object

Required

Action performed when this button is tapped. Specify an action object. The following is a list of the available actions:

Postback action
Message action
Datetime picker action
Camera action
Camera roll action
Location action

If a version of LINE that doesn't support the quick reply feature receives a message that contains quick reply buttons, only the message is displayed.

# Change icon and display name

When sending a message from the LINE Official Account, you can specify the sender.name and the sender.iconUrl properties in Message objects.

sender.name

String

Optional

Display name. Certain words such as LINE may not be used.
Max character limit: 20

sender.iconUrl

String

Optional

URL of the image to display as an icon when sending a message

Max character limit: 1000
URL scheme: https

Text message example of changed icon and display name

# Text message

Number of characters and index position of emojis

The number of characters and index position of emojis in text set to the property must be the number and position of the code unit when encoded in UTF-16. For some characters, such as those that use surrogate pairs and emojis that can be expressed in UTF-16, count them as multiple characters instead of one.

type

String

Required

text

text

String

Required

Message text. You can include the following emoji:

Unicode emoji
LINE emoji (Use a $ character as a placeholder and specify details in the emojis property)
(Deprecated) LINE original emoji (Unicode code point table for LINE original emoji)

Max character limit: 5000

emojis

Array of LINE emoji objects

One or more LINE emoji.
Max: 20 LINE emoji

emojis.index

Number

The index position for $ indicating the placeholder for LINE emojis in text, with the first character being at position 0. See the text message example for details.

Note

If you specify a position that doesn't match the position of $, the API returns HTTP 400 Bad request.

emojis.productId

String

Product ID for a set of LINE emoji. See Sendable LINE emoji list (opens new window).

emojis.emojiId

String

ID for a LINE emoji inside a set. See Sendable LINE emoji list (opens new window).

Text message example

# Sticker message

type

String

Required

sticker

packageId

String

Required

Package ID for a set of stickers. For information on package IDs, see the Sticker list.

stickerId

String

Required

Sticker ID. For a list of sticker IDs for stickers that can be sent with the Messaging API, see the Sticker list.

Sticker message example

# Image message

type

String

Required

image

originalContentUrl

String

Required

Image URL (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Max image size: No limits
Max file size: 10 MB

previewImageUrl

String

Required

Preview image URL (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Max image size: No limits
Max file size: 10 MB

Image message example

# Video message

type

String

Required

video

originalContentUrl

String

Required

URL of video file (Max character limit: 1000)
HTTPS over TLS 1.2 or later
mp4
Max file size: 200 MB

Note

A very wide or tall video may be cropped when played in some environments.

previewImageUrl

String

Required

URL of preview image (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Max file size: 10 MB

trackingId

String

Optional

ID used to identify the video when Video viewing complete event occurs. If you send a video message with trackingId added, the video viewing complete event occurs when the user finishes watching the video.

You can use the same ID in multiple messages.

Max character limit: 100
Supported character types: Half-width alphanumeric characters (a-z, A-Z, 0-9) and symbols (-.=,+*()%$&;:@{}!?<>[])

Note: You can't use the trackingId property in messages addressed to groups or talk rooms, or in audience match.

Video message example

# Audio message

type

String

Required

audio

originalContentUrl

String

Required

URL of audio file (Max character limit: 1000)
HTTPS over TLS 1.2 or later
m4a
Max file size: 200 MB

Note

Only M4A files are supported on the Messaging API. If a service only supports MP3 files, you can use a service like FFmpeg to convert the files to M4A.

duration

Number

Required

Length of audio file (milliseconds)

Audio message example

# Location message

type

String

Required

location

title

String

Required

Title
Max character limit: 100

address

String

Required

Address
Max character limit: 100

latitude

Decimal

Required

Latitude

longitude

Decimal

Required

Longitude

Location message example

# Imagemap message

Imagemap messages are messages configured with an image that has multiple tappable areas. You can assign one tappable area for the entire image or different tappable areas on divided areas of the image.

You can also play a video on the image and display a label with a hyperlink after the video is finished.

Video isn't working properly

If the video isn't playing properly, make sure the video is a supported file type and the HTTP server hosting the video supports HTTP partial requests (range request).

type

String

Required

imagemap

baseUrl

String

Required

Base URL of the image
Max character limit: 1000
HTTPS over TLS 1.2 or later
For more information about supported images in imagemap messages, see How to configure an image.

altText

String

Required

Alternative text
Max character limit: 400

baseSize.width

Number

Required

Width of base image in pixels. Set to 1040.

baseSize.height

Number

Required

Height of base image. Set to the height that corresponds to a width of 1040 pixels.

video.originalContentUrl

String

URL of the video file (Max character limit: 1000)
HTTPS over TLS 1.2 or later
mp4
Max length: No limit Max file size: 200 MB

Note

A very wide or tall video may be cropped when played in some environments.

video.previewImageUrl

String

URL of the preview image (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Max image size: No limits
Max file size: 10 MB

video.area.x

Number

Horizontal position of the video area relative to the left edge of the imagemap area. Value must be 0 or higher.

video.area.y

Number

Vertical position of the video area relative to the top of the imagemap area. Value must be 0 or higher.

video.area.width

Number

Width of the video area

video.area.height

Number

Height of the video area

video.externalLink.linkUri

String

Webpage URL. Called when the label displayed after the video is tapped.
Max character limit: 1000
The available schemes are http, https, line, and tel. For more information about the LINE URL scheme, see Using LINE features with the LINE URL scheme.

video.externalLink.label

String

Label. Displayed after the video is finished.
Max character limit: 30

actions

Array of imagemap action objects

Required

Action when tapped
Max: 50

*1 This property is required if you set a video to play on the imagemap.
*2 This property is required if you set a video to play and a label to display after the video on the imagemap.

Imagemap message example with two tappable areas

# How to configure an image

Images used in imagemap messages must meet the following requirements.

Image format: JPG, JPEG, or PNG
Image width: 240px, 300px, 460px, 700px, 1040px
Max file size: 10 MB

Using transparent PNG

It is possible to use transparent PNG in your imagemap messages.

Make it possible to access images of 5 different sizes using the baseUrl/{image width} URL format. LINE will then download an image at the appropriate resolution based on the device.

For example, if we had a base URL of https://example.com/images/cats, the URL for the image with a width of 700px would be https://example.com/images/cats/700. To confirm all images display properly, access the image URLs.

Image width	Example URL
240px	https://example.com/bot/images/rm001/240
300px	https://example.com/bot/images/rm001/300
460px	https://example.com/bot/images/rm001/460
700px	https://example.com/bot/images/rm001/700
1040px	https://example.com/bot/images/rm001/1040

Exclude image extension from URL

Don't include the extension in the image filename. The image will not display in the imagemap message if the URL contains the image file extension (e.g. https://example.com/bot/images/rm001/700.png).

# Imagemap action objects

Object which specifies the actions and tappable areas of an imagemap.

When an area is tapped, the user is redirected to the URI specified in uri and the message specified in message is sent.

# Imagemap URI action object

type

String

Required

uri

label

String

Optional

Label for the action. Spoken when the accessibility feature is enabled on the client device.
Max character limit: 50
Supported on LINE 8.2.0 or later for iOS.

linkUri

String

Required

Webpage URL
Max character limit: 1000
The available schemes are http, https, line, and tel. For more information about the LINE URL scheme, see Using LINE features with the LINE URL scheme.

area

Imagemap area object

Required

Defined tappable area

Example imagemap URI action object

# Imagemap message action object

type

String

Required

message

label

String

Optional

Label for the action. Spoken when the accessibility feature is enabled on the client device.
Max character limit: 50
Supported on 8.2.0 or later for LINE for iOS.

text

String

Required

Message to send
Max character limit: 400
Supported on LINE for iOS and Android only.

area

Imagemap area object

Required

Defined tappable area

Example imagemap message action object

# Imagemap area object

Defines the size of a tappable area. The top left is used as the origin of the area. Set these properties based on the baseSize.width property and the baseSize.height property.

Number

Required

Horizontal position relative to the left edge of the area. Value must be 0 or higher.

Number

Required

Vertical position relative to the top of the area. Value must be 0 or higher.

width

Number

Required

Width of the tappable area

height

Number

Required

Height of the tappable area

Example imagemap area object

# Template messages

Template messages are messages with predefined layouts which you can customize. For more information, see Template messages.

The following template types are available:

Buttons
Confirm
Carousel
Image carousel

Note

Template messages are only available on LINE for iOS and LINE for Android.

# Common properties of template message objects

The following properties are common to all template message objects.

type

String

Required

template

altText

String

Required

Alternative text. Displayed on devices that do not support template messages.
Max character limit: 400

template

Object

Required

A Buttons, Confirm, Carousel, or Image Carousel object.

# Buttons template

Template with an image, title, text, and multiple action buttons.

type

String

Required

buttons

thumbnailImageUrl

String

Optional

Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Max width: 1024px
Max file size: 10 MB

imageAspectRatio

String

Optional

Aspect ratio of the image. One of:

rectangle: 1.51:1
square: 1:1

Default: rectangle

imageSize

String

Optional

Size of the image. One of:

cover: The image fills the entire image area. Parts of the image that do not fit in the area are not displayed.
contain: The entire image is displayed in the image area. A background is displayed in the unused areas to the left and right of vertical images and in the areas above and below horizontal images.

Default: cover

imageBackgroundColor

String

Optional

Background color of the image. Specify a RGB color value. Default: #FFFFFF (white)

title

String

Optional

Title
Max character limit: 40

text

String

Required

Message text
Max character limit: 160 (no image or title)
Max character limit: 60 (message with an image or title)

defaultAction

Action object

Optional

Action when image, title or text area is tapped.

actions

Array of action objects

Required

Action when tapped
Max objects: 4

Warning

Because of the height limitation for buttons template messages, the lower part of the text display area will get cut off if the height limitation is exceeded. For this reason, depending on the character width, the message text may not be fully displayed even when it is within the character limits.

Buttons template message example

# Confirm template

Template with two action buttons.

type

String

Required

confirm

text

String

Required

Message text
Max character limit: 240

actions

Array of action objects

Required

Action when tapped
Set 2 actions for the 2 buttons

Warning

Because of the height limitation for confirm template messages, the lower part of the text display area will get cut off if the height limitation is exceeded. For this reason, depending on the character width, the message text may not be fully displayed even when it is within the character limits.

Confirm template message example

# Carousel template

Template with multiple columns which can be cycled like a carousel. The columns are shown in order when scrolling horizontally.

type

String

Required

carousel

columns

Array of column objects

Required

Array of columns
Max columns: 10

imageAspectRatio

String

Optional

Aspect ratio of the image. One of:

rectangle: 1.51:1
square: 1:1

Applies to all columns. Default: rectangle

imageSize

String

Optional

Size of the image. One of:

cover: The image fills the entire image area. Parts of the image that do not fit in the area are not displayed.
contain: The entire image is displayed in the image area. A background is displayed in the unused areas to the left and right of vertical images and in the areas above and below horizontal images.

Applies to all columns. Default: cover.

Carousel template message example

# Column object for carousel

thumbnailImageUrl

String

Optional

Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Aspect ratio: 1:1.51
Max width: 1024px
Max file size: 10 MB

imageBackgroundColor

String

Optional

Background color of the image. Specify a RGB color value. The default value is #FFFFFF (white).

title

String

Optional

Title
Max character limit: 40

text

String

Required

Message text
Max character limit: 120 (no image or title)
Max character limit: 60 (message with an image or title)

defaultAction

Action object

Optional

Action when image, title or text area is tapped.

actions

Array of action objects

Required

Action when tapped
Max objects: 3

Warning

Because of the height limitation for carousel template messages, the lower part of the text display area will get cut off if the height limitation is exceeded. For this reason, depending on the character width, the message text may not be fully displayed even when it is within the character limits.

Note

Keep the number of actions consistent for all columns. If you use an image or title for a column, make sure to do the same for all other columns.

# Image carousel template

Template with multiple images which can be cycled like a carousel. The images are shown in order when scrolling horizontally.

type

String

Required

image_carousel

columns

Array of column objects

Required

Array of columns
Max columns: 10

Image carousel template message example

# Column object for image carousel

imageUrl

String

Required

Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPG, JPEG, or PNG
Aspect ratio: 1:1
Max width: 1024px
Max file size: 10 MB

action

Action object

Required

Action when image is tapped

# Flex Message

Flex Messages are messages with a customizable layout. You can customize the layout freely based on the specification for CSS Flexible Box (CSS Flexbox) (opens new window). For more information, see Sending Flex Messages in the Messaging API documentation.

Container
- Bubble
- Carousel
Component
- Box
- Button
- Image
- Icon
- Text
- Span
- Separator
- Filler

type

String

Required

flex

altText

String

Required

Alternative text
Max character limit: 400

contents

Object

Required

Flex Message container

Flex Message example

# Operating environment

Flex Messages are supported on the following versions of LINE:

LINE for iOS: All versions
LINE for Android: All versions
LINE for macOS: 5.17.0 or later
LINE for Windows: 5.17.0 or later

These properties are only supported on specific versions on both LINE for iOS and LINE for Android.

Property	Supported version
`adjustMode` property of the text and button	10.13.0 or later
`maxLines` property of the text	8.11.0 or later
`action` property of the box	8.11.0 or later

# Container

A container is the top-level structure of a Flex Message. Here are the types of containers available:

Bubble
Carousel

For JSON samples and usage of containers, see Flex Message elements in the API documentation.

# Bubble

This is a container that contains one message bubble. It can contain four blocks: header, hero, body, and footer. For more information about using each block, see Block in the API documentation.

The maximum size of JSON data that defines a bubble is 30 KB.

type

String

Required

bubble

size

String

Optional

The size of the bubble. You can specify one of the following values: nano, micro, kilo, mega, or giga. The default value is mega.

direction

String

Optional

Text directionality and the direction of placement of components in horizontal boxes. Specify one of the following values:

ltr: The text is left-to-right horizontal writing, and the components are placed from left to right
rtl: The text is right-to-left horizontal writing, and the components are placed from right to left

The default value is ltr.

header

Object

Optional

Header block. Specify a Box.

hero

Object

Optional

Hero block. Specify a box or an image.

body

Object

Optional

Body block. Specify a Box.

footer

Object

Optional

Footer block. Specify a Box.

styles

Object

Optional

Style of each block. Specify a bubble style.

action

Object

Optional

Action performed when this image is tapped. Specify an action object. This property is supported on the following versions of LINE.

LINE for iOS and Android: 8.11.0 or later

Bubble example

# Objects for the block style

Use the following two objects to define the style of blocks in a bubble.

Example of a bubble style and block style

# Bubble style

header

Object

Optional

Header block. Specify a block style.

hero

Object

Optional

Hero block. Specify a block style.

body

Object

Optional

Body block. Specify a block style.

footer

Object

Optional

Footer block. Specify a block style.

# Block style

backgroundColor

String

Optional

Background color of the block. Use a hexadecimal color code.

separator

Boolean

Optional

true to place a separator above the block. The default value is false.

separatorColor

String

Optional

Color of the separator. Use a hexadecimal color code.

Note

You cannot place a separator above the first block.

# Carousel

A carousel is a container that contains multiple bubbles as child elements. Users can scroll horizontally through the bubbles.

The maximum size of JSON data that defines a carousel is 50 KB.

type

String

Required

carousel

contents

Array of objects

Required

Bubbles within a carousel. Max: 12 bubbles

Bubble width

A carousel can't contain bubbles of different widths (size property). Each bubble in a carousel should have the same width.

Bubble height

The body of each bubble will stretch to match the tallest bubble in the carousel. However, bubbles with no body will not change height.

Carousel example

# Component

Components are elements that make up a block. Here are the types of components available:

Box
Button
Image
Icon
Text
Span
Separator
Filler

For JSON samples and usage of each component, see Flex Message elements and Flex Message layout in the Messaging API documentation.

# Box

This is a component that defines the layout of child components. You can also include a box in a box.

type

String

Required

box

layout

String

Required

The layout style of components in this box. For more information, see Direction of placing components in the API documentation.

contents

Array of objects

Required

Components in this box. Here are the types of components available:

When the layout property is horizontal or vertical: box, button, image, text, separator, and filler
When the layout property is baseline: icon, text, and filler

Components are rendered in the same order specified in the array. You may also specify an empty array.

backgroundColor

String

Optional

Background color of the block. In addition to the RGB color, an alpha channel (transparency) can also be set. Use a hexadecimal color code. (Example:#RRGGBBAA) The default value is #00000000.

borderColor

String

Optional

Color of box border. Use a hexadecimal color code.

borderWidth

String

Optional

Width of box border. You can specify a value in pixels or any one of none, light, normal, medium, semi-bold, or bold. A value of none means that borders are not rendered; the other values are listed in order of increasing width.

cornerRadius

String

Optional

Radius at the time of rounding the corners of the border. You can specify a value in pixels or any one of none, xs, sm, md, lg, xl, or xxl. none doesn't round the corner while the others increase in radius in the order of listing. The default value is none.

width

String

Optional

Box width. For more information, see Box width in the Messaging API documentation.

height

String

Optional

Box height. For more information, see Box height in the Messaging API documentation.

flex

Number

Optional

The ratio of the width or height of this component within the parent box. For more information, see Width and height of components in the Messaging API documentation.

spacing

String

Optional

Minimum space between components in this box. The default value is none. For more information, see spacing property of the box in the Messaging API documentation.

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property of the component in the Messaging API documentation.

paddingAll

String

Optional

Free space between the borders of this box and the child element. For more information, see Box padding in the Messaging API documentation.

paddingTop

String

Optional

Free space between the border at the upper end of this box and the upper end of the child element. For more information, see Box padding in the Messaging API documentation.

paddingBottom

String

Optional

Free space between the border at the lower end of this box and the lower end of the child element. For more information, see Box padding in the Messaging API documentation.

paddingStart

String

Optional

Free space between the border at the left end of this box and the left end of the child element. For more information, see Box padding in the Messaging API documentation.

paddingEnd

String

Optional

Free space between the border at the right end of this box and the right end of the child element. For more information, see Box padding in the Messaging API documentation.

position

String

Optional

Reference position for placing this box. Specify one of the following values:

relative: Use the previous box as reference.
absolute: Use the top left of parent element as reference.

The default value is relative. For more information, see Offset in the Messaging API documentation.

offsetTop

String

Optional

The top offset. For more information, see Offset in the Messaging API documentation.

offsetBottom

String

Optional

The bottom offset. For more information, see Offset in the Messaging API documentation.

offsetStart

String

Optional

The left offset. For more information, see Offset in the Messaging API documentation.

offsetEnd

String

Optional

The right offset. For more information, see Offset in the Messaging API documentation.

action

Object

Optional

Action performed when this image is tapped. Specify an action object. This property is supported on the following versions of LINE.

LINE 8.11.0 or later for iOS and Android

justifyContent

String

Optional

How child elements are aligned along the main axis of the parent element. If the parent element is a horizontal box, this only takes effect when its child elements have their flex property set equal to 0. For more information, see Arranging a box's child elements and free space in the Messaging API documentation.

alignItems

String

Optional

How child elements are aligned along the cross axis of the parent element. For more information, see Arranging a box's child elements and free space in the Messaging API documentation.

background.type

String

Optional

The type of background used. Specify these values:

linearGradient: Linear gradient. For more information, see Linear gradient backgrounds in the Messaging API documentation.

background.angle

String

Optional

The angle at which a linear gradient moves. Specify the angle using an integer value like 90deg (90 degrees) or a decimal number like 23.5deg (23.5 degrees) in the half-open interval [0, 360). The direction of the linear gradient rotates clockwise as the angle increases. Given a value of 0deg, the gradient starts at the bottom and ends at the top; given a value of 45deg, the gradient starts at the bottom-left corner and ends at the top-right corner; given a value of 90deg, the gradient starts at the left and ends at the right; and given a value of 180deg, the gradient starts at the top and ends at the bottom. For more information, see Direction (angle) of linear gradient backgrounds in the Messaging API documentation.

This is required when background.type is linearGradient.

background.startColor

String

Optional

The color at the gradient's starting point. Use a hexadecimal color code in the #RRGGBB or #RRGGBBAA format.

This is required when background.type is linearGradient.

background.endColor

String

Optional

The color at the gradient's ending point. Use a hexadecimal color code in the #RRGGBB or #RRGGBBAA format.

This is required when background.type is linearGradient.

background.centerColor

String

Optional

The color in the middle of the gradient. Use a hexadecimal color code in the #RRGGBB or #RRGGBBAA format. Specify a value for the background.centerColor property to create a gradient that has three colors. For more information, see Intermediate color stops for linear gradients in the Messaging API documentation.

background.centerPosition

String

Optional

The position of the intermediate color stop. Specify an integer or decimal value between 0% (the starting point) and 100% (the ending point). This is 50% by default. For more information, see Intermediate color stops for linear gradients in the Messaging API documentation.

Box example

# Button

This component renders a button. When the user taps a button, a specified action is performed.

type

String

Required

button

action

Object

Required

Action performed when this button is tapped. Specify an action object.

flex

Number

Optional

The ratio to use for the width or height of this component within the parent element. By default, a horizontal box's components have their flex property set equal to 1. By default, a vertical box's components have their flex property set equal to 0. For more information, see Width and height of components in the Messaging API documentation.

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property for components in the Messaging API documentation.

position

String

Optional

Reference for offsetTop, offsetBottom, offsetStart, and offsetEnd. Specify one of the following values:

relative: Use the previous box as reference.
absolute: Use the top left of parent element as reference.

The default value is relative. For more information, see Offset in the API documentation.

offsetTop

String

Optional

The top offset. For more information, see Offset in the Messaging API documentation.

offsetBottom

String

Optional

The bottom offset. For more information, see Offset in the Messaging API documentation.

offsetStart

String

Optional

The left offset. For more information, see Offset in the Messaging API documentation.

offsetEnd

String

Optional

The right offset. For more information, see Offset in the Messaging API documentation.

height

String

Optional

Height of the button. You can specify sm or md. The default value is md.

style

String

Optional

Style of the button. Specify one of the following values:

primary: Style for dark color buttons
secondary: Style for light color buttons
link: HTML link style

The default value is link.

color

String

Optional

Character color when the style property is link. Background color when the style property is primary or secondary. Use a hexadecimal color code.

gravity

String

Optional

Alignment style in vertical direction. For more information, see Vertical alignment in the Messaging API documentation.

adjustMode

String

Optional

The method by which to adjust the text font size. Specify this value:

shrink-to-fit: Automatically shrink the font size to fit the width of the component. This property takes a "best-effort" approach that may work differently—or not at all!—on some platforms. For more information, see Automatically shrink fonts to fit in the Messaging API documentation.
LINE 10.13.0 or later for iOS and Android

Button example

# Image

This component renders an image.

type

String

Required

image

url

String

Required

Image URL
Protocol: HTTPS (TLS 1.2 or later)
Image format: JPG, JPEG, or PNG
Maximum image size: 1024×1024 pixels
Maximum data size: 10 MB (300 KB when the animated property is true)

flex

Number

Optional

The ratio of the width or height of this component within the parent box. For more information, see Width and height of components in the Messaging API documentation.

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property of the component in the Messaging API documentation.

position

String

Optional

Reference for offsetTop, offsetBottom, offsetStart, and offsetEnd. Specify one of the following values:

relative: Use the previous box as reference.
absolute: Use the top left of parent element as reference. The default value is relative. For more information, see Offset in the Messaging API documentation.

offsetTop

String

Optional

The top offset. For more information, see Offset in the Messaging API documentation.

offsetBottom

String

Optional

The bottom offset. For more information, see Offset in the Messaging API documentation.

offsetStart

String

Optional

The left offset. For more information, see Offset in the Messaging API documentation.

offsetEnd

String

Optional

The right offset. For more information, see Offset in the Messaging API documentation.

align

String

Optional

Alignment style in horizontal direction. For more information, see Alignment in horizontal direction in the Messaging API documentation.

gravity

String

Optional

Alignment style in vertical direction. For more information, see Alignment in vertical direction in the Messaging API documentation.

size

String

Optional

The maximum image width. This is md by default. For more information, see Image size in the Messaging API documentation.

aspectRatio

String

Optional

Aspect ratio of the image. {width}:{height} format. Specify the value of {width} and {height} in the range from 1 to 100000. However, you cannot set {height} to a value that is more than three times the value of {width}. The default value is 1:1.

aspectMode

String

Optional

The display style of the image if the aspect ratio of the image and that specified by the aspectRatio property do not match. For more information, see About the drawing area.

backgroundColor

String

Optional

Background color of the image. Use a hexadecimal color code.

action

Object

Optional

Action performed when this image is tapped. Specify an action object.

animated

Boolean

Optional

When this is true, an animated image (APNG) plays. You can specify a value of true up to three times in a single message. You can't send messages that exceed this limit. This is false by default. Animated images larger than 300 KB aren't played back.

This property has been temporarily disabled

The animated property has been temporarily disabled due to a technical issue. For more information, see the news article below.

Flex Message Update 2 released

How to create animated images

Create animated images using an APNG editor. Refer to information related to creating animated stamps as you create your APNG files. For more information, see the Creation Guidelines (opens new window) for Animated Stickers in the LINE Creators Market.

What if my animated image doesn't play?

If your image appears but no animation plays, check the following:

Flex Message Update 2 has been released（Flex message's play animated images feature has been temporarily disabled due to a technical issue）
Have you set the value of the animated property equal to true?
Are you using less than 300 KB of data?
Are you attempting to play the animation on a version of LINE that supports the animated property?

The animation repeats for the number of times specified by the num_plays field in the acTL chunk of an APNG. You can also specify a value of 0 to repeat the animation indefinitely.

Image example

# About the drawing area

Specify the max width of the image with the size property and the aspect ratio (horizontal-to-vertical ratio) of the image with the aspectRatio property. The rectangular area determined by the size and aspectRatio properties is called the drawing area. The image is rendered in this drawing area.

If the image width specified by the flex property is larger than that calculated from the size property, the width of the drawing area is scaled down to the width of the component.
If the aspect ratio of the image and that specified by the aspectRatio property do not match, the image is displayed according to the aspectMode property. The default value is fit.
- If the value of aspectMode is cover: The image fills the entire drawing area. Parts of the image that do not fit in the drawing area are not displayed.
- If the value of aspectMode is fit: The entire image is displayed in the drawing area. A background is displayed in the unused areas to the left and right of vertical images and in the areas above and below horizontal images.

# Icon

This component renders an icon for decorating the adjacent text.

This component can be used only in a baseline box.

type

String

Required

icon

url

String

Required

Image URL
Protocol: HTTPS (TLS 1.2 or later)
Image format: JPG, JPEG, or PNG
Maximum image size: 1024×1024 pixels
Maximum data size: 10 MB

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property of the component in the Messaging API documentation.

position

String

Optional

Reference for offsetTop, offsetBottom, offsetStart, and offsetEnd. Specify one of the following values:

relative: Use the previous box as reference.
absolute: Use the top left of parent element as reference. The default value is relative. For more information, see Offset in the Messaging API documentation.

offsetTop

String

Optional

The top offset. For more information, see Offset in the Messaging API documentation.

offsetBottom

String

Optional

The bottom offset. For more information, see Offset in the Messaging API documentation.

offsetStart

String

Optional

The left offset. For more information, see Offset in the Messaging API documentation.

offsetEnd

String

Optional

The right offset. For more information, see Offset in the Messaging API documentation.

size

String

Optional

Maximum size of the icon width. This is md by default. For more information, see Icon, text, and span size in the Messaging API documentation.

aspectRatio

String

Optional

Aspect ratio of the icon. {width}:{height} format. The values of {width} and {height} must be in the range 1–100000. {height} can't be more than three times the value of {width}. The default value is 1:1.

The icon's flex property is fixed to 0.

Icon example

# Text

This component renders a text string in one row. You can specify font color, size, and weight.

type

String

Required

text

text

String

Optional

Text. Be sure to set either one of the text property or contents property. If you set the contents property, text is ignored.

contents

Array of objects

Optional

Array of spans. Be sure to set either one of the text property or contents property. If you set the contents property, text is ignored.

adjustMode

String

Optional

The method by which to adjust the text's font size. Specify this value:

shrink-to-fit: Automatically shrink the font size to fit the width of the component. This property takes a "best-effort" approach that may work differently—or not at all!—on some platforms. For more information, see Automatically shrink fonts to fit in the Messaging API documentation.
LINE 10.13.0 or later for iOS and Android

flex

Number

Optional

The ratio of the width or height of this component within the parent box. For more information, see Width and height of components in the Messaging API documentation.

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property of the component in the Messaging API documentation.

position

String

Optional

Reference for offsetTop, offsetBottom, offsetStart, and offsetEnd. Specify one of the following values:

relative: Use the previous box as reference.
absolute: Use the top left of parent element as reference.

The default value is relative. For more information, see Offset in the Messaging API documentation.

offsetTop

String

Optional

The top offset. For more information, see Offset in the Messaging API documentation.

offsetBottom

String

Optional

The bottom offset. For more information, see Offset in the Messaging API documentation.

offsetStart

String

Optional

The left offset. For more information, see Offset in the Messaging API documentation.

offsetEnd

String

Optional

The right offset. For more information, see Offset in the Messaging API documentation.

size

String

Optional

Font size. This is md by default. For more information, see Icon, text, and span size in the Messaging API documentation.

align

String

Optional

Alignment style in horizontal direction. For more information, see Alignment in horizontal direction in the Messaging API documentation.

gravity

String

Optional

Alignment style in vertical direction. The default value is top. For more information, see Alignment in vertical direction in the Messaging API documentation.

wrap

Boolean

Optional

true to wrap text. The default value is false. If set to true, you can use a new line character (\n) to begin on a new line. For more information, see Wrapping text in the Messaging API documentation.

maxLines

Number

Optional

Max number of lines. If the text does not fit in the specified number of lines, an ellipsis (…) is displayed at the end of the last line. If set to 0, all the text is displayed. The default value is 0. This property is supported on the following versions of LINE.

LINE 8.11.0 or later for iOS and Android

weight

String

Optional

Font weight. You can specify one of the following values: regular or bold. Specifying bold makes the font bold. The default value is regular.

color

String

Optional

Font color. Use a hexadecimal color code.

action

Object

Optional

Action performed when this image is tapped. Specify an action object.

style

String

Optional

Style of the text. Specify one of these values:

normal: Normal
italic: Italic

The default value is normal.

decoration

String

Optional

Decoration of the text. Specify one of these values:

none: No decoration
underline: Underline
line-through: Strikethrough

The default value is none.

Text example

# Span

This component renders multiple text strings with different designs in one row. You can specify the color, size, weight, and decoration for the font. Span is set to contents property in Text.

type

String

Required

span

text

String

Optional

Text. If the wrap property of the parent text is set to true, you can use a new line character (\n) to begin on a new line.

color

String

Optional

Font color. Use a hexadecimal color code.

size

String

Optional

Font size. For more information, see Icon, text, and span size in the Messaging API documentation.

weight

String

Optional

Font weight. You can specify one of the following values: regular or bold. Specifying bold makes the font bold. The default value is regular.

style

String

Optional

Style of the text. Specify one of these values:

normal: Normal
italic: Italic

The default value is normal.

decoration

String

Optional

Decoration of the text. Specify one of these values:

none: No decoration
underline: Underline
line-through: Strikethrough

The default value is none.

Note

The decoration set in the decoration property of the text cannot be overwritten by the decoration property of the span.

Span example

# Separator

This component renders a separating line within a box. A vertical line will be rendered in a horizontal box and a horizontal line will be rendered in a vertical box.

type

String

Required

separator

margin

String

Optional

The minimum amount of space to include before this component in its parent container. For more information, see margin property of the component in the Messaging API documentation.

color

String

Optional

Color of the separator. Use a hexadecimal color code.

Separator example

# Filler

This component is used to create a space. You can put a space between, before, or after components by inserting a filler anywhere within a box.

type

String

Required

filler

flex

Number

Optional

The ratio of the width or height of this component within the parent box. For more information, see Width and height of components in the Messaging API documentation.

The spacing property of the parent element will be ignored for fillers.

Filler example

# Action objects

These are types of actions for your bot to take when a user taps a button or an image in a message.

# Postback action

When a control associated with this action is tapped, a postback event is returned via webhook with the specified string in the data property.

type

String

Required

postback

label

String

See description

Label for the action

Required for templates other than image carousel. Max character limit: 20
Optional for image carousel templates. Max character limit: 12
Optional for rich menus. Spoken when the accessibility feature is enabled on the client device. Max character limit: 20. Supported on LINE 8.2.0 or later for iOS.
Required for quick reply buttons. Max character limit: 20. Supported on LINE 8.11.0 or later for both LINE for iOS and LINE for Android.
Required for the button of Flex Message. This property can be specified for the box, image, and text but its value is not displayed. Max character limit: 20

data

String

Required

String returned via webhook in the postback.data property of the postback event
Max character limit: 300

displayText

String

See description

Text displayed in the chat as a message sent by the user when the action is performed. Required for quick reply buttons. Optional for the other message types.
Max character limit: 300
The displayText and text properties cannot both be used at the same time.

text

String

Optional

【Deprecated】 Text displayed in the chat as a message sent by the user when the action is performed. Returned from the server through a webhook. This property shouldn't be used with quick reply buttons.
Max character limit: 300
The displayText and text properties cannot both be used at the same time.

Example postback action object

# Message action

When a control associated with this action is tapped, the string in the text property is sent as a message from the user.

type

String

Required

message

label

String

See description

Label for the action

Required for templates other than image carousel. Max character limit: 20
Optional for image carousel templates. Max character limit: 12
Optional for rich menus. Spoken when the accessibility feature is enabled on the client device. Max character limit: 20. Supported on LINE 8.2.0 or later for iOS.
Required for quick reply buttons. Max character limit: 20. Supported on 8.11.0 or later for both LINE for iOS and LINE for Android.
Required for the button of Flex Message. This property can be specified for the box, image, and text but its value is not displayed. Max charater limit: 20

text

String

Required

Text sent when the action is performed
Max character limit: 300

Example message action object

# URI action

When a control associated with this action is tapped, the URI specified in the uri property is opened.

type

String

Required

uri

label

String

See description

Label for the action

Required for templates other than image carousel. Max character limit: 20
Optional for image carousel templates. Max character limit: 12
Optional for rich menus. Spoken when the accessibility feature is enabled on the client device. Max character limit: 20. Supported on LINE 8.2.0 or later for iOS.
Required for the button of Flex Message. This property can be specified for the box, image, and text but its value is not displayed. Max character limit: 20

uri

String

Required

URI opened when the action is performed (Max character limit: 1000)
The available schemes are http, https, line, and tel. For more information about the LINE URL scheme, see Using LINE features with the LINE URL scheme.

altUri.desktop

String

Optional

URI opened on LINE for macOS and Windows when the action is performed (Max character limit: 1000)
If the altUri.desktop property is set, the uri property is ignored on LINE for macOS and Windows.
The available schemes are http, https, line, and tel. For more information about the LINE URL scheme, see Using LINE features with the LINE URL scheme. This property is supported on the following version of LINE.

5.12.0 or later for both LINE for macOS and LINE for Windows

Note

The altUri.desktop property is supported only when you set URI actions in Flex Messages.

Example URI action object

# Datetime picker action

When a control associated with this action is tapped, a postback event is returned via webhook with the date and time selected by the user from the date and time selection dialog. The datetime picker action does not support time zones.

type

String

Required

datetimepicker

label

String

See description

Label for the action

Required for templates other than image carousel. Max character limit: 20
Optional for image carousel templates. Max character limit: 12
Optional for rich menus. Spoken when the accessibility feature is enabled on the client device. Max character limit: 20. Supported on LINE 8.2.0 or later for iOS.
Required for quick reply buttons. Max character limit: 20. Supported on 8.11.0 or later for both LINE for iOS and LINE for Android.
Required for the button of Flex Message. This property can be specified for the box, image, and text but its value is not displayed. Max character limit: 20

data

String

Required

String returned via webhook in the postback.data property of the postback event
Max character limit: 300

mode

String

Required

Action mode
date: Pick date
time: Pick time
datetime: Pick date and time

initial

String

Optional

Initial value of date or time

max

String

Optional

Largest date or time value that can be selected. Must be greater than the min value.

min

String

Optional

Smallest date or time value that can be selected. Must be less than the max value.

Example datetime picker action object

# Date and time format

The date and time formats for the initial, max, and min values are shown below. The full-date, time-hour, and time-minute formats follow the RFC3339 (opens new window) protocol.

Mode	Format	Example
date	`full-date` Max: 2100-12-31 Min: 1900-01-01	2017-06-18
time	`time-hour`:`time-minute` Max: 23:59 Min: 00:00	00:00 06:15 23:59
datetime	`full-date`T`time-hour`:`time-minute` or `full-date`t`time-hour`:`time-minute` Max: 2100-12-31T23:59 Min: 1900-01-01T00:00	2017-06-18T06:15 2017-06-18t06:15

# Camera action

This action can be configured only with quick reply buttons. When a button associated with this action is tapped, the camera screen in LINE is opened.

type

String

Required

camera

label

String

Required

Label for the action
Max character limit: 20

Example camera action object

# Camera roll action

This action can be configured only with quick reply buttons. When a button associated with this action is tapped, the camera roll screen in LINE is opened.

type

String

Required

cameraRoll

label

String

Required

Label for the action
Max character limit: 20

Example camera roll action object

# Location action

This action can be configured only with quick reply buttons. When a button associated with this action is tapped, the location screen in LINE is opened.

type

String

Required

location

label

String

Required

Label for the action
Max character limit: 20

Example location action object

Rich menus consist of either of these objects.

Rich menu object without the rich menu ID. Use this object when you create a rich menu.
Rich menu response object with the rich menu ID. This object is returned when you get a rich menu or get a list of rich menus.

Area objects and action objects are included in these objects.

size

Object

Required

size object which contains the width and height of the rich menu displayed in the chat. The width of the rich menu image must be between 800px and 2500px. The height must be at least 250px. However, the aspect ratio of width to height must be at least 1.45.

selected

Boolean

Required

true to display the rich menu by default. Otherwise, false.

name

String

Required

Name of the rich menu. This value can be used to help manage your rich menus and is not displayed to users.
Max character limit: 300

chatBarText

String

Required

Text displayed in the chat bar
Max character limit: 14

areas

Array

Required

Array of area objects which define the coordinates and size of tappable areas
Max: 20 area objects

Example rich menu object

richMenuId

String

ID of a rich menu

size

Object

size object which contains the width and height of the rich menu displayed in the chat. The widths of the rich menu image must be between 800px and 2500px. The height must be at least 250px. However, the aspect ratio of width to height must be at least 1.45.

selected

Boolean

true to display the rich menu by default. Otherwise, false.

name

String

Name of the rich menu. This value can be used to help manage your rich menus and is not displayed to users.
Max character limit: 300

chatBarText

String

Text displayed in the chat bar
Max character limit: 14

areas

Array

Array of area objects which define the coordinates and size of tappable areas
Max: 20 area objects

Example rich menu response object

# `size` object

width

Number

Required

Width of the rich menu. Must be 2500.

height

Number

Required

Height of the rich menu. Possible values: 1686, 843.

Example size object

# Area object

bounds

Object

Required

Object describing the boundaries of the area in pixels. See bounds object.

action

Object

Required

Action performed when the area is tapped. See action objects.

Example area object

# `bounds` object

Number

Required

Horizontal position of the top-left corner of the tappable area relative to the left edge of the image. Value must be 0 or higher.

Number

Required

Vertical position of the top-left corner of the tappable area relative to the left edge of the image. Value must be 0 or higher.

width

Number

Required

Width of the tappable area.

height

Number

Required

Height of the tappable area.

Example bounds object

# Messaging API reference

# Common specifications

# Rate limits

# Status codes

# Response headers

# Error responses

# Error messages

# Webhooks

# Request headers

# Request body

# Response

# Signature validation

# Webhook Event Objects

# Common properties

# Source user

# Source group

# Source room

# Message event

# Text

# Image

# Video

# Audio

# File

# Location

# Sticker

# Unsend event

# Follow event

# Unfollow event

# Join event

# Leave event

# Member join event

# Member leave event

# Postback event

# postback.params object

# Video viewing complete event

# Beacon event

# Beacon event types

# Account link event

# link object

# Device link event

# Device unlink event

# LINE Things scenario execution event

# things.result.resultCode definition

# Webhook settings

# Set webhook endpoint URL

# HTTP request

# Request headers

# Request body

# Response

# Error response

# Get webhook endpoint information

# HTTP request

# Request headers

# Response

# Test webhook endpoint

# HTTP request

# Request headers

# Request body

# Response

# Error response

# OAuth

# Issue channel access token v2.1

# HTTP request

# Request headers

# Request body

# Response

# Error response

# Get all valid channel access token key IDs v2.1

# HTTP request

# Request body

# Response

# Error response

# Revoke channel access token v2.1

# HTTP request

# Request body

# Response

# Error response

# Issue channel access token

# HTTP request

# Request headers

# `postback.params` object

# `link` object