Getting started with Business Connect

Note: Business Connect is only available for enterprise users (LINE partners). For more information on becoming a partner, please submit an inquiry or a proposal at the LINE Partner website.

Developing a bot server lets you automatically send responses to LINE users. Messages sent by users are relayed through the LINE platform to your bot server. Your bot server can then respond with messages, images and videos.

Prerequisites

To develop a bot server, you must register for a Channel and a Business Connect account on the LINE platform. Registration is carried out by LINE representatives.

Registering event endpoint URLs

To receive requests sent from the LINE platform, you must register an event endpoint URL for your bot server.

  1. Click Channels on the top right and log in to the Channel Console.
  2. Select your Channel
  3. Go to Technical configuration and click EDIT
  4. Enter the event endpoint URL in the BOT section
  5. Click SAVE at the bottom of the page

Once registered, requests will be sent to your event endpoint URL. The event endpoint URL must use HTTPS.

Note: The SSL certificate must be issued by an authorized CA. If a self-issued SSL certificate is applied to your server, requests sent from the LINE platform will fail.

Receiving messages/operations

This section talks about the specifications of requests sent to your bot server from the LINE platform.

Request specifications

HTTPS is used to access the bot server from the LINE platform. The specifications for access requests are as follows.

  • Protocol: HTTPS
  • HTTP method: POST
  • Content type: application/json; charset=UTF-8
  • Target URL: URL registered on the Channel Console

Example:

POST /callback HTTP/1.1
Host: YOUR_SERVER_HOST_NAME
Content-type: application/json; charset=UTF-8
X-LINE-ChannelSignature: /xZcekiWAiCrwq5dC+wBwBf6gQ33i1jRAo01KAVO3/U=

{"result":[{...}, {...}]}

The data is set in the request body as a JSON-formatted string. This data is made up of an array of objects. The content of each object depends on the type of data sent. All objects have the following properties.

Property name Value (Example) Description
from “u2ddf2eb3c959e561f6c9fa2ea732e7eb8” Fixed value
fromChannel “1341301815” Fixed value
to “u0cc15697597f61dd8b01cea8b027050e” MID value granted by the bot server’s Channel
toChannel “1441301333” Channel ID of the bot server
eventType “138311609000106303” or “138311609100106403” Identifier used to show the type of data
id ABCDEF-12345678901 ID string to identify each event
content {…} Actual data relayed by the message

Values of the eventType property:

Value Description
“138311609000106303” Received message (text, images, etc.)
“138311609100106403” Received operation (added as friend, etc.)

JSON-formatted string:

{
  "result":[
    {
      "from":"u206d25c2ea6bd87c17655609a1c37cb8",
      "fromChannel":"1341301815",
      "to":["u0cc15697597f61dd8b01cea8b027050e"],
      "toChannel":"1441301333",
      "eventType":"138311609000106303",
      "id":"ABCDEF-12345678901",
      "content":{
        ...
      }
    }
  ]
}

The data in the content property object depends on the action performed by the user. The array set inside the result property can hold a maximum of 100 items. After receiving a request, your bot server returns an HTTP status code. The HTTP status codes are explained below:

HTTP Status Code Description Retry behavior
200 Success Will not retry
470 Unable to process the contents of the received request. Will not retry
Others An error occurred on the bot server. Will resend in 5 seconds.

You must make sure that your bot server sends responses as soon as possible after receiving a request. The LINE platform will wait 10 seconds for your bot server to send back one of the above HTTP status codes. If it does not receive a response within 10 seconds it will resend the request to your server.

Signature validation

The headers of all requests contain a signature which is computed by the LINE platform. When a request is received, your bot server independently computes a signature and checks it against the signature in the request to verify that the request was sent from the LINE platform. The following is required to compute signatures:

  • Channel secret (issued on the Channel Console)
  • Contents of the request (complete JSON string inside the request)

Signatures are computed by:

  1. Calculating a digest value against all contents of the request body with HMAC-SHA256 algorithm using the Channel secret value as the secret key.
  2. Encoding the digest value using BASE64.

After computing a signature, your bot server checks that it matches the signature in the header of the X-LINE-CHANNELSIGNATURE request. If they match, the validity of the request is verified. If they do not match, the request is deemed unauthorized and the request is ignored. Below are examples of the signature computation process in Java and Ruby on Rails.

Java

String channelSecret = ...; // Channel Secret string
String httpRequestBody = ...; // Request body string
SecretKeySpec key = new SecretKeySpec(channelSecret.getBytes(), HmacSHA256);
Mac mac = Mac.getInstance(HmacSHA256);
mac.init(key);
byte[] source = httpRequestBody.getBytes(UTF-8);
String signature = Base64.encodeBase64String(mac.doFinal(source));
// Compare X-LINE-CHANNELSIGNATURE request header string and the signature

Ruby

CHANNEL_SECRET = ... # Channel Secret string
http_request_body = request.raw_post # Request body string
hash = OpenSSL::HMAC::digest(OpenSSL::Digest::SHA256.new, CHANNEL_SECRET, http_request_body)
signature = Base64.strict_encode64(hash)
# Compare X-LINE-CHANNELSIGNATURE request header string and the signature

Message and operation formats

The data defined in the content property depends on the type of request.

  • Receiving messages (text, stickers, contacts)
  • Receiving operations (adding an official account as a friend)

For more information on the data sent to the bot server for the two types of request above, see API reference.

Error notification emails

If a connection error occurs while a request is sent to your bot server, a notification email is sent.

Recipients

Users with the CHANNEL_EDITOR role for the Channel.
Registered “contact mailing address” for the Channel

Subject

[LINE Developers] BusinessConnect: Error detected –

The name and ID of the Channel, the time the error occurred, error count, and the “reason for error” are included in the email. The list of the reasons for error and their descriptions are shown below.

“Reason for error” Description
SLOW_RESPONSE (Response time > 5000ms) Your API server returned 200 but the response took more than 5 seconds.
REQUEST_TIMEOUT (Response time > 10s) Your API server didn’t respond within 10 seconds. The request is not considered to have been processed and the request is sent again.
ERROR_STATUS_CODE – (XXX) Your API server returned an error. The HTTP status code is displayed in the parentheses.
UNCLASSIFIED – (XXX) Your API server couldn’t receive the request because of an SSL authentication error, blocked connection, or another reason. Details are included in the parentheses.

To see the error log in the Channel Console, go to https://developers.line.me/channels/apibot//errors.

Sending messages

The APIs provided by the LINE platform let you send messages to users from your bot server.

Issuing Channel access tokens

Your bot server can access APIs to send users messages at any time by using Channel access tokens. Channel access tokens let you call APIs without requiring users to go through the authentication and authorization process. Channel access tokens are issued on the Channel Console.

  1. Click Channels on the top right and log in to the Channel Console
  2. Select your Channel
  3. Go to Technical configuration
  4. Click ISSUE in the Channel access tokens section.

The following information is displayed when the process is complete.

  • Access token: Channel access token string used when calling APIs
  • Refresh token: Refresh token string issued when Channel access token expires.
  • Expire: Date and time the Channel access token is set to expire. This value is displayed as the amount of time passed since 0:00:00 on January 1, 1970 and the time the token is set to expire. The unit is given in milliseconds.

For more information, see Reissuing access tokens and Checking the validity of access tokens.

API access

The following specifications are common to all APIs used to communicate with your bot server.

Endpoint host

api.line.me
(Deprecated) channel-apis.line.naver.jp

Protocol

HTTPS

Required header

X-Line-ChannelToken: Channel access token

The Channel access token received in the X-Line-ChannelToken request header must be specified when calling APIs. If not specified, an HTTP status code of 401 will be returned. There are two HTTP methods for API calls.

HTTP method Endpoint URL Specification Feature
POST /v1/events See POST Event API Sending message.
GET /v1/bot/… See API reference Get information.

The Post Event API is used to send information to users from your bot server. Use the following values to call the Post Event API.

Property name Value
to An array containing the MIDs of the target users.
toChannel 1383378250 Fixed value.
eventType “138311608800106203” Fixed value.
content The object that contains the actual data of the message. This property varies according to the type of message being sent.

Example of a Post Event API call:

POST /v1/events HTTP/1.1
Host: api.line.me
Content-type: application/json; charset=UTF-8
X-LINE-ChannelToken: YOUR_CHANNEL_ACCESS_TOKEN

{
  "to":[" <mid> "], <= Valid mid list must be specified.
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    ...
  }
}

For more information on the specifications of the contents of the JSON string that must be defined when sending messages and GET, DELETE, and other methods provided by each API, see API reference.

Limitation of request body size

For POST /v1/events requests, the size of the request body must be less than 8192 bytes. The LINE platform checks the size of the request using the value of the Content-Length request header.