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 API server lets you automatically send responses to LINE users. Messages sent by users are relayed through the LINE platform to your BOT API server. Your BOT API server can then respond with messages, images and videos.

 

Prerequisites

To develop a BOT API 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 API server.

Register an event endpoint URL

step1

Click Channels on the top right and log in to the Channel Console.

capture_001

step2

Select your Channel

capture_011

step3

Go to Technical configuration and click EDIT

capture_012

capture_013

step4

Enter the event endpoint URL in the BOT section

capture_017

step5

Click SAVE at the bottom of the page

capture_018

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 API server from the LINE platform.

 

Request specifications

HTTPS is used to access the BOT API 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 API server’s Channel
toChannel “1441301333” Channel ID of the BOT API 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 API 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 API server. Will resend in 5 seconds.

You must make sure that your BOT API server sends responses as soon as possible after receiving a request. The LINE platform will wait 10 seconds for your BOT API 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 API 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 API 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 API 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 API 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 – <Channel Name>
     

    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/<Channel_ID>/errors.

     

    Sending messages

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

     

    Issuing Channel access tokens

    Your BOT API 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.

    Issue Channel access tokens

    step1

    Click Channels on the top right and log in to the Channel Console

    capture_001

    step2

    Select your Channel

    capture_011

    step3

    Go to Technical configuration

    capture_012

    step4

    Click ISSUE in the Channel access tokens section.

    capture_016

    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 API server.
    Endpoint host api.line.me
    (Deprecated) channel-apis.line.naver.jp
    Protocol HTTPS
    Required request 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 API 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.