--- 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://developers.line.biz/ 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."