Conversation API LINE Support

LINE channel enables communication with users of the LINE ecosystem through the Conversation API.

Prerequisites

You need a LINE Developer Console Account or a LINE Official Account to integrate your Conversation API with LINE.

If you don't already have one, follow the steps below to create a new LINE channel from the developer console:

1. You need a LINE account. If you don't already have one, download the LINE app from iOS/Android App Stores and create your LINE account.
2. Go to the LINE Developer Console , register as a developer, and create a developer account.
3. Login to developer console.
4. Create a new provider.
5. Create a Message API channel. Set the following:
   • Channel type: Messaging API .
   • Provider: select a provider.
   • Upload channel icon.
   • Enter channel name / description / category / subcategory.
6. Under Basic settings , note the channel secret .
7. Under Messaging API , note the following:
   • Bot basic ID, which is to create a deeplink or QR code.
   • QR Code, which can be presented to users, allowing them to scan and enter your bot channel directly.
   • Webhook settings, which should be empty and disabled. We will configure this later.
   • Channel access token. The long-lived channel access token is required when integrating the Conversation API with LINE.

Configuring the Conversation API and LINE integration

Next, you must enable the LINE integration for your Conversation API app.

Enabling the LINE integration using the Sinch Customer Dashboard

The easiest way to configure your Conversation API app with LINE support is to use the Sinch Customer Dashboard. Select your app and click on SET UP CHANNEL beside the LINE channel. You will be asked to enter the above channel access token and channel secret for your LINE bot.

Your LINE bot webhook callback URL will be auto configured upon saving the token and secret.

Enabling the LINE integration using the Conversation API

If you decide to configure your app through API calls, you must update your Conversation API app with LINE channel credentials as given in the example snippet below:

{
  "channel_credentials": [
    {
      "channel": "LINE",
      "line_credentials": {
        "token": "{{LINE_TOKEN}}",
        "secret": "{{LINE_SECRET}}"
      }
    }
  ]
}

You need to replace {{LINE_TOKEN}} and {{LINE_SECRET}} with your LINE token and secret.

Enable Webhook in LINE Developer Console

Due to LINE's requirements, you will need to go to the LINE developer console and enable webhooks manually:

1. Go to the developer console.
2. Select the Message API you created.
3. Select Message API tab. You can see the webhook URL is filled with Sinch URL, but it's disabled.
4. Scroll down to Greeting messages and click Edit , which opens LINE Official Account Manager page.
5. Update the following:
   • Response mode must be set to to Bot .
   • Webhooks must be set to to Enabled .
   • Auto response must be set to to Disabled .
6. Refresh Developer Console page, Webhook should be enabled now

Add Conversation Webhooks

Lastly, don't forget to add Conversation API webhooks to your app in order to receive delivery receipts and inbound messages. Adding webhooks can be done through the customer dashboard or using the management API:

• For information on how to add a Conversation API webhook using the Sinch Customer Dashboard, click here .

• For information on how to add a Conversation API webhook programmatically, click here .

Testing the integration

To test your integration, open the LINE app, search for the name of your LINE bot (or scan the bot QR code), and click Add Friend to subscribe to bot. You will get two callbacks on your Conversation API webhooks. Examples of these callbacks are below (IDs and identities are masked):

One is the opt_in_notification:

{
  "app_id": "01FM9JB4SAC2FW7FG88ABCDEFG",
  "accepted_time": "2021-11-12T08:02:26.428685Z",
  "event_time": "2021-11-12T08:02:25.384Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "opt_in_notification": {
    "contact_id": "01FM9JPMVY8ZDXP8MN4ABCDEFG",
    "channel": "LINE",
    "identity": "U4623a753d8b73729616514421234567",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01FM9JPMZW2GGE2MPN7DABCDEF"
  },
  "message_metadata": ""
}

The other is the Contact creation notification:

{
  "app_id": "",
  "accepted_time": "2021-11-12T08:02:26.366075Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "contact_create_notification": {
    "contact": {
      "id": "01FM9JPMVY8ZDXP8MN4ABCDEFG",
      "channel_identities": [
        {
          "channel": "LINE",
          "identity": "U4623a753d8b7372961651441234567",
          "app_id": "01FM9JB4SAC2FW7FG88ABCDEFG"
        }
      ],
      "channel_priority": [
        "LINE"
      ],
      "display_name": "",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    }
  },
  "message_metadata": ""
}

Both callbacks contain the field contact_id, which is the identifier of the contact that was automatically created when processing the inbound LINE message. This contact contains the channel identity for the LINE user, and you can use this contact_id to reach that LINE user.

The LINE channel identities are identifiers which are scoped to individual apps. This means that the same LINE user will have different channel identities for two different Conversation API apps.

Sending Messages

Some rich messages are natively supported by the LINE channel, while others must be converted. The following sections demonstrate the mapping between the Conversation API generic message format and the way LINE renders the messages on mobile devices.

Text Messages

LINE channel natively supports text messages.

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Messages

LINE channel natively supports various type of media messages.

Media file URL must be HTTPS over TLS 1.2 or later.

• Image formats: jpeg, jpg, png
  Max image file size: 10MB
  
• Video formats: mp4
  Video thumbnail image is required (Tip: use a 1-pixel transparent image as the universal thumbnail)
  Max video file size: 200MB
  Max thumbnail image size: 1MB
  
• Audio formats: m4a
  Max audio file size: 200MB
  

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Messages

LINE channel natively supports choice messages. The following image gives an example of a choice message.

• Text: max characters limit: 160
• Choice Buttons:
  • Max 4 buttons
  • Text Message Choice, with postback data. When clicking the button, Text will appear in the chat window, invisible postback data will be sent back.
  • URL Message Choice. When clicking the button, URL will be opened in the embedded browser.
  • Location Message Choice. When clicking the button, Google Map will be opened in the embedded browser.
  • Call Message Choice. When clicking the button, phone dial panel will be opened with prefilled number.

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Messages

LINE channel natively supports card messages with one media content.

• Image:
  • Max width: 1024 pixels
  • Aspect ratio of the image must be one of:
    • rectangle: 1.51:1
    • square: 1:1
• Title: max characters limit: 40
• Description: max characters limit: 60
• Choice Buttons:
  • Max of 4 buttons
  • Text Message Choice, with postback data. When clicking the button, Text will appear in the chat window, invisible postback data will be sent back.
  • URL Message Choice. When clicking the button, URL will be opened in the embedded browser.
  • Location Message Choice. When clicking the button, Google Map will be opened in the embedded browser.
  • Call Message Choice. When clicking the button, phone dial panel will be opened with prefilled number.

The following image gives an example of a card message:

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Messages

LINE channel natively supports carousel messages, which can be made up of a maximum of 10 cards in a single message.

For each card:

• Image:
  • Max width: 1024 pixels
  • Aspect ratio of the image must be one of:
    • rectangle: 1.51:1
    • square: 1:1
• Title: max characters limit: 40
• Description: max characters limit: 60
• Choice Buttons:
  • Max of 3 buttons
  • Text Message Choice, with postback data. When clicking the button, Text will appear in the chat window, invisible postback data will be sent back.
  • URL Message Choice. When clicking the button, URL will be opened in the embedded browser.
  • Location Message Choice. When clicking the button, Google Map will be opened in the embedded browser.
  • Call Message Choice. When clicking the button, phone dial panel will be opened with prefilled number.

The following image gives an example of a carousel message:

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Messages

LINE channel natively supports location messages.

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Sticker Messages

It's possible to send Sticker message to LINE channel by using explicit_channel_message:

{
    "app_id": "{{APP}}",
    "recipient": {
        "contact_id": "{{LINE_CONTACT}}"
    },
    "message": {
        "explicit_channel_message": {
            "LINE": "{\"messages\": [{\"type\": \"sticker\", \"packageId\": \"446\", \"stickerId\": \"1988\"}]}"
        }
    }
}

Find the LINE Sticker Package ID and Sticker ID from the List of available stickers. For example:

Receiving Messages

LINE channel supports various kinds of MO messages - text, media, postback.

All of these are delivered by Conversation API with POST to MESSAGE_INBOUND webhook:

Example text MO:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:39:35.773669Z",
  "event_time": "2021-11-11T07:39:34.122Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z039AN154JA6Q9FABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Text MO"
      }
    },
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b73729616514427dabcdefg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRW123456",
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:39:35.710185Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example location MO:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:41:38.368424Z",
  "event_time": "2021-11-11T07:41:36.974Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z3V02ZAEW7RF8D6ABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "location_message": {
        "title": "HarbourFront Tower 2",
        "coordinates": {
          "latitude": 1.2646714,
          "longitude": 103.818726
        },
        "label": "3 HarbourFront Place 099254 Singapore"
      }
    },
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b73729616514427123456",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7S9123456",
    "metadata": "",
    "accept_time": "2021-11-11T07:41:38.304523Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example media MO:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:43:09.275936Z",
  "event_time": "2021-11-11T07:43:05.789Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z6KRTNB4XBYAPV6ABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "https://convapi-eu1tst.s3.eu-west-1.amazonaws.com/01F6PDXVY6Z5GT0AM1YABCDEFG/01FM6Z6KDK5NP01FHQG123456.jpg",
        "thumbnail_url": ""
      }
    },
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b7372961651442123456",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:43:09.211687Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example choice response message:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:49:00.175682Z",
  "event_time": "2021-11-11T07:48:59.097Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6ZHAH5WYS4JN5JYPABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01FM6ZGXT36AMA0QBB9ABCDEFG",
        "postback_data": "movieId=1234&actionId=101"
      }
    },
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b73729616514427d123456",
      "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7S9ABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:49:00.105016Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Receiving Status

LINE doesn't provide an affirmative delivery status. Instead, the positive status of a message delivery to the LINE channel will be QUEUED_ON_CHANNEL:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:48:47.043Z",
  "event_time": "2021-11-11T07:48:47.851947Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message_delivery_report": {
    "message_id": "01FM6ZGXT36AMA0QBB9VABCDEFG",
    "conversation_id": "01FHZFQF598ZX723CHRABCDEFG",
    "status": "QUEUED_ON_CHANNEL",
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b73729616514427123456",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": ""
  },
  "message_metadata": ""
}

If the status is FAILED, the reason will include more information about the failure.

{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:53:20.777Z",
  "event_time": "2021-11-11T07:53:21.143671Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message_delivery_report": {
    "message_id": "01FM6ZS949X61P607KA1BACDEFG",
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "status": "FAILED",
    "channel_identity": {
      "channel": "LINE",
      "identity": "U4623a753d8b73729616514427123456",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "reason": {
      "code": "MEDIA_NOT_REACHABLE",
      "description": "The provided media [https://www.url.com/samples/picture.jpg] could not be reached: [Not Found]",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": ""
  },
  "message_metadata": ""
}

Block Bot

It's possible for users to block a LINE Bot by using the "Block" feature from their LINE App. When this happens, an opt_out_notification will be sent to the app's callback webhook and customers can take action, such as removing their contact_id from their user list.

{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:55:09.201036Z",
  "event_time": "2021-11-11T07:55:08.188Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "opt_out_notification": {
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "channel": "LINE",
    "identity": "U4623a753d8b73729616514427123456",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01FM6ZWK0PZBZBX64G8ABCDEFG"
  },
  "message_metadata": ""
}

Unblock Bot

Users can unblock LINE bot at any time. If they do so, an opt_in_notification will be sent to app's callback webhook. For example:

{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:58:36.699110Z",
  "event_time": "2021-11-11T07:58:35.419Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "opt_in_notification": {
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "channel": "LINE",
    "identity": "U4623a753d8b73729616514427123456",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01FM6ZWK0PZBZBX64G8ABCDEFG"
  },
  "message_metadata": ""
}

Receiving Video Play Complete Event

If you send a video message with LINE_VIDEO_TRACKING_ID property, the video viewing complete event occurs when the user finishes watching the video. Currently, this event is returned as an unsupported_callback type. For example.

{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-12T03:57:16.592842Z",
  "event_time": "2021-11-12T03:57:16.448057Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "unsupported_callback": {
    "channel": "LINE",
    "payload": "{\"destination\":\"Ua62d78ffe18e5f32bd548127123456\",\"events\":[{\"type\":\"videoPlayComplete\",\"videoPlayComplete\":{\"trackingId\":\"my-unique-tracking-id\"},\"timestamp\":1636689435643,\"source\":{\"type\":\"user\",\"userId\":\"U4623a753d8b7372961651442123456\"},\"replyToken\":\"ca5ed55984b840a8ab81355308ee5d8a\",\"mode\":\"active\"}]}"
  },
  "message_metadata": ""
}