Receiving messages (webhooks)

# 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. For more information on handling this event, see Processing on receipt of unsend event. ✅ ✅
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 when a template message or Flex Message is sent by a user

Although users themselves can't send a template message or Flex Message, using liff.sendMessages() allows LIFF apps to send messages on behalf of the users to the currently open chat screens.

When a user sends a template message or Flex Message via liff.sendMessages(), the message object that arrives via the webhook will be text. The string specified in the altText property of the template message or Flex Message will be included in the text property of the text message object.

"message": {
  "type": "text",
  "id": "468789577898262530",
  "quotedMessageId": "468789532432007169",
  "quoteToken": "q3Plxr4AgKd...",
  "text": "this is a flex message" // altText specified in Flex Message
}

# Receive quote messages sent by users via webhook

When a user sends a message quoting a past message, you can check the ID of the quoted message in the quotedMessageId property included in the message property of the webhook. In this case, you can check the ID of the quoted message, but you can't retrieve the content of the message (such as text or stickers).

Here is an example of a webhook that arrives at your bot server when a user sends a message quoting a past message.

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "type": "message",
      "message": {
        "type": "text",
        "id": "468789577898262530", // ID of the sent message
        "quotedMessageId": "468789532432007169", // ID of the quoted message
        "quoteToken": "q3Plxr4AgKd...",
        "text": "Chicken, please." // Text of the sent message
      },
      "webhookEventId": "01H810YECXQQZ37VAXPF6H9E6T",
      "deliveryContext": {
        "isRedelivery": false
      },
      "timestamp": 1692251666727,
      "source": {
        "type": "group",
        "groupId": "Ca56f94637c...",
        "userId": "U4af4980629..."
      },
      "replyToken": "38ef843bde154d9b91c21320ffd17a0f",
      "mode": "active"
    }
  ]
}

For more information about the quotedMessageId property, see text and sticker of the Message event in the Messaging API reference.

For more information about how users can send quote messages, see Using the chat reply feature (opens new window) (only available in Japanese) in the LINE user's guide.

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

# Processing on receipt of unsend event

Users can unsend a sent message within 24 hours of sending it.

When a user unsends a sent message, an unsend event is sent to the bot server. When the unsend event is received, we recommend that service providers respect the user's intent to unsend a sent message and handle the message appropriately with the utmost care so that the target message can't be seen or used in the future.

For example, you should handle a message that a user has unsent as follows:

  • Cancel the target message displayed on your own management screen, etc.
  • Delete the target message stored in a database or other storage device.

For more information about how to unsend a sent message in the LINE app, see Using the unsend message function (opens new window) (only available in Japanese) in the LINE user's guide.

# 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 content listed here has been moved to Check the reason for errors.

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