Conversation API LINE Support

Note

LINE channel is currently open to select customers on Sinch Customer Dashboard. To request access, send an email to linemessaging@sinch.com. For beta support, send an email to ConvAPI_LINE_beta@sinch.com, or check articles in Conversation API Knowledge Base

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.

Note

Once the LINE Developer Console account is created, you can log into LINE Official Account Manager with the same credentials.

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, follow these steps:

  1. Update your Conversation API app with LINE channel credentials as given in the example snippet below:

    Copy
    Copied
    {
     "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.

  2. Set the webhook for your LINE to the URL of the Conversation API in LINE developer console. This step is done automatically when configuring the LINE integration through the Sinch Customer Dashboard. The format of the adapter callback URL is: https://line-adapter.{{REGION}}.conversation-api.prod.sinch.com/adapter/v1/{{CONVERSATION_APP_ID}}/callback

Where {{REGION}} is either eu1 or us1, depending on the region of your app. {{CONVERSATION_APP_ID}} is the ID of your Conversation API app.

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

Enable Webhook

Enable Webhook

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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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.

Note

When sending messages using the LINE Bot, you can use LINE channel specific properties, like LINE_VIDEO_TRACKING_ID. Check out Channel Specific Properties for more info.

Text Messages

LINE channel natively supports text messages.

Text Message

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
    png
  • 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
    mp4
  • Audio formats: m4a
    Max audio file size: 200MB
    m4a

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: 240
  • Choice Buttons:

    • Max 2 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.

Choice Message

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. The following image gives an example of a card message.

  • Title: max characters limit: 40
  • Description: max characters limit: 60
  • Choice 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.

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. The following image gives an example of a carousel message.

For each card:

  • Title: max characters limit: 40
  • Description: max characters limit: 60
  • Choice 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.

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.

Location Message

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:

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

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

Sticker

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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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.

Copy
Copied
{
  "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.

Note

No error is surfaced when sending messages to a LINE recipient who blocked the bot. However, that user won't receive the message.

Copy
Copied
{
  "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:

Copy
Copied
{
  "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.

Copy
Copied
{
  "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": ""
}
Was this page helpful?