# Receiving messages (webhooks)

Every time a user adds your LINE Official Account as a friend or sends it a message, the LINE Platform sends an HTTP POST request with a webhook event object to the webhook URL (bot server) you have specified in the LINE Developers Console.

Make sure that your bot server processes the webhook event objects correctly. Webhook sending may be suspended for bot servers that have been failing to receive webhooks for a long period of time.

Security warning

Your bot server may receive malicious HTTP POST requests that weren't sent from the LINE Platform.

Don't process any webhook event objects until you have verified their signatures.

We recommend processing events asynchronously

We recommend processing events asynchronously, so that processing an HTTP POST request doesn't cause delays in processing subsequent requests.

# Verifying signatures

Have your bot server verify the signature in the x-line-signature request header to confirm that the request was sent from the LINE Platform.

  1. Using the HMAC-SHA256 algorithm with the channel secret as the secret key, compute the digest for the request body.
  2. Confirm that the Base64-encoded digest matches the signature in the x-line-signature request header.

The following is an example of how to implement signature validation in Python®.

import base64
import hashlib
import hmac

channel_secret = '...' # Channel secret string
body = '...' # Request body string
hash = hmac.new(channel_secret.encode('utf-8'),
    body.encode('utf-8'), hashlib.sha256).digest()
signature = base64.b64encode(hash)
# Compare x-line-signature request header and the signature

For more information and code samples, see Signature validation in the Messaging API reference.

# Webhook event types

You can control your bot's behavior and respond to the user based on the data in the webhook event object. For more information, see Webhook event object in the Messaging API reference.

# Webhook events for one-on-one chats or group chats and multi-person chats

In one-on-one chats or group chats and multi-person chats, you will receive these webhook events based on user action.

Event type Description 1-on-1 chats Group chats and multi-person chats
Message event Indicates that the user sent a message. You can reply to this event.
Unsend event Indicates that the user unsent a message.
Follow event Indicates that your LINE Official Account was added as a friend (or unblocked). You can reply to this event.
Unfollow event Indicates that your LINE Official Account was blocked.
Join event Indicates that your LINE Official Account joined a group chat or multi-person chat. You can reply to this event.
Leave event Indicates that the user either deleted your LINE Official Account from the group chat, or the LINE Official Account has left the group chat or multi-person chat.
Member join event Indicates that the user joined a group chat or multi-person chat of which your LINE Official Account is a member. You can reply to this event.
Member leave event Indicates that the user left a group chat or multi-person chat of which your LINE Official Account is a member.
Postback event Indicates that the user performed a postback action. You can reply to this event.
Video viewing complete event Indicates that the user finished watching the video message with the specified trackingId sent from the LINE Official account. You can reply to this event.

✅ : Receive    ❌ : Don't receive

# Webhook events for LINE Things

Some webhook events are unique to LINE Things.

Event type Description
Device link event Indicates that the user linked a device with LINE.
Device unlink event Indicates that the user unlinked a device from LINE.
LINE Things scenario execution event Indicates that an automatic communication scenario has been executed.

# Other webhook events

There are also webhook events that are sent when beacons are in use, or webhook events that are sent when accounts are linked using the Messaging API.

Event type Description
Beacon event Indicates that a user is within the reception range of the Beacon. You can reply to this event. For more information, see Using beacons.
Account link event Indicates that the user linked the LINE account with the service account provided by the provider. You can reply to this event. For more information, see Linking user accounts.

# Redeliver a webhook that failed to be received

The Messaging API provides a feature to redeliver webhooks that fail to be received on the bot server. Even if the bot server fails to respond normally to a webhook due to temporary over-access or other reasons, the webhook will be redelivered from the LINE Platform for a certain period of time, so that the webhook can be received after the bot server has recovered.

Webhook redelivery is available for all Messaging API channels.

Check before enabling webhook redelivery
  • Due to network routing problems and other factors, duplicate webhook events may be sent. If this is an issue, use webhookEventId in the webhook event objects to detect duplicates.
  • If webhook events are redelivered, the order in which webhook events occur and the order in which they reach the bot server can be different significantly. If this is an issue, check the context by looking at the timestamp of webhook event objects.

# Redelivered webhooks

The content of a redelivered webhook event object will be the same as the original webhook event object except for the value of deliveryContext.isRedelivery. Values such as Webhook Event ID and reply token will remain unchanged.

The reply token included in a redelivered webhook event object can be used except in certain cases. For more information on reply tokens, see Reply token in the Messaging API reference.

# Enable webhook redelivery

Webhook redelivery is disabled by default. To enable webhook redelivery, perform the following steps from the LINE Developers Console.

  1. Open the settings screen of the channel for which you want to enable webhook redelivery.
  2. Click the Messaging API tab.
  3. Turn on Use webhook.
  4. Turn on Webhook redelivery.

When Webhook redelivery is turned on, a note for using webhook redelivery will be displayed. By following the instructions, you can receive webhooks that failed to be received.

Enable webhook redelivery

# Conditions for redelivering webhooks

Webhooks sent from the LINE Platform will be redelivered within a certain period of time and with a certain time interval when the following two conditions are met.

  1. Webhook redelivery is enabled
  2. The bot server did not return a status code in the 20x for the webhook.
May not be able to redeliver webhooks

The webhook redelivery feature does not guarantee reliable redelivery of webhooks. In addition, if the number of webhook redeliveries increases significantly in a short period of time and it is determined that it will affect the operation of the LINE Platform, the webhook redelivery setting may be forcibly disabled.

# Check error statistics for sending webhooks

The Messaging API provides a feature to check statistics on errors in sending webhooks. This is useful for understanding the status of sending webhooks when a webhook was not received due to a problem on the bot server, etc.

# Enable error statistics

The display of error statistics is disabled by default. To view error statistics, perform the following steps from the LINE Developers Console.

  1. Open the settings screen of the channel for which you want to view error statistics.
  2. Click the Messaging API tab.
  3. Turn on Use webhook.
  4. Turn on Error statistics aggregation.

The above allows you to view error statistics. To view statistics, go to the Statistics tab and select Errors from the drop-down.

Error statistics aggregation

# Check the reason for errors

Error statistics provide the reasons and details for errors. There are four types of reasons.

Reason Summary
could_not_connect The LINE Platform tried to send a webhook to the bot server, but could not successfully connect to the bot server.
request_timeout The LINE Platform sent a webhook to the bot server, but the bot server did not return a response within one second.
error_status_code The LINE Platform sent a webhook to the bot server, but the bot server returned a response other than the HTTP status code in the 20x.
unclassified An unknown error occurred that cannot be categorized above.

The details for each reason are as follows.

# The reason is could_not_connect

If a webhook cannot be successfully sent from the LINE Platform to the bot server, the reason will be could_not_connect. The details in this case are as follows.

Detail Summary
Connection failed Failed to connect to bot server.
Connection failed (received GOAWAY) Connection refused when connecting to bot server.
Connection failed (session closed) Connection to the bot server was unexpectedly terminated.
Connection timeout Connection to the bot server did not complete within a certain period of time.
DNS Query timeout Webhook URL name resolution was performed, but name resolution could not be completed within a certain period of time.
Invalid URL syntax An invalid Webhook URL is specified (e.g., RFC violation).
Session protocol negotiation failure Connected to bot server, but protocol negotiation failed.
TLS handshake failure Connected to bot server, but TLS handshake failed.
Unknown host The host specified in the Webhook URL could not be found.

# The reason is request_timeout

If a webhook is sent from the LINE Platform to the bot server, but the response is not received by the LINE Platform or the sending fails midway, the reason will be the request_timeout. The details in this case are as follows. Note that the webhook may have been successfully received by the bot server.

Detail Summary
Request timeout Webhook was sent to the bot server, but no response was returned within a certain period of time.

# The reason is error_status_code

If the reason is error_status_code, the details will contain the HTTP status code.

# The reason is unclassified

If an unclassified error occurs, the reason is unclassified. The details in this case are as follows.

Detail Summary
Session closed unexpectedly A webhook was sent to the bot server, but the connection was unexpectedly closed.
Stream closed unexpectedly A webhook was sent to the bot server, but the stream was unexpectedly closed.
Unclassified webhook dispatch error An unclassifiable and unexpected error occurred.

# Getting content sent by users

You can get images, videos, audio, and files sent by users using message IDs received via the webhook.

Example request

curl -v -X GET https://api-data.line.me/v2/bot/message/{messageId}/content \
-H 'Authorization: Bearer {channel access token}'

For more information, see Get content in the Messaging API reference.

Note
  • Content sent by users is automatically deleted after a certain period of time.
  • There is no API for retrieving text sent by users.
  • You can get the text sent by the user via the text message object of the webhook. There is no API to get the text sent by users again after receiving the webhook.

# Getting user profile information

Get the user ID from the webhook event object. User IDs allow you to get users' LINE profile information such as user's display name, user ID, URL to the profile image and status message.

Example request

curl -v -X GET https://api.line.me/v2/bot/profile/{userId} \
-H 'Authorization: Bearer {channel access token}'

If successful, a JSON object is returned.

{
  "displayName": "LINE Botto",
  "userId": "U4af4980629...",
  "pictureUrl": "https://obs.line-apps.com/...",
  "statusMessage": "Hello world!"
}

For more information, see Get profile in the Messaging API reference.