# 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
Narrowcast messages are sent asynchronously in the background. Even if a request to send a narrowcast message is successful, failures can occur once the messages start to be delivered. You must check the messages' status to determine if they were sent successfully.
# 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 audience for click-based retargeting |
| Users who have opened a message you sent them before | Create audience for impression-based retargeting |
| 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 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 a chat tag audience, friend path audience, reservation audience, web traffic audience, app event audience, video view audience, or image click audience with the Messaging API.
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.
The recipient object can represent a complex set of criteria using logical conjunctions (AND operators), disjunctions (OR operators), and complements (NOT operators).
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 sending narrowcast messages, regardless of the values set to the recipient or filter.demographic properties, the number of messages to be delivered is calculated assuming that the message will be temporarily delivered to all friends. If the number of messages to be delivered exceeds the monthly limit, you can't send a narrowcast message.
However, if the maximum number of messages set in the limit.max property doesn't exceed the monthly limit, you can send a narrowcast message.
By setting the limit.upToRemainingQuota property to true, even if you exceed the limit, you won't receive an error. The number of messages to be delivered will be automatically capped by the limit. However, if there are zero messages that can be delivered, the status code 429 Too Many Requests will be returned.
To get the approximate monthly limit, use the Get the target limit for sending messages this month endpoint.
For more information on how to set the approximate target limit, see Messaging API pricing.
When you send a narrowcast, 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 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. This will occur if the following two conditions are met:
- The number of target reach is greater than the approximate limit for the current month.
- The
limit.maxproperty is not set or set to more than the approximate limit for the current month.
Once the narrowcast delivery is complete, you will no longer be exceeding the approximate limit, so you can resume sending messages.
To prevent delivery failures, set limit.max to a number that doesn't exceed the upper limit when sending a narrowcast. By setting limit.max correctly, you can control the number of messages that are reserved for narrowcast delivery.
This table shows the relationship between the limit.max property settings and limit.upToRemainingQuota property settings, and the number of reservations.
limit.max | limit.upToRemainingQuota | Number of reservation |
|---|---|---|
| Not set | false | number of target reach |
| Any number | false | minimum value from target reach and limit.max |
| Not set | true | minimum value from target reach and estimated upper limit for the current month |
| Any number | true | minimum value from target reach, estimated upper limit for the current month, and limit.max |
# 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.
The request ID specified in the requestId property must satisfy all of these conditions:
- The request ID was issued by the delivering a narrowcast message
- The narrowcast message was delivered within less than the past 14 days (336 hours)
- The delivery process is completed (The value of the
phaseproperty issucceededin the response of the Get narrowcast message status endpoint)
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.
- The attribute data used for demographic filters is always 3 days old.
- If you don't specify any attributes, messages will be sent to everyone—even users with attribute values of "unknown".
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.
# Usage restrictions of narrowcast messages
When using narrowcast messages, take note of the following:
- To use attribute data, your "Target reach" number must be 100 or more.
- Combine audience and attribute data so that the number of recipients is 50 or more. If this criterion isn't met, you can't send narrowcast messages. However, you can send to less than 50 people if:
- You use an audience for uploading the user ID without using attribute data
- You use the chat tag audience
- When sending narrowcast messages, you can use the
recipientproperty to specify up to a combined total of 10 audience objects and redelivery objects. There is no upper limit on the number of operator objects.