English

# Option API reference for corporate customers

Use of optional functions requires an application

The functions described in this document can only be used by corporate users who have submitted the required applications. To use it with your LINE Official Account, contact your sales representative or contact our Sales partners (opens new window).

# Common specifications

# Status code

For more information, see Status codes in the Messaging API reference.

# Mission stickers API

Mission stickers are provided to user upon completion of certain objectives. Using stickers as an incentive, users are encouraged to "link ID information", "register as a member", or "answer a questionnaire".

# Send mission stickers (v3)

Sends a mission sticker.

Tip

Unlike "Send mission stickers (v2)", it is not necessary to register the IP or network address of the server that connects this endpoint in the LINE Developers Console.

Example request

    # HTTP request

    POST https://api.line.me/shop/v3/mission

    # Request headers

    Content-Type

    Required

    application/json

    Authorization

    Required

    Bearer {channel access token}

    # Request body

    to

    String

    Required

    Destination user ID

    productType

    String

    Required

    STICKER

    productId

    String

    Required

    Package ID for a set of stickers

    sendPresentMessage

    Boolean

    Required

    false

    # Response

    Returns status code 200 and an empty response body.

    # Error response

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

    message

    String

    Message containing error information. For more information, see Error messages.

    # Error messages

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

    Message Description
    invalid request The destination user ID specified for to is invalid.
    not found The package ID specified for productId is invalid.
    internal error The package ID specified for productId is invalid.
    not allowed to use the API The channel is not granted the required permission for the mission sticker API.
    not_sales_period The date and time when the sticker set was sent is not within the valid period of the sticker set.
    not sale for country The sticker set specified for productId isn't available for purchase in the country of the destination user specified for to.
    not sale for device The device of the destination user specified for to doesn't support the sticker set specified for productId.
    not sale for version The LINE app used by the destination user specified for to doesn't support the sticker set specified for productId.

    # Send mission stickers (v2)

    Sends a push mission sticker to a user at any time.

    Note

    It is necessary to register the IP or network address of the server that connects this endpoint in the LINE Developers Console. Add the server IP address or network address to the [Security Management] tab of the target channel.

    Example request

      # HTTP request

      POST https://api.line.me/v2/missionSticker/send

      # Request headers

      Content-Type

      Required

      application/json

      X-Line-ChannelId

      Required

      Channel ID. You can check this property in the LINE Developers Console.

      X-Line-ChannelSecret

      Required

      Channel secret. You can check this property in the LINE Developers Console.

      X-Line-Trusted-User-With-ACL

      Required

      Value assigned when the permission to use the Mission Stickers API is granted. For more information, contact your LINE representative.

      # Request body

      to

      String

      Required

      Destination user ID

      messages

      Array

      Required

      An array that has an object that includes the packageId and isPresent properties. Only one object can be specified.

      messages[].packageId

      String

      Required

      Package ID for a set of stickers

      messages[].isPresent

      Boolean

      Required

      false

      # Response

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

      ticketId

      String

      Value used inside LINE.
      Returns ticketId if the API call is successful.

      Example response

        # Error response

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

        message

        String

        Message containing error information. For more information, see Error messages.

        # Error messages

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

        Message Description
        authentication failed This message is returned in either or both cases below:
        • Any of the X-Line-ChannelId, X-Line-ChannelSecret, or X-Line-Trusted-User-With-ACL headers are incorrect.
        • The server that connects this endpoint is not registered on the "Security settings" tab in the LINE Developers Console.
        CHANNEL_MISSION_STICKER_NOT_USABLE The channel is not granted the required permission for the mission sticker feature.

        # Audience Match API

        # Rate limits

        The limits on API requests for the Audience Match API are the same as the Rate limits for the Messaging API.

        # Message types

        All message types of Messaging API can be used.

        Unavailable actions

        Actions other than URI actions can't be set for the following message types:

        If an action other than the URI action is set, no message will be sent. Also, no other messages in the same request are sent.

        # Unsupported features

        These properties and request headers aren't available for the Audience Match API:

        # Send a message using phone number

        Serves targeting delivery based on the user's phone number.

        Example request

          # HTTP request

          POST https://api.line.me/bot/ad/multicast/phone

          # Request headers

          Content-Type

          Required

          application/json

          Authorization

          Required

          Bearer {channel access token}

          # Request body

          to

          Array of hashed phone numbers

          Required

          Destination of the message (A value obtained by hashing the telephone number, which is another value normalized to E.164 format, with SHA256).
          Max message limit: 150

          messages

          array of message objects

          Required

          Message to send.
          Max message limit: 5

          notificationDisabled

          Boolean

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

          The default value is false.

          # Response

          Returns status code 200 and an empty JSON object.

          Example response

            # Get result of message delivery using phone number

            Gets the delivery result of the message delivered in "Send message using phone number".

            Example request

              # HTTP request

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

              # Request headers

              Content-Type

              Required

              application/json

              Authorization

              Required

              Bearer {channel access token}

              # Query parameters

              date

              Required

              Date the message was sent

              • Format: yyyyMMdd (e.g. 20190831)
              • Time Zone: UTC+9

              # Response

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

              status

              String

              Aggregation process status. One of:

              • ready: The number of messages can be obtained.
              • unready: We haven't finished calculating the number of sent messages for the specified in date. For example, this property is returned when the delivery date or a future date is specified. Calculation usually takes about a day.
              • unavailable_for_privacy: The total number of messages on the specified day is less than 20.
              • out_of_service: The specified date is earlier than the date on which we first started calculating sent messages (March 31, 2018).

              success

              Long

              The number of messages delivered using the phone number on the date specified in date. The response has this property only when the value of status is ready.

                # Mark-as-Read

                # Mark messages from users as read

                All messages sent from a specific user can display "Read" at any time.

                Example request

                  # HTTP request

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

                  # Request headers

                  Content-Type

                  Required

                  application/json

                  Authorization

                  Required

                  Bearer {channel access token}

                  # Request body

                  chat.userId

                  String

                  Required

                  The target user ID

                  # Response

                  Returns status code 200 and an empty JSON object.

                  Example response

                    # Get statistics per aggregation unit

                    Enables aggregation of statistics when sending push messages or multicast messages with the same content to multiple end users. "Unit" refers to the aggregation unit. There is no procedure to creating a unit. You can view statistics on a per-unit basis, simply by specifying any unit name when sending the message.

                    # Assign a unit name to any aggregation unit when sending messages

                    When sending push messages or multicast messages, assign names to aggregation units. For information on sending push messages or multicast messages, see Message under the Messaging API Reference.

                    On assigning unit names later or changing unit names

                    Once you send a message, you can't retroactively assign unit names or change them.

                    When assigning unit names, make the contents of the message bubble consistent

                    If you send messages with the same unit name, the statistics are aggregated together, regardless of message contents, or the number and order of message bubbles. When sending multiple messages with the same unit name, make sure the contents of the message bubbles are consistent.

                    # Request body

                    You can specify the property, customAggregationUnits, to the following endpoint request bodies.

                    customAggregationUnits

                    Array of string

                    Optional

                    Name of aggregation unit. Case-sensitive. For example, Promotion_a and Promotion_A are regarded as different unit names.

                    • Maximum unit number: 1
                    • Maximum length: 30 characters
                    • Supported character types: Half-width alphanumeric characters (a-z, A-Z, 0-9) and underscore (_)

                    Example request

                      # Get statistics per unit

                      You can check the per-unit statistics of how users interact with push messages and multicast messages sent from your LINE Official Account.

                      In addition, statistics can be obtained on a per-message and per-message bubble basis.

                      message and bubbles

                      On the recorded statistics recorded

                      Interactions are updated for only 14 days (1,209,600 seconds) from the time a message was sent. After that time, interactions aren't updated.

                      For example, if you send a message at 15:00 on February 1, 2021, interactions will be updated until 15:00 on February 15, 2021.

                      To obtain statistics per message

                      To obtain statistics per narrowcast message or broadcast message, use the following endpoint.

                      Example request

                        # HTTP request

                        GET https://api.line.me/v2/bot/insight/message/event/aggregation?customAggregationUnit={customAggregationUnit}&from={from}&to={to}

                        # Request headers

                        Authorization

                        Required

                        Bearer {channel access token}

                        # Query parameters

                        customAggregationUnit

                        String

                        Required

                        Name of aggregation unit specified when sending the message. Case-sensitive. For example, Promotion_a and Promotion_A are regarded as different unit names.

                        from

                        String

                        Required

                        Start date of aggregation period.

                        • Format: yyyyMMdd (e.g. 20210301)
                        • Time zone: UTC+9

                        to

                        String

                        Required

                        End date of aggregation period. The end date can be specified for up to 30 days later. For example, if the start date is 20210301, the latest end date is 20210331.

                        • Format: yyyyMMdd (e.g. 20210301)
                        • Time zone: UTC+9

                        # Response

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

                        Note

                        The statistical data may contain some errors.

                        To protect users' privacy, the values of some properties related to user interactions will be displayed as null in the following cases:

                        • The property value is 20 or lower
                        • Even if the property value is higher than 20, the actual number of users who generated the event is less than 20 (for example, if messages[].mediaPlayed is 30, but messages[].uniqueMediaPlayed is 15, both will be displayed as null

                        overview

                        Object

                        Statistics related to messages.

                        overview.uniqueImpression

                        Number

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

                        overview.uniqueClick

                        Number

                        Number of users who opened any URL in the message.

                        overview.uniqueMediaPlayed

                        Number

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

                        overview.uniqueMediaPlayed100Percent

                        Number

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

                        messages[].uniqueMediaPlayed25Percent

                        Number

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

                        messages[].uniqueMediaPlayed50Percent

                        Number

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

                        messages[].uniqueMediaPlayed75Percent

                        Number

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

                        messages[].uniqueMediaPlayed100Percent

                        Number

                        Number of users 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 in the bubble was opened.

                        clicks[].uniqueClick

                        Number

                        Number of users that opened the URL in the bubble.

                        clicks[].uniqueClickOfRequest

                        Number

                        Number of users who opened this url through any link in the message. If another message bubble contains the same URL, and a user opens both links, it's counted only once.

                        Example response

                          # Get number of units used this month

                          Get the number of aggregation units used this month.

                          Limit to the number of units that can be used

                          With the feature for getting statistics per aggregation unit, you can use up to 1,000 different unit names per channel in a given month. Unit numbers get reset on the first day of every month and are counted from 1 again. If you assign the 1,001st unit name within a given month, you can still send a message, but the new unit name will not take effect.

                          Example request

                            # HTTP request

                            GET https://api.line.me/v2/bot/message/aggregation/info

                            # Request headers

                            Authorization

                            Required

                            Bearer {channel access token}

                            # Response

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

                            numOfCustomAggregationUnits

                            Number

                            Number of aggregation units used this month.

                            Example response

                              # Get name list of units used this month

                              You can get the name list of units used this month for statistics aggregation.

                              Example request

                                # HTTP request

                                GET https://api.line.me/v2/bot/message/aggregation/list

                                # Request headers

                                Authorization

                                Required

                                Bearer {channel access token}

                                # Query parameters

                                limit

                                String

                                Optional

                                Maximum number of aggregation units you can get per request. If you don't specify a value, or if you specify a value greater than or equal to 100, the maximum is 100.

                                start

                                String

                                Optional

                                Value of the continuation token found in the next property of the JSON object returned in the response. If you can't get all the aggregation units in one request, include this parameter to get the remaining array.

                                # Response

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

                                customAggregationUnits

                                Array of string

                                Name list of aggregation units used this month.

                                next

                                String

                                A continuation token to get the next array of unit names. Returned only when there are remaining aggregation units that were not returned in customAggregationUnits in the original request.

                                Example response