# Sending messages

You can create bots to send various types of messages to users via two main messaging methods: reply messages and push messages.

dummy dummy
Messaging method
  • Replies (a.k.a. "reply messages")
  • Push messages
    • Push messages (one-to-one)
    • Multicast messages (one-to-many, targeting a list of user IDs)
    • Narrowcast messages (one-to-many, targeting a segmented list)
    • Broadcast messages (one-to-many, targeting all friends)
Message types
  • Text message
  • Sticker message
  • Image message
  • Video message
  • Audio message
  • Location message
  • Imagemap message
  • Template message
  • Flex message
For more information on the types of messages you can send using the Messaging API, see Message types.

# Messaging methods

The Messaging API provides two main messaging methods for you to use: replies (a.k.a. "reply messages") and push messages.

# Reply messages

Reply messages are sent in response to user actions, such as adding your LINE Official Account as a friend or sending it 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.

# Push messages

Push messages are messages that you can send to users at any time. Send these messages by one of the following methods:

Message method Recipient(s)
Push messages Sent to a single user
Multicast messages Sent to multiple users
Narrowcast messages Sent to multiple users via attribute data or retargeting
Broadcast messages Sent to all friends of your LINE Official Account

Unlike reply messages, push messages do not require a reply token. You can send up to 5 message objects in a single request.

Sample request for multicast message

curl -v -X POST https://api.line.me/v2/bot/message/multicast \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {channel access token}' \
-d '{
    "to": ["U4af4980629...","U0c229f96c4..."],
    "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 push 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 groups or rooms.

Follow these steps to send narrowcast messages:

  1. Prepare a list of recipients
  2. Begin sending narrowcast messages
  3. Check the status of the narrowcast messages
Messages are sent asynchronously

Narrowcast messages are sent asynchronously in the background. The API call to send the messages always succeeds, but 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 additional path audiences in LINE Official Account Manager (opens new window)
Note

You can't create a chat tag audience and a friend path audience with the Messaging API.

If you have created an audience, follow the instructions below to confirm that it is 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.

narrowcast message

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.

Maximum number of narrowcast messages to be delivered

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.

To get the approximate monthly limit, use the Get the target limit for additional messages endpoint.

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

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

Conditions for specifying the request ID

The request ID specified in the requestId property must satisfy all of these conditions:

  • The request ID was issued by the delivering a narrowcast message
  • The narrowcast message was delivered within the past seven days
  • The delivery process is completed (The value of the phase property is succeeded in the response of the Get narrowcast message status endpoint)
On the "there weren't enough recipients" error message

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 are reduced because some of the recipients have blocked the LINE Official Account after sending the last message.
  • The number of recipients are 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 "Usage restrictions of narrowcast messages" in Send narrowcast message.

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.

Using attribute data
  • 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:

operator object

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"
            }
        }
    ]
}

# 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, please take note of the following:

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