API reference for BOT API (Deprecated)

This page talks about the specifications for messages/operations sent from the LINE platform and received by your BOT API server. The specifications for the APIs used by your BOT API server are also explained.

Receiving messages

When a user sends a message, the following information is included in the request sent to your BOT API server.

Property list of messages

When a user sends a message, the following data is sent to your server from the LINE platform.

Property name Type Description
id String Identifier of the message.
contentType Integer A numeric value indicating the type of message sent.
from String MID of the user who sent the message.
createdTime Integer Time and date request created. Displayed as the amount of time passed since 0:00:00 on January 1, 1970. The unit is given in milliseconds.
to Array of Strings Array of user who will receive the message.
toType Integer Type of user who will receive the message. (1: To user )
contentMetadata Object Detailed information about the message
text String Posted text to be delivered. Note: users can send a message which has max 10,000 characters.
location Object Location data. This property is defined if the text message sent contains location data.

ContentType values

The contentType property varies according to the type of message being sent. The chart below shows how contentType values are handled according to type.

contentType value Description
1 Text message
2 Image message
3 Video message
4 Audio message
7 Location message
8 Sticker message
10 Contact message

Property list of location object

The location object is made up of the follow properties.

Property name Type Description
title String “Location data” string
address String Address
latitude Decimal Latitude
longitude Decimal Longitude

Property list of contentMetadata object

The information found in the contentMetadata object varies according to the contentType value. If contentType is 8 (Sticker message) or 10 (Contact message), detailed information is defined in the contentMetadata object. The values are set to null for all other contentType values. The following chart shows the properties defined in the contentMetadata object.

contentType value Property name Type Description
8 (Sticker message) STKPKGID String The package ID of the sticker.
STKID String The sticker ID.
STKVER String The sticker’s version number.
STKTXT String The text of the sticker.
10 (Contact message) mid String The MID value of the person sent as this contact.
displayName String The nickname of the person sent as this contact.

Example

{"result":[
  {
    "from":"u2ddf2eb3c959e561f6c9fa2ea732e7eb8",
    "fromChannel":1341301815,
    "to":["u0cc15697597f61dd8b01cea8b027050e"],
    "toChannel":1441301333,
    "eventType":"138311609000106303",
    "id":"ABCDEF-12345678901",
    "content": {
      "location":null,
      "id":"325708",
      "contentType":1,
      "from":"uff2aec188e58752ee1fb0f9507c6529a",
      "createdTime":1332394961610,
      "to":["u0a556cffd4da0dd89c94fb36e36e1cdc"],
      "toType":1,
      "contentMetadata":null,
      "text":"Hello, BOT API Server!"
    }
  },
  ...
]}
 

Requests containing multiple messages

When many messages are sent by users in a short period of time, multiple messages may be sent in one request to the BOT API server to reduce the load on the server. In such an event, confirm that the request is properly handled when implementing the “receive message” function. The following is an example of a request containing multiple messages.

{"result":[{1st event},{2nd event},...]}

Receiving operations

The LINE platform sends operation requests to your BOT API server when users perform actions such as adding your account as friend. The following information is included in operation requests.

Property list of operations

The following data is sent to your server from the LINE platform.

Property name Type Description
revision Integer Revision number of operation
opType Integer Type of operation
params Array of Strings Array of MIDs

opType values

The opType values correspond to different operation types.

opType value Description
4 Added as friend (including canceling block).
8 Blocked account

params values

The params values correspond to different operation types.

opType value 1st params value 2nd params value 3rd params value
4 (Added as friend) MID of user who added your account as a friend. null. Fixed value. null. Fixed value.
8 (Blocked account) MID of user who blocked your account. null. Fixed value. null. Fixed value.

Example

{"result":[
  {
    "from":"uefb896062d34df287b220e7b581d24a6",
    "fromChannel":1341301815,
    "to":["u0cc15697597f61dd8b01cea8b027050e"],
    "toChannel":1441301333,
    "eventType":"138311609100106403",
    "id":"ABCDEF-12345678901",
    "content": {
      "params":[
        "u0f3bfc598b061eba02183bfc5280886a",
        null,
        null
      ],
      "revision":2469,
      "opType":4
    }
  },
  ...
]}

After users add your account as a friend, you can send them a greeting message or instructions to provide a positive user experience.

Sending messages

The Post Event API is called to send messages from your BOT API server. The requirements for the request body varies depending on the user who you want to send messages to.

To call the Post Event API, send a request to the LINE platform with the following information.

Endpoint URL https://trialbot-api.line.me/v1/events
HTTP method POST
Required request header Content-Type: application/json; charser=UTF-8
X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

Set a JSON string in the request body that includes the message you want to send. Apply the following values to the request.

Property name Value
to Array of target user. Max count: 150.
toChannel 1383378250 Fixed value
eventType “138311608800106203” Fixed value.
content Object that contains the message (varies according to message type).

Example 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":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    ...
  }
}

Text

The required values for sending text are as follows.

Property name Type Description
contentType Integer 1. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
text String String you want to send. Messages can contain up to 1024 characters.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":1,
    "toType":1,
    "text":"Hello, Jose!"
  }
}

Image

To send an image, place 2 image files (main image and thumbnail image used for preview) on your BOT API server, then relay the image to the LINE platform. The required values are as follows.

Property name Type Description
contentType Integer 2. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
originalContentUrl String URL of image. Only JPEG format supported. Image size cannot be larger than 1024×1024.
previewImageUrl String URL of thumbnail image. For preview. Only JPEG format supported. Image size cannot be larger than 240×240.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":2,
    "toType":1,
    "originalContentUrl":"http://example.com/original.jpg",
    "previewImageUrl":"http://example.com/preview.jpg"
  }
}

Video

To send a video, place a video file and a thumbnail image to be used as preview on your BOT API server, then relay the video to the LINE platform. The required values are as follows.

Property name Type Description
contentType Integer 3. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
originalContentUrl String URL of the movie. The “mp4” format is recommended.
previewImageUrl String URL of thumbnail image used as a preview.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":3,
    "toType":1,
    "originalContentUrl":"http://example.com/original.mp4",
    "previewImageUrl":"http://example.com/preview.jpg"
  }
}

Audio

To send a voice message, place the audio file on your BOT API server, then relay the audio file to the LINE platform. The required values are as follows.

Property name Type Description
contentType Integer 4. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
originalContentUrl String URL of audio file. The “m4a” format is recommended.
contentMetadata.AUDLEN String Length of voice message. The unit is given in milliseconds.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":4,
    "toType":1,
    "originalContentUrl":"http://example.com/original.m4a",
    "contentMetadata":{
      "AUDLEN":"240000"
    }
  }
}

Location

To send location information, the required values are as follows.

Property name Type Description
contentType Integer 7. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
text String String used to explain the location information (example: name of restaurant, address).
location.title String Assigned the same string as the text property.
location.latitude Decimal Latitude.
location.longitude Decimal Longitude.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":7,
    "toType":1,
    "text":"Convention center",
    "location":{
      "title":"Convention center",
      "latitude":35.61823286112982,
      "longitude":139.72824096679688
    }
  }
}

Sticker

To send a sticker, the required values are as follows. You can use the stickers shown in the sticker list.

Property name Type Description
contentType Integer 8. Fixed value.
toType Integer Type of recipient set in the to property. (1 = user)
contentMetadata.STKID String ID of the sticker.
contentMetadata.STKPKGID String Package ID of the sticker.
contentMetadata.STKVER String Optional. Version number of the sticker. If omitted, the latest version number is applied.

Example JSON string

{
  "to":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    "contentType":8,
    "toType":1,
    "contentMetadata":{
      "STKID":"3",
      "STKPKGID":"332",
      "STKVER":"100"
    }
  }
}

Sending multiple messages

You can use the following API to send multiple messages to users in a single request. You can also determine the order of the messages that you want to send.

Request

The endpoint specification for multiple messages is the same as for single messages. But the event type ID is different.

Endpoint URL https://trialbot-api.line.me/v1/events
HTTP method POST
Required request header Content-Type: application/json; charser=UTF-8
X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

The POST Event API is called to send multiple messages. Multiple messages are included in the request.

to Array of target users’ MIDs. Max count: 150.
toChannel 1383378250 Fixed value.
eventType “140177271400161403″ Fixed value.
content.messages The messages property is an array with multiple sent message definitions.
content.messageNotified Optional. Zero-based index of the message to be notified. Default value is 0.

Example

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":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"140177271400161403",
  "content": {
    "messageNotified": 0,
    "messages": [
      {
        "contentType": 1,
        "text": "First message"
      },
      {
        "contentType": 2,
        "originalContentUrl": "...",
        "previewImageUrl": "..."
      },
      ...
    ]
  }
}

Sending rich messages

Your server can send rich messages, which are messages with interactive features.

With rich messages, users can tap on an image in the message to open a URL or to send a preset text message to your BOT account.

Prerequisites

Rich messages are composed of one image. To support a variety of devices, images of the following sizes must be created:

  • Width: Fixed 1040px
  • Width: Fixed 700px
  • Width: Fixed 460px
  • Width: Fixed 300px
  • Width: Fixed 240px

Max height is 2080px. JPEG and PNG are supported for images (we recommend JPEG for performance). The LINE app fetches the optimal image specified when the API is called. The image should be put on the CDN for global.

The width which the LINE app uses depends on the screen resolution of the user’s device. The LINE app automatically decides on the URL to fetch the optimal image.

  • Width 1040px: DOWNLOAD_URL/1040
  • Width 700px: DOWNLOAD_URL/700
  • Width 460px: DOWNLOAD_URL/460
  • Width 300px: DOWNLOAD_URL/300
  • Width 240px: DOWNLOAD_URL/240

For example, if the DOWNLOAD_URL is “http://example.com/imgs/face” and the LINE app requires “700px”, the following URL will be requested:

  • http://example.com/imgs/face/700

You must configure your server to be able to fetch images using the URLs above. Note that redirect is not supported.

Objects

Rich messages are composed of a 4 object models which are described below.

  • Canvas: Area where the image is drawn. Has a fixed width and height.
  • Image: The image is drawn on the canvas. One message can only have one image.
  • Action: This defines the behavior when the image is tapped.
  • Scene: This defines a mapping between the image and action, and defines areas to receive a tap event.

To send rich messages, create a request using a JSON format which has these models.

Example JSON code:

{
  "canvas": {
    "width": 1040,
    "height": 1040,
    "initialScene": "scene1"
  },
  "images": {
    "image1": {
      "x": 0,
      "y": 0,
      "w": 1040,
      "h": 1040
    }
  },
  "actions": {
    "openHomepage": {
      "type": "web",
      "text": "Open our homepage.",
      "params": {
        "linkUri": "http://your.server.name/"
      }
    },
    "sayHello": {
      "type": "sendMessage",
      "text": "Say hello.",
      "params": {
        "text": "Hello, Brown!"
      }
    }
  },
  "scenes": {
    "scene1": {
      "draws": [
        {
          "image": "image1",
          "x": 0,
          "y": 0,
          "w": 1040,
          "h": 1040
        }
      ],
      "listeners": [
        {
          "type": "touch",
          "params": [0, 0, 1040, 350],
          "action": "openHomepage"
        },
        {
          "type": "touch",
          "params": [0, 350, 1040, 350],
          "action": "sayHello"
        }
      ]
    }
  }
}

Important:

  • The canvas and the image are the same size.
  • There are two actions. One to open the homepage in the web browser. One to send the text message to BOT.
  • One scene is defined. The scene has two sub-models: draws and listeners.
  • scene1 relates to the image specified by the image ID image1 using the draw sub-model. scene1 defines two areas where tap events are received and maps the areas to each action.

In the example above, if the user taps the top half of the image, the home page will be opened. If the user taps the bottom half of the image, the page of an item will be open.

Here’s the part of description for the model specification.

Canvas
Property name Description Value
width A width of the canvas area. Integer fixed value: 1040.
height A height of the canvas area. Integer value. Max value is 2080px.
initialScene An initial scene name. Fixed string “scene1″.
Image

Each image has an ID. The ID is used as the property name of the images object.

"images": {
  "image1": { ... }
}

The images object can only have one image. You should use the ID image1 as the image’s property name. The image object has the following properties:

Property name Description Value
x The x-coordinate value on the image. Fixed 0.
y The y-coordinate value on the image. Fixed 0.
w The width of the image. Integer fixed value: 1040.
h The height of the image. Integer value. Max value is 2080px.
Action

Each action has an ID. The ID is used as the property name of the action object.

"actions": {
  "openHomepage": { ... },
  ...
}

The actions object can have multiple action objects. Each action object has the following properties:

Property name Description Value
type Action type. String. “web” or “sendMessage”.
Note: The “sendMessage” type is only supported on smartphones.
text Alternative string displayed on low-level devices. Any string.
params Additional information for the behavior of this action. For the web type, an object with the property, linkUri, which is opened in the web browser.
For the sendMessage type, an object with the property, text, which is sent in the chat.
Scene

Rich messages can have only one scene named scene1.

"scenes": {
  "scene1": { ... }
}

The scene has two sub-models draws and listeners. The draws model has only one image. For example, the draw object has the following properties:

Property name Description Value
image The image ID. Use the image ID “image1″.
x x-coordinate value. Fixed 0.
y y-coordinate value. Fixed 0.
w Width of the image. Integer value. Any one of 1040, 700, 460, 300, 240. This value must be same as the image width.
h Height of the image. Integer value. Max value is 2080px.

The listener model defines a mapping between an event tap area and the action. The listeners property can have multiple listener objects. Each listener object has the following properties:

Property name Description Value
type Event type. Fixed “touch”.
params Rectangular area where tap event is received. Array of the rectangle information. [x, y, width, height].
action Action ID to be executed when the tap event occurs. Action ID string. For example, “openHomepage”.

Request

Rich messages are sent with the Post Event API.

Endpoint URL https://trialbot-api.line.me/v1/events
HTTP method POST
Required request header Content-Type: application/json; charset=UTF-8
X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

Example 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":["u5912407b444e54885d00111f7b0ce375"],
  "toChannel":1383378250,
  "eventType":"138311608800106203",
  "content":{
    ...
  }
}

To send Rich messages, you need to specify the following properties in the content property above:

Property name Type Description
contentType Integer Fixed 12.
toType Integer Type of recipient set in the to property. (1= user)
contentMetadata Object Information about the Rich message.

The contentMetadata object has the following properties:

Property name Type Description
DOWNLOAD_URL String URL of image which is on your server.
SPEC_REV String Fixed “1”.
ALT_TEXT String Alternative string displayed on low-level devices.
MARKUP_JSON String Escaped string of the JSON string representing the rich message object.

Example:

"content": {
  "contentType": 12,
  "toType": 1,
  "contentMetadata": {
    "DOWNLOAD_URL": "http://example.com/bot/images/12345",
    "SPEC_REV": "1",
    "ALT_TEXT": "Please visit our homepage and the item page you wish.",
    "MARKUP_JSON": "{\"canvas\":{...},\"images\":{...},\"actions\":{},\"scenes\":{...}}"
  }
}

Getting message content

Use the following API to retrieve the content of a user’s message which is an image or video file.

Note: Contents are only stored on our servers for a certain period of time, after which they can no longer be received. We are unable to provide details about how long contents are stored.

Request

HTTP method GET
Endpoint URL https://trialbot-api.line.me/v1/bot/message/<messageId>/content
Required request header X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

The <messageId> included in the endpoint URL designates the ID (content/id) of the message whose contents you want to receive.

For example, in the “Receiving messages” event below, <messageId> is 123456789.

{"result":[
  {
    "content":{
      "toType":1,
      "createdTime":1448616197774,
      "from":"u90efb18b1449b80dfe176e490058124a",
      "location":null,
      "id":"123456789",
      "to":["u9a1701809838503fc3f9a7048d819ccf"],
      "text":"",
      "contentMetadata":null,
      "deliveredTime":0,
      "contentType":2,
      "seq":null
    },
    "createdTime":1448616198606,
    "eventType":"138311609000106303",
    "from":"uefb896062d34df287b220e7b581d24a6",
    "fromChannel":1341301815,
    "id":"ABCDEF-12345678901",
    "to":["uaf73f6500f6bd2e8f1697782c042420d"],
    "toChannel":1441301333
  },
  ...
]}

Response

Binary data of the message content is sent. The original file name is sent in the Content-Disposition HTTP response header.

Getting previews of message content

When a user sends a message to the BOT API server via the LINE platform using “Receiving messages”, you will receive a thumbnail preview of the message if the message is an image or video file.

Note: Content is only stored on our servers for a certain period of time, after which they can no longer be received. We are unable to provide details about how long content is stored.

Request

HTTP method GET
Endpoint URL https://trialbot-api.line.me/v1/bot/message/<messageId>/content/preview
Required request header X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

The <messageId> included in the endpoint URL designates the ID (content/id) of the message whose contents you wish to receive.

For example, in the “Receiving messages” event below, <messageId> is 123456789.

{"result":[
  {
    "content":{
      "toType":1,
      "createdTime":1448616197774,
      "from":"u90efb18b1449b80dfe176e490058124a",
      "location":null,
      "id":"123456789",
      "to":["u9a1701809838503fc3f9a7048d819ccf"],
      "text":"",
      "contentMetadata":null,
      "deliveredTime":0,
      "contentType":2,
      "seq":null
    },
    "createdTime":1448616198606,
    "eventType":"138311609000106303",
    "from":"uefb896062d34df287b220e7b581d24a6",
    "fromChannel":1341301815,
    "id":"ABCDEF-12345678901",
    "to":["uaf73f6500f6bd2e8f1697782c042420d"],
    "toChannel":1441301333
  },
  ...
]}

Response

The binary data of the thumbnail preview image will be sent. The original file name will be sent on the Content-Disposition HTTP response header.

Getting user profile information

The profile information of any specified user can be obtained.

Objects

The following API provides the following objects that have users’ profiles.

Property name Type Description
contacts Array of object Container of profile information for 0 friends and above.
count Integer No. of results in this response.
total Integer Total no. of results that match the specified conditions.
start Integer Starting index specified in the request.
display Integer Display parameter value specified in the request.

The contacts array property contains the profile information of 0 or more users as objects. The properties of the profile object are as follows.

Property name Type Description
displayName String User nickname.
mid String User ID.
pictureUrl String URL of user’s profile photo.
statusMessage String User’s status message. Not included in the object if the user has not created a status message.

Request

HTTP method GET
Endpoint URL https://trialbot-api.line.me/v1/profiles
Required request Header X-Line-ChannelID: Channel ID
X-Line-ChannelSecret: Channel secret
X-Line-Trusted-User-With-ACL: Channel MID

This API supports the following query parameters.

Name Type Default value Description
mids String (comma-separated) Required. Lists the MIDs of the users whose information is to be retrieved, separated by commas.

Example

{
  "contacts": [
    {
      "displayName":"BOT API",
      "mid":"u0047556f2e40dba2456887320ba7c76d",
      "pictureUrl":"http://dl.profile.line.naver.jp/abcdefghijklmn",
      "statusMessage":"Hello, LINE!"
    },
    ...
  ],
  "count":3,
  "display":3,
  "start":1,
  "total",3
}

Error responses

If there is an error in the request, the following responses may be returned.

Reason HTTP status code Response body
mids query parameter was not specified 500 {“statusCode”:”400″,”statusMessage”:”Required String parameter ‘mids’ is not present”}
No value was specified for the mids query parameter 400 {“statusCode”:”400″,”statusMessage”:”invalid parameter(s).”}