Getting started with BOT API Trial (Deprecated)

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

 

Prerequisites

To develop your server, you must create a BOT API account from the LINE Business Center.

 

Registering a callback URL

To receive requests sent from the LINE platform, you must register a callback URL for your server on the Channel Console.

Register a callback 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 Basic information and click EDIT

capture_013

step4

Enter the callback URL in the Callback URL section.
Example: https://yourdomain.com:443/callback

callback_001

step5

Click SAVE at the bottom of the page

capture_018

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

Note: The SSL certificate must be issued by an authorized CA (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 server from the LINE platform.

 

Request specifications

HTTPS is used to access your 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 values of friends of your BOT API Trial account
toChannel “1441301333” Channel ID of your 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 (example: text, images)
“138311609100106403” Received operation (example: added as friend)
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 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 your server. Will not retry

You must make sure that your server sends responses as soon as possible after receiving a request. The LINE platform waits 10 seconds for your BPT API server to send back one of the above HTTP status codes.

 

Signature validation

The headers of all requests contain a signature which is computed by the LINE platform. When a request is received, your 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 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 your server for the two types of request above, see API reference.

Sending messages

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

Server whitelist

The BOT APIs can only be called from registered servers. To register servers, you need to add IP addresses or a network to your Channel.

If an BOT API is called from a not registered servers an HTTP status code of 427 will be returned.

Opening the server whitelist page

To open the server whitelist page:
  1. Select the Channel that you want to register a server for from the list on the left.
  2. Click Server IP whitelist.

Adding IP addresses and network addresses

Find out the IP address of the servers you want to register. You may only have one server to register or you may have hundreds. There are two methods for registering servers:
  • Using the server’s IP address
  • Using the network address.
If you only have one or a small number of servers, you can add each server’s IP address individually.
If you have many servers, you can register your servers using the network address. The CIDR (Classless Inter-Domain Routing) format must be used for this method. Add the network address using the format “network/mask”. The mask value must be greater than 24 (Class C).

API access

The following specifications are common to all APIs used to communicate with your server.
Endpoint host trialbot-api.line.me
Protocol HTTPS
Required request header X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: MID (of Channel)
The X-Line-ChannelID, X-Line-ChannelSecret and X-Line-Trusted-User-With-ACL request header must be specified when calling APIs. If not specified, an HTTP status code of 401 will be returned. You can find the Channel ID, Channel secret and MID of your Channel on the “Basic information” page in the Channel Console. 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 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: trialbot-api.line.me
Content-type: application/json; charset=UTF-8
X-Line-ChannelID: YOUR_CHANNEL_ID
X-Line-ChannelSecret: YOUR_CHANNEL_SECRET
X-Line-Trusted-User-With-ACL: YOUR_CHANNEL_MID

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

Useful links

Following are useful links that will help your development in BOT API Trial.

BOT API Trial SDK

BOT API Trial documentation