# Sending messages
You can create bots to send messages to users at any time, or reply to messages from users with reply messages. You can also use various types of messages.
| dummy | dummy |
|---|---|
| Messaging method |
|
| Message types |
|
# Messaging methods
The Messaging API provides two main types of sending methods to use.
# Reply to messages and actions from users (reply messages)
Reply messages are used to reply to the user with a message when the user adds your LINE Official Account as a friend or sends a message.
The body of the message should contain the same reply token that was part of the webhook event. You can send up to 5 message objects in a single request.
Example request
curl -v -X POST https://api.line.me/v2/bot/message/reply \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {channel access token}' \
-d '{
"replyToken":"nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
"messages":[
{
"type":"text",
"text":"Hello, user"
},
{
"type":"text",
"text":"May I help you?"
}
]
}'
For more information, see Send reply message in the Messaging API reference.
# Send messages at any time
You can send messages to users at any time by one of the following methods:
| Message method | Description |
|---|---|
| Push messages | Specify users, groups, and rooms to send messages. For example, when you want to notify users of the shipment of an item on a shopping site. |
| Multicast messages | Efficiently send the same message to multiple users. For example, when you want users who have used a shopping site to be notified of new features at the same time. |
| Narrowcast messages | Send the same message to multiple users. Recipients are specified using attribute information (e.g., gender, age, OS type, region, etc.) or retargeting (audience). |
| Broadcast messages | Send the same message to all users who are friends with your LINE Official Account. |
You can send up to 5 message objects in a single request.
The number of messages is counted by the number of people to whom the message was sent. For example, even if you send a push message with four message objects specified in a single request to a chat room containing five people, the number of messages counted is five. The number of message objects specified in a single request doesn't affect the number of messages sent.
Also, if you send a message to a user ID that has blocked the LINE Official Account, a user ID that doesn't exist, or to any other users that won't actually receive your message, it won't be counted as one message.
Sample request for push messages
curl -v -X POST https://api.line.me/v2/bot/message/push \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {channel access token}' \
-d '{
"to": "U4af4980629...",
"messages":[
{
"type":"text",
"text":"Hello, world1"
},
{
"type":"text",
"text":"Hello, world2"
}
]
}'
# Sending messages to multiple users via attribute data or retargeting (narrowcast messages)
This technique lets you send a message to multiple users at any time. You can specify recipients using attributes (such as age, gender, OS, and region) or by retargeting (audiences). Messages cannot be sent to group chats or multi-person chats.
Follow these steps to send narrowcast messages:
- Prepare a list of recipients
- Begin sending narrowcast messages
- Check the status of the narrowcast messages
# Preparing a list of recipients
You must prepare different kinds of data for different types of recipients. You can combine these recipients using logical operators (AND, OR, and NOT). For example, the recipients could be all users who have either received message A OR clicked a URL in message B.
| Recipients | Data to prepare |
|---|---|
| All users who have added your LINE Official Account as a friend | Nothing |
| Users who can be identified by a user ID or Identifier for Advertisers (IFA) | |
| Users who have clicked a URL in a message you sent them before | Create message click audience |
| Users who have opened a message you sent them before | Create message impression audience |
| Users who received a narrowcast message previously delivered | Specify the request ID of the narrowcast message delivered previously in the redelivery object of the recipient object |
| Users with specific tags in a chat | Create a chat tag audience with LINE Official Account Manager (opens new window) |
| Users who have added a LINE Official Account as a friend through a specific path | Create friend path audiences in LINE Official Account Manager (opens new window) |
| Users who have reserved a visit before | Create reservation audiences in LINE Official Account Manager (opens new window) |
| Users who have viewed a rich menu | Create rich menu impression audiences in LINE Official Account Manager (opens new window) |
| Users who have clicked on a rich menu button | Create rich menu click audiences in LINE Official Account Manager (opens new window) |
| Users narrowed down using LINE Tag tracking information | Create web traffic audience in LINE Official Account Manager (opens new window) |
| Users who viewed a video you sent previously | Create video view audience in LINE Ad Manager (opens new window) |
| Users who participated in certain events within the app (such as opening the app or making a purchase within the app) | Create app event audience in LINE Ad Manager (opens new window) |
| Users who clicked the image you sent previously | Create image click audience in LINE Ad Manager (opens new window) |
You can't create the following types of audiences with the Messaging API:
- Chat tag audience
- Friend path audience
- Reservation audience
- Rich menu impression audience
- Rich menu click audience
- Web traffic audience
- App event audience
- Video view audience
- Image click audience
If you have created an audience, follow the instructions below to confirm that it's ready to accept messages.
# Confirming that an audience is ready to accept messages
Audiences are created asynchronously in the background. Confirm that an audience's status has changed to READY (ready to accept messages) before you start sending it narrowcast messages.
You can check an audience's status via the following API endpoint.
curl -v -X GET https://api.line.me/v2/bot/audienceGroup/{audienceGroupId} \
-H 'Authorization: Bearer {channel access token}'
Once the status property in the response has changed to READY (ready to accept messages), you may begin sending narrowcast messages with that audience given as the recipient.
Learn more about checking an audience's status from Get audience data in the Messaging API Reference.
# Beginning to send narrowcast messages
By combining these objects in a narrowcast message, you can specify the target of the message based on complex conditions.
For example, you can specify a message target based on complex conditions such as women not aged between 15-20 years old who are included in both audiences.
If you try to send a message that exceeds the maximum number of messages that can be sent, the delivery will fail. Messages can be sent within the maximum number of deliverable messages by specifying the limit.upToRemainingQuota property. For more information on the maximum number of messages that can be delivered, see Messaging API pricing.
When you send a narrowcast message, regardless of the actual number of messages being sent, you may reach the approximate limit for the messages you can reserve for the month. Once you reach the approximate limit, you would have to wait until the narrowcast message delivery is complete, as you can't exceed the limit. If you attempt to send another message in that state, You have reached your monthly limit. will be returned, and the message will fail to send.
For more information, see Note regarding the number of remaining messages to be sent during the current month in the Messaging API reference.
# Recipient object
Once you specify the message to be sent (messages property) and the message target (recipient object), you can begin sending a narrowcast message. If you omit the recipient object, all users who added the LINE Official Account as a friend will be the target of the message.
Specify either the audience object or the redelivery object in the recipient object.
# Audience object
Set the audience ID to the audienceGroupId property to specify the target of the message.
To create an audience, use the managing audiences API.
Example recipient object representing an audience
{
"type": "audience",
"audienceGroupId": 5614991017776
}
# Redelivery object
By setting the request ID (X-Line-Request-Id) obtained when the narrowcast message was delivered to the requestId property, you can specify the users who received the narrowcast message as the target.
If errorCode with the "An error occurred because there weren't enough recipients." error message is returned when sending a message with the request ID of a previously sent message specified in a redelivery object, these may be the causes.
- The number of recipients is reduced because some of the recipients have blocked the LINE Official Account after sending the last message.
- The number of recipients is reduced by combining other audience objects or demographic filter objects using an AND or NOT operator of the Operator object.
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 Restrictions on sending messages using attributes and audiences in the Messaging API reference.
Example of a recipient object representing a redelivery object
{
"type": "redelivery",
"requestId": "5b59509c-c57b-11e9-aa8c-2a2ae2dbcce4"
}
For more information on the audience object and redelivery object, see Recipient object in the Messaging API reference.
# Demographic filter object
By specifying the demographic filter object (filter.demographic property), you can distribute a message segmentally based on the attributes (gender, age, type of OS, region) of your friends.
Example demographic filter object for gender
{
"type": "gender",
"oneOf": ["male", "female"]
}
For more information on the demographic filter object, see Demographic filter object in the Messaging API reference.
# Operator object
By using the product set (AND), the union set (OR) and the difference set (NOT) of operator objects, multiple conditions of the recipient object and the demographic filter object can be combined to specify the target.
By using each operator object (AND, OR, NOT), multiple targets can be combined as follows:
Example of a recipient object that combines conditions with operator objects
"recipient": {
"type": "operator",
"and": [
{
"type": "audience",
"audienceGroupId": 5614991017776
},
{
"type": "operator",
"not": {
"type": "redelivery",
"requestId": "5b59509c-c57b-11e9-aa8c-2a2ae2dbcce4"
}
}
]
}
Using operator objects, you can specify the recipient objects and the demographic filter objects to be sent in a nested structure. Operator objects are applied in order from the deepest level of nesting.
In the following example, the target recipient is interpreted as "users who fit A, B, and E, excluding users who are C and D (AudienceA AND AudienceB AND NOT (AudienceC AND Audience D) AND Audience E)".
{
"type": "operator",
"and": [
{
"type": "audience",
"audienceGroupId": AudienceA
},
{
"type": "audience",
"audienceGroupId": AudienceB
},
{
"type": "operator",
"not": {
"type": "operator",
"and": [
{
"type": "audience",
"audienceGroupId": AudienceC
},
{
"type": "audience",
"audienceGroupId": AudienceD
},
]
}
},
{
"type": "audience",
"audienceGroupId": AudienceE
},
]
}
# Example of a narrowcast message request
The following is an example of a request to send a narrowcast message with the following conditions:
- User of an audience (Audience ID:
5614991017776) - Exclude users who received a narrowcast message previously delivered (Request ID:
5b59509c-c57b-11e9-aa8c-2a2ae2dbcce4) - Men and women aged between 20-25
- Residents of Akita or Aichi prefecture
- Have been a friend of the Official Account for between 7-30 days
- Women aged between 35-40 (Exclude men)
curl -v -X POST https://api.line.me/v2/bot/message/narrowcast \
-H 'Authorization: Bearer {channel access token}' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"type": "text",
"text": "test message"
}
],
"recipient": {
"type": "operator",
"and": [
{
"type": "audience",
"audienceGroupId": 5614991017776
},
{
"type": "operator",
"not": {
"type": "redelivery",
"requestId": "5b59509c-c57b-11e9-aa8c-2a2ae2dbcce4"
}
}
]
},
"filter": {
"demographic": {
"type": "operator",
"or": [
{
"type": "operator",
"and": [
{
"type": "gender",
"oneOf": [
"male",
"female"
]
},
{
"type": "age",
"gte": "age_20",
"lt": "age_25"
},
{
"type": "appType",
"oneOf": [
"android",
"ios"
]
},
{
"type": "area",
"oneOf": [
"jp_23",
"jp_05"
]
},
{
"type": "subscriptionPeriod",
"gte": "day_7",
"lt": "day_30"
}
]
},
{
"type": "operator",
"and": [
{
"type": "age",
"gte": "age_35",
"lt": "age_40"
},
{
"type": "operator",
"not": {
"type": "gender",
"oneOf": [
"male"
]
}
}
]
}
]
}
},
"limit": {
"max": 100,
"upToRemainingQuota": true
}
}'
Learn more from Sending narrowcast messages in the Messaging API Reference.
# Checking the status of a narrowcast message
Narrowcast messages are sent asynchronously in the background. We offer an API endpoint that allows you to check if a narrowcast message was successfully sent.
curl -v -X GET 'https://api.line.me/v2/bot/message/progress/narrowcast?requestId={request_id}' \
-H 'Authorization: Bearer {channel access token}'
Learn more from Get narrowcast message status in the Messaging API Reference.
# Send quote messages
You can send messages that quote past messages using the Messaging API.
To send a message quoting a past message, specify the quote token (quoteToken) of the message to be quoted. For more information about how to retrieve quote tokens, see Get quote tokens.
Example of a push message request quoting a past message
curl -v -X POST https://api.line.me/v2/bot/message/push \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {channel access token}' \
-d '{
"to": "U4af4980629...",
"messages": [
{
"type": "text",
"text": "Yes, you can.",
"quoteToken": "yHAz4Ua2wx7..." // Specify the quote token of the message to be quoted
}
]
}'
Note that if the sending of the message to be quoted has been cancelled, or if the past chat history has been deleted from the device, the quoted message won't be displayed.
You can only use quote tokens to send messages with the following endpoints:
Also, when sending a message using a quote token, you can only use the following message objects: