insight.yml

---
openapi: 3.0.0
info:
  title: LINE Messaging API(Insight)
  version: "0.0.1"
  description:
    This document describes LINE Messaging API(Insight).

servers:
  - url: "https://api.line.me"

security:
  - Bearer: []

tags:
  - name: insight

paths:
  "/v2/bot/insight/demographic":
    get:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
      tags:
        - insight
      operationId: getFriendsDemographics
      description: |+
        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).
      responses:
        "200":
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/GetFriendsDemographicsResponse"
              example:
                available: true
                genders:
                  - gender: unknown
                    percentage: 37.6
                  - gender: male
                    percentage: 31.8
                  - gender: female
                    percentage: 30.6
                ages:
                  - age: unknown
                    percentage: 37.6
                  - age: from50
                    percentage: 17.3
                areas:
                  - area: unknown
                    percentage: 42.9
                  - area: 徳島
                    percentage: 2.9
                appTypes:
                  - appType: ios
                    percentage: 62.4
                  - appType: android
                    percentage: 27.7
                  - appType: others
                    percentage: 9.9
                subscriptionPeriods:
                  - subscriptionPeriod: over365days
                    percentage: 96.4
                  - subscriptionPeriod: within365days
                    percentage: 1.9
                  - subscriptionPeriod: within180days
                    percentage: 1.2
                  - subscriptionPeriod: within90days
                    percentage: 0.5
                  - subscriptionPeriod: within30days
                    percentage: 0.1
                  - subscriptionPeriod: within7days
                    percentage: 0
          description: "OK"

  "/v2/bot/insight/message/delivery":
    get:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-delivery-messages
      tags:
        - insight
      operationId: getNumberOfMessageDeliveries
      description: |+
        Returns the number of messages sent from LINE Official Account
        on a specified day.
      parameters:
        - in: query
          name: date
          description: |+
            Date for which to retrieve number of sent messages.
            - Format: yyyyMMdd (e.g. 20191231)
            - Timezone: UTC+9
          required: true
          schema:
            type: string
            pattern: "^[0-9]{8}$"
            minLength: 8
            maxLength: 8
      responses:
        "200":
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/GetNumberOfMessageDeliveriesResponse"
              example:
                status: ready
                broadcast: 5385
                targeting: 522
          description: "OK"
      summary: "Get number of message deliveries"

  "/v2/bot/insight/followers":
    get:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-followers
      tags:
        - insight
      summary: "Get number of followers"
      description: |+
        Returns the number of users who have added the LINE Official Account
        on or before a specified date.
      operationId: getNumberOfFollowers
      parameters:
        - in: query
          name: date
          required: false
          description: |+
            Date for which to retrieve the number of followers.

            Format: yyyyMMdd (e.g. 20191231)
            Timezone: UTC+9
          schema:
            type: string
            pattern: "^[0-9]{8}$"
            maxLength: 8
            minLength: 8
      responses:
        "200":
          description: "OK"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/GetNumberOfFollowersResponse"
              example:
                status: ready
                followers: 7620
                targetedReaches: 5848
                blocks: 237

  "/v2/bot/insight/message/event":
    get:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-message-event
      tags:
        - insight
      description: |+
        Returns statistics about how users interact with narrowcast messages
        or broadcast messages sent from your LINE Official Account.
      summary: "Get user interaction statistics"
      operationId: getMessageEvent
      parameters:
        - in: query
          name: requestId
          required: true
          description: |+
            Request ID of a narrowcast message or broadcast message.
            Each Messaging API request has a request ID.
          schema:
            # TODO maxLength and/or pattern is required for x-line-request-id
            type: string
            minLength: 1
      responses:
        "200":
          description: "OK"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/GetMessageEventResponse"
              example:
                overview:
                  requestId: f70dd685-499a-4231-a441-f24b8d4fba21
                  timestamp: 1568214000
                  delivered: 320
                  uniqueImpression: 82
                  uniqueClick: 51
                  uniqueMediaPlayed:
                  uniqueMediaPlayed100Percent:
                messages:
                  - seq: 1
                    impression: 136
                    mediaPlayed:
                    mediaPlayed25Percent:
                    mediaPlayed50Percent:
                    mediaPlayed75Percent:
                    mediaPlayed100Percent:
                    uniqueMediaPlayed:
                    uniqueMediaPlayed25Percent:
                    uniqueMediaPlayed50Percent:
                    uniqueMediaPlayed75Percent:
                    uniqueMediaPlayed100Percent:
                clicks:
                  - seq: 1
                    url: https://line.me/
                    click: 41
                    uniqueClick: 30
                    uniqueClickOfRequest: 30
                  - seq: 1
                    url: https://www.linebiz.com/
                    click: 59
                    uniqueClick: 38
                    uniqueClickOfRequest: 38

  "/v2/bot/insight/message/event/aggregation":
    get:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit
      tags:
        - insight
      description: |+
        You can check the per-unit statistics of how users interact with
        push messages and multicast messages sent from your LINE Official Account.
      operationId: getStatisticsPerUnit
      parameters:
        - in: query
          name: customAggregationUnit
          required: true
          description: |+
            Name of aggregation unit specified when sending the message. Case-sensitive.
            For example, `Promotion_a` and `Promotion_A` are regarded as different unit names.
          schema:
            # https://developers.line.biz/en/reference/messaging-api/#send-push-message-request-body
            type: string
            pattern: "^[a-zA-Z0-9_]{1,30}$"
            minLength: 1
            maxLength: 30
        - in: query
          name: from
          required: true
          description: |+
            Start date of aggregation period.

            Format: yyyyMMdd (e.g. 20210301)
            Time zone: UTC+9
          schema:
            type: string
            pattern: "^[0-9]{8}$"
            example: "20210301"
            minLength: 8
            maxLength: 8
        - in: query
          name: to
          required: true
          description: |+
            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
          schema:
            type: string
            pattern: "^[0-9]{8}$"
            example: "20210301"
            minLength: 8
            maxLength: 8
      responses:
        "200":
          description: "OK"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/GetStatisticsPerUnitResponse"
              example:
                overview:
                  uniqueImpression: 40
                  uniqueClick: 30
                  uniqueMediaPlayed: 25
                  uniqueMediaPlayed100Percent: ~
                messages:
                  - seq: 1
                    impression: 42
                    mediaPlayed: 30
                    mediaPlayed25Percent: ~
                    mediaPlayed50Percent: ~
                    mediaPlayed75Percent: ~
                    mediaPlayed100Percent: ~
                    uniqueMediaPlayed: 25
                    uniqueMediaPlayed25Percent: ~
                    uniqueMediaPlayed50Percent: ~
                    uniqueMediaPlayed75Percent: ~
                    uniqueMediaPlayed100Percent: ~
                clicks:
                  - seq: 1
                    url: https://developers.line.biz/
                    click: 35
                    uniqueClick: 25
                    uniqueClickOfRequest: ~
                  - seq: 1
                    url: https://www.line-community.me/
                    click: 29
                    uniqueClick: ~
                    uniqueClickOfRequest: ~

components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: "Channel access token"

  schemas:
    GetFriendsDemographicsResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
      description: "Get friend demographics"
      type: object
      properties:
        available:
          type: boolean
          description: "true if friend demographic information is available."
        genders:
          type: array
          items:
            $ref: "#/components/schemas/GenderTile"
          description: "Percentage per gender."
        ages:
          type: array
          items:
            $ref: "#/components/schemas/AgeTile"
          description: "Percentage per age group."
        areas:
          type: array
          items:
            $ref: "#/components/schemas/AreaTile"
          description: "Percentage per area."
        appTypes:
          type: array
          items:
            $ref: "#/components/schemas/AppTypeTile"
          description: "Percentage by OS."
        subscriptionPeriods:
          items:
            $ref: "#/components/schemas/SubscriptionPeriodTile"
          type: array
          description: "Percentage per friendship duration."
    GenderTile:
      type: object
      properties:
        gender:
          type: string
          enum:
            - male
            - female
            - unknown
          description: "users' gender"
        percentage:
          type: number
          format: double
          description: "Percentage"
    AgeTile:
      type: object
      properties:
        age:
          type: string
          enum:
            - from0to14
            - from15to19
            - from20to24
            - from25to29
            - from30to34
            - from35to39
            - from40to44
            - from45to49
            - from50
            - from50to54
            - from55to59
            - from60to64
            - from65to69
            - from70
            - unknown
          description: "users' age"
        percentage:
          type: number
          format: double
          description: "Percentage"
    AreaTile:
      type: object
      properties:
        area:
          type: string
          description: "users' country and region"
        percentage:
          type: number
          format: double
          description: "Percentage"
    AppTypeTile:
      properties:
        appType:
          type: string
          enum:
            - ios
            - android
            - others
          description: "users' OS"
        percentage:
          format: double
          type: number
          description: "Percentage"
      type: object
    SubscriptionPeriodTile:
      properties:
        subscriptionPeriod:
          type: string
          description: "Subscription period. Possible values: `within7days`, `within90days`, `unknown` etc."
          enum:
            # Less than 7 days
            - within7days
            # Equal to or greater than 7 days but less than 30 days
            - within30days
            # Equal to or greater than 30 days but less than 90 days
            - within90days
            # Equal to or greater than 90 days but less than 180 days
            - within180days
            # Equal to or greater than 180 days but less than 365 days
            - within365days
            # Equal to or greater than 365 days
            - over365days
            # Unknown
            - unknown
        percentage:
          format: double
          type: number
          description: "Percentage. Possible values: [0.0,100.0] e.g. 0, 2.9, 37.6."
      type: object

    GetNumberOfMessageDeliveriesResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-delivery-messages
      description: "Get number of message deliveries"
      type: object
      properties:
        status:
          type: string
          enum:
            - ready
            - unready
            - out_of_service
          description: "Status of the counting process."
        broadcast:
          format: int64
          type: integer
          description: "Number of messages sent to all of this LINE Official Account's friends (broadcast messages)."
        targeting:
          format: int64
          type: integer
          description: "Number of messages sent to some of this LINE Official Account's friends, based on specific attributes (targeted messages)."
        autoResponse:
          format: int64
          type: integer
          description: "Number of auto-response messages sent."
        welcomeResponse:
          format: int64
          type: integer
          description: "Number of greeting messages sent."
        chat:
          format: int64
          type: integer
          description: "Number of messages sent from LINE Official Account Manager [Chat screen](https://www.linebiz.com/jp/manual/OfficialAccountManager/chats/) (only available in Japanese)."
        apiBroadcast:
          format: int64
          type: integer
          description: "Number of broadcast messages sent with the `Send broadcast message` Messaging API operation."
        apiPush:
          format: int64
          type: integer
          description: "Number of push messages sent with the `Send push message` Messaging API operation."
        apiMulticast:
          format: int64
          type: integer
          description: "Number of multicast messages sent with the `Send multicast message` Messaging API operation."
        apiNarrowcast:
          format: int64
          type: integer
          description: "Number of narrowcast messages sent with the `Send narrowcast message` Messaging API operation."
        apiReply:
          format: int64
          type: integer
          description: "Number of replies sent with the `Send reply message` Messaging API operation."


    GetNumberOfFollowersResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-followers
      description: "Get number of followers"
      type: object
      properties:
        status:
          description: "Calculation status."
          type: string
          enum:
            - ready
            - unready
            - out_of_service
        followers:
          type: integer
          format: int64
          description: |+
            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:
          format: int64
          type: integer
          description: |+
            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:
          type: integer
          format: int64
          description: |+
            The number of users blocking the account as of the specified date.
            The number decreases when a user unblocks the account.


    GetMessageEventResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-insight-message-event-response
      description: "Statistics about how users interact with narrowcast messages or broadcast messages sent from your LINE Official Account."
      properties:
        overview:
          $ref: "#/components/schemas/GetMessageEventResponseOverview"
        messages:
          description: "Array of information about individual message bubbles."
          type: array
          items:
            $ref: "#/components/schemas/GetMessageEventResponseMessage"
        clicks:
          description: "Array of information about opened URLs in the message."
          type: array
          items:
            $ref: "#/components/schemas/GetMessageEventResponseClick"
      type: object
    GetMessageEventResponseOverview:
      description: "Summary of message statistics."
      type: object
      properties:
        requestId:
          type: string
          description: "Request ID."
        timestamp:
          format: int64
          type: integer
          description: "UNIX timestamp for message delivery time in seconds."
        delivered:
          format: int64
          type: integer
          description: |+
            Number of messages delivered.
            This property shows values of less than 20.
            However, if all messages have not been sent, it will be null.
        uniqueImpression:
          format: int64
          type: integer
          description: "Number of users who opened the message, meaning they displayed at least 1 bubble."
          nullable: true
        uniqueClick:
          format: int64
          type: integer
          description: "Number of users who opened any URL in the message."
          nullable: true
        uniqueMediaPlayed:
          format: int64
          type: integer
          description: "Number of users who started playing any video or audio in the message."
          nullable: true
        uniqueMediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of users who played the entirety of any video or audio in the message."
          nullable: true
    GetMessageEventResponseMessage:
      type: object
      properties:
        seq:
          format: int32
          type: integer
          description: "Bubble's serial number."
        impression:
          format: int64
          type: integer
          description: "Number of times the bubble was displayed."
          nullable: true
        mediaPlayed:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing."
          nullable: true
        mediaPlayed25Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 25% of the total time."
          nullable: true
        mediaPlayed50Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 50% of the total time."
          nullable: true
        mediaPlayed75Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 75% of the total time."
          nullable: true
        mediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 100% of the total time."
          nullable: true
        uniqueMediaPlayed:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble."
          nullable: true
        uniqueMediaPlayed25Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 25% of the total time."
          nullable: true
        uniqueMediaPlayed50Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 50% of the total time."
          nullable: true
        uniqueMediaPlayed75Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 75% of the total time."
          nullable: true
        uniqueMediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 100% of the total time."
          nullable: true
    GetMessageEventResponseClick:
      type: object
      properties:
        seq:
          type: integer
          format: int32
          description: "The URL's serial number."
        url:
          type: string
          description: "URL."
        click:
          type: integer
          format: int64
          description: "Number of times the URL was opened."
          nullable: true
        uniqueClick:
          type: integer
          format: int64
          description: "Number of users that opened the URL."
          nullable: true
        uniqueClickOfRequest:
          type: integer
          format: int64
          description: "Number of users 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."
          nullable: true


    GetStatisticsPerUnitResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit-response
      description: "Response object for `get statistics per unit`"
      type: object
      properties:
        overview:
          $ref: "#/components/schemas/GetStatisticsPerUnitResponseOverview"
        messages:
          description: "Array of information about individual message bubbles."
          type: array
          items:
            $ref: "#/components/schemas/GetStatisticsPerUnitResponseMessage"
        clicks:
          description: "Array of information about opened URLs in the message."
          type: array
          items:
            $ref: "#/components/schemas/GetStatisticsPerUnitResponseClick"
      required:
        - clicks
        - messages
        - overview
    GetStatisticsPerUnitResponseOverview:
      description: "Statistics related to messages."
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit-response
      type: object
      properties:
        uniqueImpression:
          format: int64
          type: integer
          description: "Number of users who opened the message, meaning they displayed at least 1 bubble."
          nullable: true
        uniqueClick:
          format: int64
          type: integer
          description: "Number of users who opened any URL in the message."
          nullable: true
        uniqueMediaPlayed:
          format: int64
          type: integer
          description: "Number of users who started playing any video or audio in the message."
          nullable: true
        uniqueMediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of users who played the entirety of any video or audio in the message."
          nullable: true
    GetStatisticsPerUnitResponseMessage:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit-response
      required:
        - seq
      type: object
      properties:
        seq:
          format: int32
          type: integer
          description: "Bubble's serial number."
        impression:
          format: int64
          type: integer
          description: "Number of times the bubble was displayed."
          nullable: true
        mediaPlayed:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing."
          nullable: true
        mediaPlayed25Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 25% of the total time."
          nullable: true
        mediaPlayed50Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 50% of the total time."
          nullable: true
        mediaPlayed75Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 75% of the total time."
          nullable: true
        mediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of times audio or video in the bubble started playing and was played 100% of the total time."
          nullable: true
        uniqueImpression:
          format: int64
          type: integer
          description: "Number of users the bubble was displayed."
          nullable: true
        uniqueMediaPlayed:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble."
          nullable: true
        uniqueMediaPlayed25Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 25% of the total time."
          nullable: true
        uniqueMediaPlayed50Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 50% of the total time."
          nullable: true
        uniqueMediaPlayed75Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 75% of the total time."
          nullable: true
        uniqueMediaPlayed100Percent:
          format: int64
          type: integer
          description: "Number of users that started playing audio or video in the bubble and played 100% of the total time."
          nullable: true
    GetStatisticsPerUnitResponseClick:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit-response
      type: object
      properties:
        seq:
          format: int64
          type: integer
          description: "The URL's serial number."
        url:
          type: string
          description: "URL."
        click:
          format: int64
          type: integer
          description: "Number of times the URL in the bubble was opened."
          nullable: true
        uniqueClick:
          format: int64
          type: integer
          description: "Number of users that opened the URL in the bubble."
          nullable: true
        uniqueClickOfRequest:
          format: int64
          type: integer
          description: |+
            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.
          nullable: true
      required:
        - seq
        - url

    ErrorResponse:
      externalDocs:
        url: https://developers.line.biz/en/reference/messaging-api/#error-responses
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: "Message containing information about the error."
        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"
          description: "An array of error details. If the array is empty, this property will not be included in the response."
    ErrorDetail:
      type: object
      properties:
        message:
          type: string
          description: "Details of the error. Not included in the response under certain situations."
        property:
          type: string
          description: "Location of where the error occurred. Returns the JSON field name or query parameter name of the request. Not included in the response under certain situations."