# Common specifications
Common specifications for Messaging API, such as response and rate limit when a request succeeds or fails.
Common specifications for Messaging API, such as response and rate limit when a request succeeds or fails.
The Messaging API applies the following rate limits for each endpoint.
If you send requests exceeding the rate limit, you will receive an error message saying, 429 Too Many Requests
.
When developing a LINE Bot using the Messaging API, follow the Development guidelines, including the guidelines on rate limits.
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 |
|
500 Internal Server Error | Error on the internal server |
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. |
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. For more details, see Details of the error.
details[].property
String
Location of where the error occurred. Returns the JSON field name or query parameter name of the request. Not returned in certain situations.
Example error response
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. |
The details of the error that are found in the details[].message
property of the JSON error responses are shown below.
Message | Description |
---|---|
AUDIENCE_GROUP_CAN_NOT_UPLOAD_STATUS_EXPIRED | The audience was created more than 180 days ago. This audience cannot be used. |
AUDIENCE_GROUP_COUNT_MAX_OVER | You have already created the maximum number of audiences (1,000). |
AUDIENCE_GROUP_NAME_DUPLICATE | There is already an audience with the specified name. |
AUDIENCE_GROUP_NAME_SIZE_OVER | The audience's name is too long. |
AUDIENCE_GROUP_NAME_WRONG | The audience's name contains an invalid character (such as \n or some other control character). |
AUDIENCE_GROUP_NOT_FOUND | Audience not found. |
AUDIENCE_GROUP_REQUESTID_DUPLICATE | There is already an audience with the specified request ID. |
REQUEST_NOT_FOUND | The specified request ID is incorrect or LINE not ready to create an audience with the specified request ID. |
TOO_OLD_MESSAGES | You can't create an audience for a message (request ID) that was sent over 60 days ago. |
UPLOAD_AUDIENCE_GROUP_INVALID_AUDIENCE_ID_FORMAT |
|
UPLOAD_AUDIENCE_GROUP_NO_VALID_AUDIENCE_IDS |
|
UPLOAD_AUDIENCE_GROUP_TOO_MANY_AUDIENCE_IDS | Exceeded the maximum number of user IDs or IFAs. |
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. |
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.
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.
We recommend that you make the event processing asynchronous so that the processing of HTTP POST requests does not delay the processing of subsequent events.
x-line-signature
Used for signature validation
Uppercase and lowercase letters in the Request headers field names may change without notice. The bot server that receives the webhook should handle the header field name without case distinction.[1]
Before change | After change | |
---|---|---|
Header field name example | X-Line-Signature | x-line-signature |
The request body contains a JSON object with the user ID of a bot that should receive webhook events and an array of webhook event objects.
destination
String
User ID of a bot that should receive webhook events. The user ID value is a string that matches the regular expression, U[0-9a-f]{32}
.
events
Array of webhook event objects
List of webhook events. An empty list may be sent from the LINE Platform to confirm communication.
The bot server must return status code 200
after it receives the HTTP POST request sent from the LINE Platform.
HTTP POST requests sent from the LINE Platform aren't resent if the request fails.
The LINE Platform may send an HTTP POST request that doesn't include a webhook event to confirm communication.
In this case, please send a 200
status code.
Example HTTP POST request without a webhook event:
{
"destination": "xxxxxxxxxx",
"events": []
}
The signature in the x-line-signature
request header must be verified to confirm that the request was sent from the LINE Platform.
Authentication is performed as follows:
x-line-signature
in the request header matches the Base64-encoded digest value.Example of signature validation
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
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
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.
type
String
user
userId
String
ID of the source user
Source user example
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
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
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 which contains the text sent from the source.
id
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.
mention
Object
Object containing the contents of the mentioned user.
mention.mentionees[]
Array of mention objects
Mentioned user information.
Max: 20 mentions
mention.mentionees[].index
Number
Index position of the user mention for a character in text
, with the first character being at position 0
.
mention.mentionees[].length
Number
The length of the text of the mentioned user. For a mention @example
, 8 is the length.
mention.mentionees[].userId
String
User ID of the mentioned user. Only returned if the user consents to the LINE Official Account obtaining their user profile information.
Text message example
Message object which contains the image content sent from the source.
id
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
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.
id
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
Message object which contains the audio content sent from the source.
id
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
Message object which contains the file sent from the source. The binary data can be retrieved from the content
endpoint.
id
String
Message ID
type
String
file
fileName
String
File name
fileSize
Number
File size in bytes
File message example
Message object which contains the location data sent from the source.
id
String
Message ID
type
String
location
title
String
Title
address
String
Address
latitude
Decimal
Latitude
longitude
Decimal
Longitude
Location message example
Message object which contains the sticker data sent from the source. For a list of basic LINE stickers and sticker IDs, see sticker list.
You can't get the image of stickers sent by users.
id
String
Message ID
type
String
sticker
packageId
String
Package ID
stickerId
String
Sticker ID
stickerResourceType
String
Sticker resource type. One of:
STATIC
: Still imageANIMATION
: Animated stickerSOUND
: Sticker with soundANIMATION_SOUND
: Animated sticker with soundPOPUP
: Pop-up sticker or Effect stickerPOPUP_SOUND
: Pop-up sticker with sound or Effect sticker with soundNAME_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.keywords
Array of strings
List of up to 15 keywords describing the sticker. If a sticker has 16 or more keywords, a random selection of 15 keywords will be returned. The keyword selection is random for each event, so different keywords may be returned for the same sticker.
stickerResourceType
In the future, we may add new types without notice. Make sure your implementation can handle both current and future sticker resource types.
keywords
The keywords
property is currently in an experimental phase and discontinuation or spec changes may occur in the future.
Sticker message example
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
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
Event object for when your LINE Official Account is blocked.
timestamp, source etc.
Please refer to Common Properties.
type
String
unfollow
Unfollow event example
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.
timestamp, source etc.
Please refer to Common Properties.
type
String
join
replyToken
String
Token for replying to this event
Join event example
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
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
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
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
objectObject 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
Event for when a user finishes viewing a video at least once with the specified trackingId
sent by the LINE Official Account.
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
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.type | Description |
---|---|
enter | Entered 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. |
As of January 2021, we are no longer accepting new applications for banner
and stay
events.
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
objectresult
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
Example link object
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
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
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 unlink event example
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.
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
SLEEP
, return an execution result of type void
.action
array may be 0.Therefore, things.result.actionResults
has the following properties:
GATT_READ
actions, the results are returned in the order in which each individual GATT_READ
action was performed.things.result.actionResults
will be 0.things.result.actionResults[].type
String
void
, binary
type
of the executed action.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
resultCode | Description |
---|---|
success | Indicates that the execution has completed successfully |
gatt_error | Indicates that the execution of the GATT operation failed
|
runtime_error | Indicates that an unexpected error has occurred
|
You can configure, test, and get information on channel webhook endpoints.
Sets the webhook endpoint URL. It may take up to 1 minute for changes to take place due to caching.
Please ensure these webhook URL validation rules are met:
Example request
PUT https://api.line.me/v2/bot/channel/webhook/endpoint
Authorization
Bearer {channel access token}
Content-Type
application/json
endpoint
String
A valid webhook URL.
Returns status code 200
and an empty JSON object.
Example response
Returns a 400
HTTP status code if the webhook URL is invalid.
Example error response
Gets information on a webhook endpoint.
Example request
GET https://api.line.me/v2/bot/channel/webhook/endpoint
Authorization
Bearer {channel access token}
Content-Type
application/json
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
Checks if the configured webhook endpoint can receive a test webhook event.
Please ensure these webhook URL validation rules are met:
Example request
POST https://api.line.me/v2/bot/channel/webhook/test
Authorization
Bearer {channel access token}
Content-Type
application/json
endpoint
String
A webhook URL to be validated.
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.
Returns status code 200
and a JSON object with the following information.
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
: Successfalse
: Failuretimestamp
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
400
HTTP status code if the webhook URL isn't valid.404
HTTP status code if the webhook URL isn't set.You can issue, get, or revoke the channel access token required when calling the Messaging API from the app.
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
POST https://api.line.me/oauth2/v2.1/token
Content-Type
application/x-www-form-urlencoded
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.
The JSON Web Token will expire 30 minutes after being created.
Learn how to Generate a JWT.
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
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
Gets all valid channel access token key IDs.
Example request
GET https://api.line.me/oauth2/v2.1/tokens/kid
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.
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
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
Revokes a channel access token.
Example request
POST https://api.line.me/oauth2/v2.1/revoke
client_id
String
Channel ID
client_secret
String
Channel Secret
access_token
String
Channel access token
Returns status code 200
and an empty response body.
No error occurs if an invalid channel access token is specified.
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
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.
Example request
Content-Type
application/x-www-form-urlencoded
grant_type
String
client_credentials
client_id
String
Channel ID. Found on the LINE Developers Console.
client_secret
String
Channel secret. Found on the LINE Developers Console.
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.
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
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
Revokes a channel access token.
Example request
Content-Type
application/x-www-form-urlencoded
access_token
String
Channel access token
Returns status code 200
and an empty response body. No error occurs if an invalid channel access token is specified.
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
You can send a message and obtain information about the sent 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
POST https://api.line.me/v2/bot/message/reply
Content-Type
application/json
Authorization
Bearer {channel access token}
replyToken
String
Reply token received via webhook
messages
Array of message objects
Messages to send
Max: 5
notificationDisabled
Boolean
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
Returns status code 200
and an empty JSON object.
Example response
Sends a push message to a user, group, or room at any time.
Example request
POST https://api.line.me/v2/bot/message/push
Content-Type
application/json
Authorization
Bearer {channel access token}
to
String
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
Messages to send
Max: 5
notificationDisabled
Boolean
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
Returns status code 200
and an empty JSON object.
Example response
Sends push messages to multiple users at any time. Messages cannot be sent to groups or rooms.
Example request
POST https://api.line.me/v2/bot/message/multicast
Content-Type
application/json
Authorization
Bearer {channel access token}
to
Array of strings
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
Messages to send
Max: 5
notificationDisabled
Boolean
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
Returns status code 200
and an empty JSON object.
Example response
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.
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:
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.
POST https://api.line.me/v2/bot/message/narrowcast
Authorization
Bearer {channel access token}
Content-Type
application/json
messages
Array of message objects
Messages to send
Max: 5
recipient
Object
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
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
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
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
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 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
audience
audienceGroupId
Number
The audience ID. Create audiences with the manage audience API.
Redelivery object
type
String
redelivery
requestId
String
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.
The request ID specified in the requestId
property must satisfy all of these conditions:
completedTime
of the Get narrowcast message status API endpoint.phase
property is succeeded
in the response of the Get narrowcast message status API endpoint).Logical operator objects
Use logical AND, OR, and NOT operators to combine multiple recipient objects together.
type
String
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 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.
Gender
type
String
gender
oneOf
Array of strings
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
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
appType
oneOf
Array of strings
Send messages to users with the specified OS. One of:
ios
android
Region
type
String
area
oneOf
Array of strings
Send messages to users in the specified region. One of:
日本 // JP (country code=392)
jp_01
: 北海道 // Hokkaidojp_02
: 青森県 // Aomorijp_03
: 岩手県 // Iwatejp_04
: 宮城県 // Miyagijp_05
: 秋田県 // Akitajp_06
: 山形県 // Yamagatajp_07
: 福島県 // Fukushimajp_08
: 茨城県 // Ibarakijp_09
: 栃木県 // Tochigijp_10
: 群馬県 // Gunmajp_11
: 埼玉県 // Saitamajp_12
: 千葉県 // Chibajp_13
: 東京都 // Tokyojp_14
: 神奈川県 // Kanagawajp_15
: 新潟県 // Niigatajp_16
: 富山県 // Toyamajp_17
: 石川県 // Ishikawajp_18
: 福井県 // Fukuijp_19
: 山梨県 // Yamanashijp_20
: 長野県 // Naganojp_21
: 岐阜県 // Gifujp_22
: 静岡県 // Shizuokajp_23
: 愛知県 // Aichijp_24
: 三重県 // Miejp_25
: 滋賀県 // Shigajp_26
: 京都府 // Kyotojp_27
: 大阪府 // Osakajp_28
: 兵庫県 // Hyougojp_29
: 奈良県 // Narajp_30
: 和歌山県 // Wakayamajp_31
: 鳥取県 // Tottorijp_32
: 島根県 // Shimanejp_33
: 岡山県 // Okayamajp_34
: 広島県 // Hiroshimajp_35
: 山口県 // Yamaguchijp_36
: 徳島県 // Tokushimajp_37
: 香川県 // Kagawajp_38
: 愛媛県 // Ehimejp_39
: 高知県 // Kouchijp_40
: 福岡県 // Fukuokajp_41
: 佐賀県 // Sagajp_42
: 長崎県 // Nagasakijp_43
: 熊本県 // Kumamotojp_44
: 大分県 // Oitajp_45
: 宮崎県 // Miyazakijp_46
: 鹿児島県 // Kagoshimajp_47
: 沖縄県 // Okinawa台湾 // TW (country code=158)
tw_01
: 台北市 // Taipei Citytw_02
: 新北市 // New Taipei Citytw_03
: 桃園市 // Taoyuan Citytw_04
: 台中市 // Taichung Citytw_05
: 台南市 // Tainan Citytw_06
: 高雄市 // Kaohsiung Citytw_07
: 基隆市 // Keelung Citytw_08
: 新竹市 // Hsinchu Citytw_09
: 嘉義市 // Chiayi Citytw_10
: 新竹県 // Hsinchu Countytw_11
: 苗栗県 // Miaoli Countytw_12
: 彰化県 // Changhua Countytw_13
: 南投県 // Nantou Countytw_14
: 雲林県 // Yunlin Countytw_15
: 嘉義県 // Chiayi Countytw_16
: 屏東県 // Pingtung Countytw_17
: 宜蘭県 // Yilan Countytw_18
: 花蓮県 // Hualien Countytw_19
: 台東県 // Taitung Countytw_20
: 澎湖県 // Penghu Countytw_21
: 金門県 // Kinmen Countytw_22
: 連江県 // Lienchiang Countyタイ // TH (country code=764)
th_01
: バンコク // Bangkokth_02
: パタヤ // Pattayath_03
: 北部 // Northernth_04
: 中央部 // Centralth_05
: 南部 // Southernth_06
: 東部 // Easternth_07
: 東北部 // NorthEasternth_08
: 西部 // Westernインドネシア // ID (country code=360)
id_01
: バリ // Baliid_02
: バンドン // Bandungid_03
: バンジャルマシン // Banjarmasinid_04
: ジャボデタベック(ジャカルタ首都圏) // Jabodetabekid_06
: マカッサル // Makassarid_07
: メダン // Medanid_08
: パレンバン // Palembangid_09
: サマリンダ // Samarindaid_10
: スマラン // Semarangid_11
: スラバヤ // Surabayaid_12
: ジョグジャカルタ // Yogyakartaid_05
: その他のエリア // LainnyaFriendship duration
This lets you filter recipients with a given range of friendship durations.
type
String
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
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
Returns the 202
HTTP status code.
For more information on how to check the status of a narrowcast message, see Get narrowcast message status.
Gets the status of a narrowcast message.
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.
You can get the status of a narrowcast message for up to 7 days (168 hours) after the timestamp displayed in completedTime
.
Example request
GET https://api.line.me/v2/bot/message/progress/narrowcast
Authorization
Bearer {channel access token}
requestId
The narrowcast message's request ID. Each Messaging API request has a request ID. Find it in the response headers.
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.acceptedTime
String
Narrowcast message request accepted time in milliseconds.
2020-12-03T10:15:30.121Z
)completedTime
String
Processing of narrowcast message request completion time in milliseconds. Returned when the phase
property is succeeded
or failed
.
2020-12-03T10:15:30.121Z
)* Not available when the phase
property is waiting
.
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.
Sends push messages to multiple users at any time.
Example request
POST https://api.line.me/v2/bot/message/broadcast
Content-Type
application/json
Authorization
Bearer {channel access token}
messages
Array of message objects
Messages to send
Max: 5
notificationDisabled
Boolean
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
Returns status code 200
and an empty JSON object.
Example response
Gets images, videos, audio, and files sent by users.
You can't use the Messaging API to retrieve text sent by users.
Example request
GET https://api-data.line.me/v2/bot/message/{messageId}/content
Authorization
Bearer {channel access token}
messageId
Message ID
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.
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
Authorization
Bearer {channel access token}
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
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
Authorization
Bearer {channel access token}
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
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
Authorization
Bearer {channel access token}
date
Date the messages were sent
yyyyMMdd
(Example: 20191231
)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
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
Authorization
Bearer {channel access token}
date
Date the messages were sent
yyyyMMdd
(Example: 20191231
)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
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
Authorization
Bearer {channel access token}
date
Date the messages were sent
yyyyMMdd
(Example: 20191231
)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
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
GET https://api.line.me/v2/bot/message/delivery/broadcast
Authorization
Bearer {channel access token}
date
Date the messages were sent
yyyyMMdd
(Example: 20191231
)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
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.
Example request
X-Line-Retry-Key
Arbitrarily generated UUID in hexadecimal notation (example: 123e4567-e89b-12d3-a456-426614174000)
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
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. | |
An audience used for click-based retargeting. | |
An audience used for impression-based retargeting. | |
Chat tag audience. | |
Friend path audience. | |
Web traffic audience. |
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 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).
You can get User IDs by using the following methods:
source
object of Webhook event objectsAudience 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.
If an invalid user ID is specified in the audiences
property of JSON, the error response (details[].message
: 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
POST https://api.line.me/v2/bot/audienceGroup/upload
Authorization
Bearer {channel access token}
Content-Type
application/json
description
String
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
true
.false
or omit isIfaAudience
property.uploadDescription
String
The description to register for the job (in jobs[].description
).
audiences
Array
An array of user IDs or IFAs.
Max number: 10,000
audiences[].id
String
A user ID or IFA. You can specify an empty array.
Returns an audience along with the 202
HTTP status code.
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
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
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 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).
You can get User IDs by using the following methods:
source
object of Webhook event objectsAudience 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 |
Learn more from Usage restrictions of narrowcast messages.
Example request
Text file example
POST https://api-data.line.me/v2/bot/audienceGroup/upload/byFile
Authorization
Bearer {channel access token}
Content-Type
multipart/form-data
description
String
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
true
.false
or omit isIfaAudience
property.uploadDescription
String
The description to register for the job (in jobs[].description
).
file
File
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
Returns an audience along with the 202
HTTP status code.
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
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
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.
We strongly recommend using request timeout values of 30 seconds or more.
If an invalid user ID is specified in the audiences
property of JSON, the error response (details[].message
: 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.
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.
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 cannot delete a user ID or IFA after adding it.
Example request
PUT https://api.line.me/v2/bot/audienceGroup/upload
Authorization
Bearer {channel access token}
Content-Type
application/json
audienceGroupId
Number
The audience ID.
uploadDescription
String
The description to register with the job (in jobs[].description
).
audiences
Array
An array of up to 10,000 user IDs or IFAs.
audiences[].id
String
A user ID or IFA.
Returns status code 202
and an empty JSON object.
Before using an audience, Ensure audience can be used for delivery.
Example response
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
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.
We strongly recommend using request timeout values of 30 seconds or more.
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 cannot delete a user ID or IFA after adding it.
Example request
Example text
PUT https://api-data.line.me/v2/bot/audienceGroup/upload/byFile
Authorization
Bearer {channel access token}
Content-Type
multipart/form-data
audienceGroupId
Number
The audience ID.
uploadDescription
String
The description to register with the job (in jobs[].description
).
file
File
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
Returns status code 202
and an empty JSON object.
Before using an audience, Ensure audience can be used for delivery.
Example response
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
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.
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.
Learn more from Usage restrictions of narrowcast messages.
Example request
POST https://api.line.me/v2/bot/audienceGroup/click
Authorization
Bearer {channel access token}
Content-Type
application/json
description
String
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
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.
The request IDs of reply messages, push messages, and multicast messages cannot be used.
clickUrl
String
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
Returns an audience along with the 202
HTTP status code.
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
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
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.
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.
Learn more from Usage restrictions of narrowcast messages.
Example request
POST https://api.line.me/v2/bot/audienceGroup/imp
Authorization
Bearer {channel access token}
Content-Type
application/json
description
String
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
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.
Returns an audience along with the 202
HTTP status code.
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
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
Renames an existing audience.
Example request
PUT https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}/updateDescription
Authorization
Bearer {channel access token}
Content-Type
application/json
audienceGroupId
The audience ID.
description
String
The audience's name. Audience names must be unique. This is case-insensitive, meaning AUDIENCE
and audience
are considered identical.
Max character limit: 120
Returns the 200
HTTP status code.
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
Deletes an audience.
Make sure that an audience is no longer in use before you delete it.
Example request
DELETE https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}
Authorization
Bearer {channel access token}
audienceGroupId
The audience ID.
Returns the 202
HTTP status code.
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
Gets audience data.
Example request
GET https://api.line.me/v2/bot/audienceGroup/{audienceGroupId}
Authorization
Bearer {channel access token}
audienceGroupId
The audience ID.
Returns a 200
HTTP status code and a JSON object with the following information.
audienceGroup
Object
Audience group object.
audienceGroup.audienceGroupId
Number
The audience ID.
audienceGroup.createRoute
String
How the audience was created. One of:
OA_MANAGER
: Audience created with LINE Official Account Manager (opens new window).MESSAGING_API
: Audience created with Messaging API.audienceGroup.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.WEBTRAFFIC
: Web traffic audience.For more information, see the Audience (opens new window) page on LINE for Business. This page isn't currently available in English.
audienceGroup.description
String
The audience's name.
audienceGroup.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.audienceGroup.audienceCount
Number
The number of valid recipients.
audienceGroup.created
Number
When the audience was created (in UNIX time).
audienceGroup.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.audienceGroup.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.audienceGroup.requestId
String
The request ID that was specified when the audience was created. This is only included when audienceGroup.type
is CLICK
or IMP
.
audienceGroup.clickUrl
String
The URL that was specified when the audience was created. This is only included when audienceGroup.type
is CLICK
and link URL is specified.
audienceGroup.failedType
String
The reason why the operation failed. This is only included when audienceGroup.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.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. Empty array is returned for any other type of audience.
Max: 50
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[].status
String
This property is deprecated. Refer to jobs[].jobStatus
for the status of jobs.
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).
jobs[].jobStatus
String
The job's status. One of:
QUEUED
: Waiting to run.WORKING
: Running.FINISHED
: Completed.FAILED
: Failed.Example response
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
Example error response
Gets data for more than one audience.
Example request
GET https://api.line.me/v2/bot/audienceGroup/list
Authorization
Bearer {channel access token}
page
The page to return when getting (paginated) results. Must be 1
or higher.
description
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
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
The number of audiences per page. Default: 20
Max: 40
includesExternalPublicGroups
true
: Get public audiences created in all channels linked to the same bot.false
: Get audiences created in the same channel.createRoute
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.Returns a 200
HTTP status code and a JSON object with the following information.
audienceGroups
Array
An array of audience data. If there are no audiences that match the specified filter, an empty array will be returned.
audienceGroups[].audienceGroupId
Number
The audience ID.
audienceGroups[].createRoute
String
How the audience was created. One of:
OA_MANAGER
: Audience was created with LINE Official Account Manager (opens new window).MESSAGING_API
: Audience was created with Messaging API.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.WEBTRAFFIC
: Web traffic 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[].audienceCount
Number
The number of valid recipients.
audienceGroups[].created
Number
When the audience was created (in UNIX time).
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[].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[].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[].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.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 filter, the number of audiences with the update permission set to READ_WRITE
.
page
Int
The current page number.
size
Int
The maximum number of audiences on the current page.
Example response
Returns a 400
HTTP status code and the error response. For more details, see the Error responses section of the Common specifications.
Example error response
Get the authority level of the audience
The authority levels are set for each channel. You can't set different authority levels for different audiences.
Example request
GET https://api.line.me/v2/bot/audienceGroup/authorityLevel
Authorization
Bearer {channel access token}
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 all audiences created in the same channel.
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.PRIVATE
will be available only in the channel where you created the audience.The authority levels are set for each channel. You can't set different authority levels for different audiences.
Example request
PUT https://api.line.me/v2/bot/audienceGroup/authorityLevel
Authorization
Bearer {channel access token}
Content-Type
application/json
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.Returns the HTTP 200
status code.
You can obtain information on the number of messages sent from the LINE Official Account, number of friends, and other statistical data.
Returns the number of messages sent from LINE Official Account on a specified day.
Example request
GET https://api.line.me/v2/bot/insight/message/delivery?date={date}
Authorization
Bearer {channel access token}
date
Date for which to retrieve number of sent messages.
yyyyMMdd
(Example: 20191231
)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
Returns the number of users who have added the LINE Official Account on or before a specified date.
Example request
GET https://api.line.me/v2/bot/insight/followers?date={date}
Authorization
Bearer {channel access token}
date
Date for which to retrieve the number of followers.
yyyyMMdd
(Example: 20191231
)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
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).
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
GET https://api.line.me/v2/bot/insight/demographic
Authorization
Bearer {channel access token}
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
TW
台北市
(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
TH
Bangkok
Pattaya
Northern
Central
Southern
Eastern
NorthEastern
Western
unknown
ID
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
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.
Interactions are tracked for only 14 days after a message was sent. The statistics are no longer updated after 15 days.
Example request
GET https://api.line.me/v2/bot/insight/message/event?requestId={requestId}
Authorization
Bearer {channel access token}
requestId
Request ID of a narrowcast message or broadcast message. Each Messaging API request has a request ID. Find it in the response headers.
Returns status code 200
and a JSON object with these properties:
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
You can get information of users who have added your LINE Official Account as a friend.
Get the profile information of users who have added your LINE Official Account as a friend.
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.
Example request
Authorization
Bearer {channel access token}
userId
User ID that is returned in a webhook event object. Do not use the LINE ID found on LINE.
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:
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
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
GET https://api.line.me/v2/bot/followers/ids
Content-Type
application/json
Authorization
Bearer {channel access token}
start
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.
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
next
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
You can obtain basic information on the LINE Official Account's bots.
Gets a bot's basic information.
Example request
GET https://api.line.me/v2/bot/info
Content-Type
application/json
Authorization
Bearer {channel access token}
Returns status code 200
and a JSON object with the following information.
userID
String
Bot's user ID
basicId
String
Bot's basic ID
premiumId
String
Bot's premium ID. Not included in the response if the premium ID isn't set.
displayName
String
Bot's display name
pictureUrl
String
Profile image URL. "https" image URL. Not included in the response if the bot doesn't have a profile image.
chatMode
String
Bot's response mode set in the LINE Official Account Manager (opens new window). One of:
chat
: The response mode is set to "Chat".bot
: The response mode is set to "Bot".markAsReadMode
String
Automatic read setting for messages. If the bot's response mode is "Bot", auto
is returned. If the response mode is "Chat", manual
is returned.
auto
: Auto read setting is enabled.manual
: Auto read setting is disabled.Example response
You can obtain information on the LINE official account's groups and members of the groups.
Gets the group ID, group name, and group icon URL of a group where the LINE Official Account is a member.
Example request
GET https://api.line.me/v2/bot/group/{groupId}/summary
Authorization
Bearer {channel access token}
groupId
Group ID. Found in the source object of webhook event objects.
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
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
GET https://api.line.me/v2/bot/group/{groupId}/members/count
Authorization
Bearer {channel access token}
groupId
Group ID. Found in the source object of webhook event objects.
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
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
GET https://api.line.me/v2/bot/group/{groupId}/members/ids
Authorization
Bearer {channel access token}
groupId
Group ID. Found in the source
object of webhook event objects.
start
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.
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
next
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
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
GET https://api.line.me/v2/bot/group/{groupId}/member/{userId}
Authorization
Bearer {channel access token}
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.
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
Leaves a group.
Example request
POST https://api.line.me/v2/bot/group/{groupId}/leave
Authorization
Bearer {channel access token}
groupId
Group ID. Found in the source
object of webhook event objects.
Returns status code 200
and an empty JSON object.
Example response
You can obtain information about the LINE official account's chat rooms and their members.
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
GET https://api.line.me/v2/bot/room/{roomId}/members/count
Authorization
Bearer {channel access token}
roomId
Room ID. Found in the source object of webhook event objects.
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
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
GET https://api.line.me/v2/bot/room/{roomId}/members/ids
Authorization
Bearer {channel access token}
roomId
Room ID. Found in the source
object of webhook event objects.
start
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.
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
next
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
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
GET https://api.line.me/v2/bot/room/{roomId}/member/{userId}
Authorization
Bearer {channel access token}
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.
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
Leaves a room.
Example request
POST https://api.line.me/v2/bot/room/{roomId}/leave
Authorization
Bearer {channel access token}
roomId
Room ID. Found in the source
object of webhook event objects.
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:
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
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
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.
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
ID of a rich menu
Returns status code 200
and a rich menu response object.
Example response
Deletes a rich menu.
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
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):
Example request
POST https://api.line.me/v2/bot/user/all/richmenu/{richMenuId}
Authorization
Bearer {channel access token}
richMenuId
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):
Example request
POST https://api.line.me/v2/bot/user/{userId}/richmenu/{richMenuId}
Authorization
Bearer {channel access token}
richMenuId
ID of a rich menu
userId
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):
Example request
POST https://api.line.me/v2/bot/richmenu/bulk/link
Content-Type
application/json
Authorization
Bearer {channel access token}
richMenuId
String
ID of a rich menu
userIds
Array of strings
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
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
API that removes the per-user rich menu linked to a specified user.
Example request
DELETE https://api.line.me/v2/bot/user/{userId}/richmenu
Authorization
Bearer {channel access token}
userId
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
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
You can link the service account provided by the provider (corporate and developer) with the account of the LINE user.
Issues a link token used for the account link feature.
Example request
POST https://api.line.me/v2/bot/user/{userId}/linkToken
Authorization
Bearer {channel access token}
userId
User ID for the LINE account to be linked. Found in the source
object of account link event objects. Do not use the LINE ID used in LINE.
Returns status code 200
and a link token. Link tokens are valid for 10 minutes and can only be used once.
The validity period may change without notice.
Example response
JSON object which contains the contents of the message you send.
The following properties can be specified in all the message objects.
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
If the user receives multiple message objects, the quickReply
property of the last message object is displayed.
This is a container that contains quick reply buttons.
items
Array of objects
Quick reply button objects. Max: 13 objects
Example items object
This is a quick reply option that is displayed as a button.
type
String
action
imageUrl
String
URL of the icon that is displayed at the beginning of the button
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
Action performed when this button is tapped. Specify an action object. The following is a list of the available actions:
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.
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
Display name. Certain words such as LINE
may not be used.
Max character limit: 20
sender.iconUrl
String
URL of the image to display as an icon when sending a message
Text message example of changed icon and display name
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
text
text
String
Message text. You can include the following emoji:
$
character as a placeholder and specify details in the emojis
property)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.
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
type
String
sticker
packageId
String
Package ID for a set of stickers. For information on package IDs, see the Sticker list.
stickerId
String
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
type
String
image
originalContentUrl
String
Image URL (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Max image size: No limits
Max file size: 10 MB
previewImageUrl
String
Preview image URL (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Max image size: No limits
Max file size: 1 MB
Image message example
type
String
video
originalContentUrl
String
URL of video file (Max character limit: 1000)
HTTPS over TLS 1.2 or later
mp4
Max file size: 200 MB
A very wide or tall video may be cropped when played in some environments.
previewImageUrl
String
URL of preview image (Max character limit: 1000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Max file size: 1 MB
trackingId
String
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.
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
type
String
audio
originalContentUrl
String
URL of audio file (Max character limit: 1000)
HTTPS over TLS 1.2 or later
m4a
Max file size: 200 MB
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
Length of audio file (milliseconds)
Audio message example
type
String
location
title
String
Title
Max character limit: 100
address
String
Address
Max character limit: 100
latitude
Decimal
Latitude
longitude
Decimal
Longitude
Location message example
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.
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
imagemap
baseUrl
String
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
Alternative text
Max character limit: 400
baseSize.width
Number
Width of base image in pixels. Set to 1040.
baseSize.height
Number
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
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
JPEG or PNG
Max image size: No limits
Max file size: 1 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
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
Images used in imagemap messages must meet the following requirements.
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 |
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
).
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.
type
String
uri
label
String
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
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
Defined tappable area
Example imagemap URI action object
type
String
message
label
String
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
Message to send
Max character limit: 400
Supported on LINE for iOS and Android only.
area
Defined tappable area
Example imagemap message action 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.
x
Number
Horizontal position relative to the left edge of the area. Value must be 0
or higher.
y
Number
Vertical position relative to the top of the area. Value must be 0
or higher.
width
Number
Width of the tappable area
height
Number
Height of the tappable area
Example imagemap area object
Template messages are messages with predefined layouts which you can customize. For more information, see Template messages.
The following template types are available:
Template messages are only available on LINE for iOS and LINE for Android.
The following properties are common to all template message objects.
type
String
template
altText
String
Alternative text. Displayed on devices that do not support template messages.
Max character limit: 400
template
Object
A Buttons, Confirm, Carousel, or Image Carousel object.
Template with an image, title, text, and multiple action buttons.
type
String
buttons
thumbnailImageUrl
String
Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Max width: 1024px
Max file size: 10 MB
To avoid delays in displaying messages, keep the size of individual image files small (1 MB or less recommended).
imageAspectRatio
String
Aspect ratio of the image. One of:
rectangle
: 1.51:1square
: 1:1Default: rectangle
imageSize
String
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
Background color of the image. Specify a RGB color value. Default: #FFFFFF
(white)
title
String
Title
Max character limit: 40
text
String
Message text
Max character limit: 160 (no image or title)
Max character limit: 60 (message with an image or title)
defaultAction
Action when image, title or text area is tapped.
actions
Array of action objects
Action when tapped
Max objects: 4
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
Template with two action buttons.
type
String
confirm
text
String
Message text
Max character limit: 240
actions
Array of action objects
Action when tapped
Set 2 actions for the 2 buttons
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
Template with multiple columns which can be cycled like a carousel. The columns are shown in order when scrolling horizontally.
type
String
carousel
columns
Array of column objects
Array of columns
Max columns: 10
imageAspectRatio
String
Aspect ratio of the image. One of:
rectangle
: 1.51:1square
: 1:1Applies to all columns. Default: rectangle
imageSize
String
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
thumbnailImageUrl
String
Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Aspect ratio: 1:1.51
Max width: 1024px
Max file size: 10 MB
To avoid delays in displaying messages, keep the size of individual image files small (1 MB or less recommended).
imageBackgroundColor
String
Background color of the image. Specify a RGB color value. The default value is #FFFFFF
(white).
title
String
Title
Max character limit: 40
text
String
Message text
Max character limit: 120 (no image or title)
Max character limit: 60 (message with an image or title)
defaultAction
Action when image, title or text area is tapped.
actions
Array of action objects
Action when tapped
Max objects: 3
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.
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.
Template with multiple images which can be cycled like a carousel. The images are shown in order when scrolling horizontally.
type
String
image_carousel
columns
Array of column objects
Array of columns
Max columns: 10
Image carousel template message example
imageUrl
String
Image URL (Max character limit: 1,000)
HTTPS over TLS 1.2 or later
JPEG or PNG
Aspect ratio: 1:1
Max width: 1024px
Max file size: 10 MB
To avoid delays in displaying messages, keep the size of individual image files small (1 MB or less recommended).
action
Action when image is tapped
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.
type
String
flex
altText
String
Alternative text
Max character limit: 400
contents
Object
Flex Message container
Flex Message example
Flex Messages are supported on the following versions of LINE:
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 |
A container is the top-level structure of a Flex Message. Here are the types of containers available:
For JSON samples and usage of containers, see Flex Message elements in the API documentation.
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
bubble
size
String
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
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 rightrtl
: The text is right-to-left horizontal writing, and the components are placed from right to leftThe default value is ltr
.
header
Object
Header block. Specify a Box.
body
Object
Body block. Specify a Box.
footer
Object
Footer block. Specify a Box.
styles
Object
Style of each block. Specify a bubble style.
action
Object
Action performed when this image is tapped. Specify an action object. This property is supported on the following versions of LINE.
Bubble example
Use the following two objects to define the style of blocks in a bubble.
Example of a bubble style and block style
header
Object
Header block. Specify a block style.
hero
Object
Hero block. Specify a block style.
body
Object
Body block. Specify a block style.
footer
Object
Footer block. Specify a block style.
backgroundColor
String
Background color of the block. Use a hexadecimal color code.
separator
Boolean
true
to place a separator above the block. The default value is false
.
separatorColor
String
Color of the separator. Use a hexadecimal color code.
You cannot place a separator above the first block.
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
carousel
contents
Array of objects
Bubbles within a carousel. Max: 12 bubbles
A carousel can't contain bubbles of different widths (size
property). Each bubble in a carousel should have the same width.
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
Components are elements that make up a block. Here are the types of components available:
For JSON samples and usage of each component, see Flex Message elements and Flex Message layout in the Messaging API documentation.
This is a component that defines the layout of child components. You can also include a box in a box.
type
String
box
layout
String
The layout style of components in this box. For more information, see Direction of placing components in the API documentation.
contents
Array of objects
Components in this box. Here are the types of components available:
layout
property is horizontal
or vertical
: box, button, image, text, separator, and fillerlayout
property is baseline
: icon, text, and fillerComponents are rendered in the same order specified in the array. You may also specify an empty array.
backgroundColor
String
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
Color of box border. Use a hexadecimal color code.
borderWidth
String
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
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
Box width. For more information, see Box width in the Messaging API documentation.
height
String
Box height. For more information, see Box height in the Messaging API documentation.
flex
Number
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
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
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
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
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
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
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
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
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
The top offset. For more information, see Offset in the Messaging API documentation.
offsetBottom
String
The bottom offset. For more information, see Offset in the Messaging API documentation.
offsetStart
String
The left offset. For more information, see Offset in the Messaging API documentation.
offsetEnd
String
The right offset. For more information, see Offset in the Messaging API documentation.
action
Object
Action performed when this image is tapped. Specify an action object. This property is supported on the following versions of LINE.
justifyContent
String
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
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
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
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
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
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
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
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
This component renders a button. When the user taps a button, a specified action is performed.
type
String
button
action
Object
Action performed when this button is tapped. Specify an action object.
flex
Number
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
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
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
The top offset. For more information, see Offset in the Messaging API documentation.
offsetBottom
String
The bottom offset. For more information, see Offset in the Messaging API documentation.
offsetStart
String
The left offset. For more information, see Offset in the Messaging API documentation.
offsetEnd
String
The right offset. For more information, see Offset in the Messaging API documentation.
height
String
Height of the button. You can specify sm
or md
. The default value is md
.
style
String
Style of the button. Specify one of the following values:
primary
: Style for dark color buttonssecondary
: Style for light color buttonslink
: HTML link styleThe default value is link
.
color
String
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
Alignment style in vertical direction. For more information, see Vertical alignment in the Messaging API documentation.
adjustMode
String
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
This component renders an image.
type
String
image
url
String
Image URL
Protocol: HTTPS (TLS 1.2 or later)
Image format: JPEG or PNG
Maximum image size: 1024×1024 pixels
Maximum file size: 10 MB (300 KB when the animated
property is true
)
To avoid delays in displaying messages, keep the size of individual image files small (1 MB or less recommended).
flex
Number
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
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
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
The top offset. For more information, see Offset in the Messaging API documentation.
offsetBottom
String
The bottom offset. For more information, see Offset in the Messaging API documentation.
offsetStart
String
The left offset. For more information, see Offset in the Messaging API documentation.
offsetEnd
String
The right offset. For more information, see Offset in the Messaging API documentation.
align
String
Alignment style in horizontal direction. For more information, see Alignment in horizontal direction in the Messaging API documentation.
gravity
String
Alignment style in vertical direction. For more information, see Alignment in vertical direction in the Messaging API documentation.
size
String
The maximum image width. This is md
by default. For more information, see Image size in the Messaging API documentation.
aspectRatio
String
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
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
Background color of the image. Use a hexadecimal color code.
action
Object
Action performed when this image is tapped. Specify an action object.
animated
Boolean
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.
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.
If your image appears but no animation plays, check the following:
animated
property equal to true
?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
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.
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.aspectRatio
property do not match, the image is displayed according to the aspectMode
property. The default value is fit
.
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.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.This component renders an icon for decorating the adjacent text.
This component can be used only in a baseline box.
type
String
icon
url
String
Image URL
Protocol: HTTPS (TLS 1.2 or later)
Image format: JPEG or PNG
Maximum image size: 1024×1024 pixels
Maximum data size: 1 MB
margin
String
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
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
The top offset. For more information, see Offset in the Messaging API documentation.
offsetBottom
String
The bottom offset. For more information, see Offset in the Messaging API documentation.
offsetStart
String
The left offset. For more information, see Offset in the Messaging API documentation.
offsetEnd
String
The right offset. For more information, see Offset in the Messaging API documentation.
size
String
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
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
This component renders a text string in one row. You can specify font color, size, and weight.
type
String
text
text
String
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
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
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
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
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
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
The top offset. For more information, see Offset in the Messaging API documentation.
offsetBottom
String
The bottom offset. For more information, see Offset in the Messaging API documentation.
offsetStart
String
The left offset. For more information, see Offset in the Messaging API documentation.
offsetEnd
String
The right offset. For more information, see Offset in the Messaging API documentation.
size
String
Font size. This is md
by default. For more information, see Icon, text, and span size in the Messaging API documentation.
align
String
Alignment style in horizontal direction. For more information, see Alignment in horizontal direction in the Messaging API documentation.
gravity
String
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
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
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.
weight
String
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
Font color. Use a hexadecimal color code.
action
Object
Action performed when this image is tapped. Specify an action object.
style
String
Style of the text. Specify one of these values:
normal
: Normalitalic
: ItalicThe default value is normal
.
decoration
String
Decoration of the text. Specify one of these values:
none
: No decorationunderline
: Underlineline-through
: StrikethroughThe default value is none
.
Text example
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
span
text
String
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
Font color. Use a hexadecimal color code.
size
String
Font size. For more information, see Icon, text, and span size in the Messaging API documentation.
weight
String
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
Style of the text. Specify one of these values:
normal
: Normalitalic
: ItalicThe default value is normal
.
decoration
String
Decoration of the text. Specify one of these values:
none
: No decorationunderline
: Underlineline-through
: StrikethroughThe default value is none
.
The decoration set in the decoration
property of the text cannot be overwritten by the decoration
property of the span.
Span example
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
separator
margin
String
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
Color of the separator. Use a hexadecimal color code.
Separator example
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
filler
flex
Number
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
These are types of actions for your bot to take when a user taps a button or an image in a message.
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
postback
label
String
Label for the action
data
String
String returned via webhook in the postback.data
property of the postback event
Max character limit: 300
displayText
String
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
【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
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
message
label
String
Label for the action
text
String
Text sent when the action is performed
Max character limit: 300
Example message action object
When a control associated with this action is tapped, the URI specified in the uri
property is opened.
type
String
uri
label
String
Label for the action
uri
String
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
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.
The altUri.desktop
property is supported only when you set URI actions in Flex Messages.
Example URI action object
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
datetimepicker
label
String
Label for the action
data
String
String returned via webhook in the postback.data
property of the postback event
Max character limit: 300
mode
String
Action mode
date
: Pick date
time
: Pick time
datetime
: Pick date and time
initial
String
Initial value of date or time
max
String
Largest date or time value that can be selected. Must be greater than the min
value.
min
String
Smallest date or time value that can be selected. Must be less than the max
value.
Example datetime picker action object
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 Ttime-hour :time-minute or full-date ttime-hour :time-minute Max: 2100-12-31T23:59 Min: 1900-01-01T00:00 | 2017-06-18T06:15 2017-06-18t06:15 |
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
camera
label
String
Label for the action
Max character limit: 20
Example camera action object
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
cameraRoll
label
String
Label for the action
Max character limit: 20
Example camera roll action object
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
location
label
String
Label for the action
Max character limit: 20
Example location action object
Rich menus consist of either of these objects.
Area objects and action objects are included in these objects.
size
Object
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
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 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
objectwidth
Number
Width of the rich menu. Must be 2500
.
height
Number
Height of the rich menu. Possible values: 1686
, 843
.
Example size object
bounds
Object
Object describing the boundaries of the area in pixels. See bounds
object.
action
Object
Action performed when the area is tapped. See action objects.
Example area object
bounds
objectx
Number
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.
y
Number
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
Width of the tappable area.
height
Number
Height of the tappable area.
Example bounds object