LINE API

API Declaration

The "token" param must be contained in the header of the https request when calling the API.

Token is the only global API call credential for the Sobot API open platform. It is used when developers call the business APIs and thus should be properly kept. At least 32 chars should be reserved to store token. The validity period of token is currently 24 hours. It needs to be refreshed regularly or reacquired according to the token failure prompt returned by the API. When requesting the token API, regardless of the existence of token, a new token will be returned and its expiry time will be reset (currently 24 hours).

Token usage description: 1. Developers need to obtain and manage the token uniformly. When calling the Sobot open APIs of various businesses, they should use the same token, instead of refreshing and obtaining new tokens for each business. Otherwise, it will easily lead to token invalidation and affect the normal API call. 2. The current validity period of the token is transmitted by the returned expire_in, which is currently a value within 86,400 seconds. Developers need to refresh the new token in advance based on this valid time. 3. Developers should reacquire the token according to the token invalidation prompt returned by the API.

API call

● Acquire token

API description:

Get the open API token, which is only applicable to all APIs of Sobot Open Platform v5.0. Contact the Sobot after-sales service personnel to get appid and app_key in the API.

Request method:

GET

Request URL:

 https://sg.sobot.io/api/get_token

Request param:

Param	Type	Required	Description
appid	String	Yes	API credential ID, the unique API call credential ID for the 3rd-party users
create_time	String	Yes	10-digit timestamp
sign	String	Yes	Signature md5(appid+create_time+app_key)

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	No	Return object

Item object:

Param	Type	Required	Description
token	String	Yes	Token code
expires_in	String	Yes	Credential valid time (unit: s)

Timestamp conversion tool:

http://tool.chinaz.com/Tools/unixtime.aspx

sign signature generation example:

E.g., appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") is 258eec3118705112b2c53dc8043d4d34.

Request example:

curl https://sg.sobot.io/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

Return example:

{
  "item": {
    "token": "4ac37cb2e9c740dba4b75a34d5358802",
    "expires_in": "86400"
  },
  "ret_code": "000000",
  "ret_msg": "success"
}

Webhook message forwarding

Description:

webhook notification message return example, configured in the Sobot Admin Center backend. All message types follow a common structure, which includes destination, event, reply token, message type, pattern, timestamp, message source, etc. Here is an example and explanation of each field:

● Complete example

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "444573844083572737",
        "type": "text",
        "quoteToken": "q3Plxr4AgKd...",
        "text": "@All @example Good Morning!! (love)",
        "emojis": [
          {
            "index": 29,
            "length": 6,
            "productId": "5ac1bfd5040ab15980c9b435",
            "emojiId": "001"
          }
        ]
      }
    }
  ]
}

Param	Type	Required	Description
destination	String	Yes	The target user ID to receive the message is usually the user ID of your managed LINE official account.
events	Array	Yes	Event array, each element represents an event that occurred
replyToken	String	Yes	Reply token, used to reply to the message of the event
type	String	Yes	Event type, usually "message" in message events
mode	String	Yes	Event mode, can be "active" or "standby"
timestamp	Long	Yes	Timestamp of event occurrence, in milliseconds
source	Object	Yes	Source information of event, including source type and user ID
webhookEventId	String	Yes	Webhook event ID
deliveryContext	Object	Yes	Delivery context information, indicating whether the event is a redelivery
message	Object	Yes	Message content, containing different fields depending on the type of message

{
  "type": "user",
  "userId": "U4af4980629..."
}

Param	Type	Required	Description
type	String	Yes	Source type, can be "user", "group" or "room"
userId	String	Yes	User ID

{
  "isRedelivery": false
}

Param	Type	Required	Description
isRedelivery	Boolean	Yes	Whether it is a redelivery

● Receive customer message

1. Text message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "444573844083572737",
        "type": "text",
        "quoteToken": "q3Plxr4AgKd...",
        "text": "@All @example Good Morning!! (love)",
        "emojis": [
          {
            "index": 29,
            "length": 6,
            "productId": "5ac1bfd5040ab15980c9b435",
            "emojiId": "001"
          }
        ]
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	text
text	String	Yes	Message text content
emojis	Array	No	Message emoji content
mention	Array	No	Message emoji content

2. Image message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "type": "message",
      "message": {
        "type": "image",
        "id": "354718705033693859",
        "quoteToken": "q3Plxr4AgKd...",
        "contentProvider": {
          "type": "line"
        },
        "imageSet": {
          "id": "E005D41A7288F41B65593ED38FF6E9834B046AB36A37921A56BC236F13A91855",
          "index": 1,
          "total": 2
        }
      },
      "timestamp": 1627356924513,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "replyToken": "7840b71058e24a5d91f9b5726c7512c9",
      "mode": "active"
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	image
quoteToken	String	Yes	Message reference token
contentProvider.type	String	Yes	Provider of the image file: 1. line: The image was sent by a LINE user. You can retrieve the binary data of an image file by specifying the message ID and calling the endpoint of acquired content 2. external: URL of the image file is contained in the attribute
contentProvider.originalContentUrl	String	No	URL of the image file. The external is contained only when contentProvider.type is included
imageSet.id	String	No	Image collection ID. Contained only when multiple images are sent at the same time
imageSet.index	Integer	No	The index 1 at the beginning represents the image number in a group of images sent at the same time
imageSet.total	Integer	No	Total number of images sent at the same time. If two images are sent at the same time, the number will be 2

3. Video message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "325708",
        "type": "video",
        "quoteToken": "q3Plxr4AgKd...",
        "duration": 60000,
        "contentProvider": {
          "type": "external",
          "originalContentUrl": "https://example.com/original.mp4",
          "previewImageUrl": "https://example.com/preview.jpg"
        }
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	video
quoteToken	String	Yes	Message reference token
duration	String	No	Length of the video file (ms)
contentProvider.type	String	Yes	Provider of the video file: 1. line: The video was sent by a LINE user. You can retrieve the binary data of a video file by specifying the message ID and calling the endpoint of acquired content 2. external: URL of the video file (contentProvider.originalContentUrl) is contained in the attribute. If the video file provider is external, the binary data of the video file cannot be retrieved using the endpoint of acquired content
contentProvider.originalContentUrl	String	No	URL of the video file. The external is contained only when contentProvider.type is included. The server where the video file is located is not provided by LY Corporation
contentProvider.previewImageUrl	String	No	URL of the preview image. The external is contained only when contentProvider.type is included. The server where the preview image file is located is not provided by LY Corporation

4. Audio message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "325708",
        "type": "audio",
        "duration": 60000,
        "contentProvider": {
          "type": "line"
        }
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	audio
duration	String	No	Length of the audio file (ms)
contentProvider.type	String	Yes	Provider of the audio file: 1. line: The audio was sent by a LINE user. You can retrieve the binary data of an audio file by specifying the message ID and calling the endpoint of acquired content 2. external: URL of the audio file (contentProvider.originalContentUrl) is contained in the attribute. If the audio file provider is external, the binary data of the audio file cannot be retrieved using the endpoint of acquired content
contentProvider.originalContentUrl	String	No	URL of the audio file. The external is contained only when contentProvider.type is included. The server where the audio file is located is not provided by LY Corporation

5. File message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "325708",
        "type": "file",
        "fileName": "file.txt",
        "fileSize": 2138
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	file
fileName	String	Yes	File name
fileSize	Integer	Yes	File size (in bytes)

6. Location message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "id": "325708",
        "type": "location",
        "title": "my location",
        "address": "1-3 Kioicho, Chiyoda-ku, Tokyo, 102-8282 Japan",
        "latitude": 35.67966,
        "longitude": 139.73669
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	location
title	String	No	Title
address	String	No	URL
latitude	Decimal	Yes	Latitude
longitude	Decimal	Yes	Longitude

7. Sticker message

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA",
      "type": "message",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      },
      "message": {
        "type": "sticker",
        "id": "1501597916",
        "quoteToken": "q3Plxr4AgKd...",
        "stickerId": "52002738",
        "packageId": "11537",
        "stickerResourceType": "ANIMATION",
        "keywords": [
          "cony",
          "sally",
          "Staring",
          "hi",
          "whatsup",
          "line",
          "howdy",
          "HEY",
          "Peeking",
          "wave",
          "peek",
          "Hello",
          "yo",
          "greetings"
        ]
      }
    }
  ]
}

Param	Type	Required	Description
id	String	Yes	Message ID
type	String	Yes	sticker
quoteToken	String	Yes	Message reference token
packageId	String	Yes	Package number
stickerId	String	Yes	Sticker ID
stickerResourceType	String	Yes	Sticker resource type: 1. STATIC: static images 2. ANIMATION: animated stickers 3. SOUND: sound stickers 4. ANIMATION_SOUND: animated stickers with sound 5. POPUP: pop-up stickers or effect stickers 6. POPUP_SOUND: pop-up stickers or effect stickers with sound 7. CUSTOM: custom stickers. Unable to retrieve the text input from the user. 8. MESSAGE: message stickers
keywords	Array	No	There are up to 15 arrays describing the keywords of the sticker. If there are 16 or more keywords on the sticker, a random selection of 15 keywords will be returned. The selection of keywords for each event is random, so the same sticker may return different keywords

● Friend status change event

1. Follow the event

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "replyToken": "85cbe770fa8b4f45bbe077b1d4be4a36",
      "type": "follow",
      "mode": "active",
      "timestamp": 1705891467176,
      "source": {
        "type": "user",
        "userId": "U3d3edab4f36c6292e6d8a8131f141b8b"
      },
      "webhookEventId": "01HMQGW40RZJPJM3RAJP7BHC2Q",
      "deliveryContext": {
        "isRedelivery": false
      },
      "follow": {
        "isUnblocked": false
      }
    }
  ]
}

Param	Type	Required	Description
type	String	Yes	follow

2. Unfollow the event

Return example:

{
  "destination": "xxxxxxxxxx",
  "events": [
    {
      "type": "unfollow",
      "mode": "active",
      "timestamp": 1462629479859,
      "source": {
        "type": "user",
        "userId": "U4af4980629..."
      },
      "webhookEventId": "01FZ74A0TDDPYRVKNK77XKC3ZR",
      "deliveryContext": {
        "isRedelivery": false
      }
    }
  ]
}

Param	Type	Required	Description
type	String	Yes	unfollow

Get media message content

● Get media message content (image/audio/video/file)

Request method:

GET

Request URL:

  https://sg.sobot.io/chat-line/api/line/get_media_content

Request header:

Param	Type	Required	Description
token	String	Yes	token

Path param:

Param	Type	Required	Description
messageid	String	Yes	line message ID
appid	String	Yes	Channel ID

Request example:

curl -v -X GET https://sg.sobot.io/chat-line/api/line/get_media_content?appid=12323&messageid=1501597916
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802'

Return example:

{
  "item": {
    "https://sg.sobot.io/chatres/c72d7e67c0f64d38879747c9cfd68e85/msg/20240626/0d63b822ba724e858a128f3f27a4f405/017a4945aa5a4832bf1809acc1878cb2.png"
  },
  "ret_code": "000000",
  "ret_msg": "success"
}

Query mass messaging task data

API description: Query mass messaging task data

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-set/api/line/query_task_list

Request param:

Param	Type	Required	Description
task_start_time	Long	No	task start time (e.g. 1714295033250)
task_end_time	Long	No	task end time (e.g. 1714295033250)
sender	String	No	sender（Line Official Account）
task_name	String	No	Task name
page_no	Integer	No	Start page (default 1)
page_size	Integer	No	Query count (default 15, max 100)

Return param:

Param	Type	Description
ret_code	String	Return code
ret_msg	String	Return message
items	Object	Return object
page_count	String	Total pages
page_no	String	Current page
page_size	String	Pieces on each page
total_count	String	Total pieces

items object:

Param	Type	Description
task_name	String	Task name
task_source	Integer	Task source（1.Broadcast）
taskid	String	Task ID
timezone	String	Time Zone
task_start_time	String	Task start time
task_end_time	String	Task end time
send_time_type	Integer	Send Type(1. Send now 2. Timed sending)
estimate_send_num	Long	Estimated sending
send_success_num	Long	Sent
send_error_num	Long	Sending failed

Request example:

curl https://sg.sobot.io/chat-set/api/line/query_task_list
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "page_no": 1,
    "page_size": 15,
    "task_start_time": 1714295033250,
    "task_end_time": 1714295033250,
    "sender": "123456",
    "task_name": "test"
}'

Return example:

{
  "items": [
    {
      "task_name": "test",
      "send_error_num": 2,
      "estimate_send_num": 2,
      "task_source": 1,
      "timezone": "GMT+08:00",
      "task_end_time": "2024-07-10 20:11:15",
      "send_success_num": 0,
      "send_time_type": 1,
      "taskid": "aa8eb4e79d8b46efaf4320622faf8e8d",
      "task_start_time": "2024-07-10 20:10:12"
    },
    {
      "task_name": "test2",
      "send_error_num": 6,
      "estimate_send_num": 7,
      "task_source": 1,
      "timezone": "GMT+08:00",
      "task_end_time": "2024-07-03 13:55:15",
      "send_success_num": 1,
      "send_time_type": 1,
      "taskid": "4ce03cb9585a4c7a941688dda8a695db",
      "task_start_time": "2024-07-03 13:54:59"
    }
  ],
  "page_count": 5,
  "page_no": 1,
  "page_size": 2,
  "ret_code": "000000",
  "ret_msg": "success",
  "total_count": 9
}

Query sending records

API description: Query sending records

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-set/api/line/send_record_list

Request param:

Param	Type	Required	Description
send_start_time	Long	No	Sending start time (e.g. 1714295033250)[Default is the latest month]
send_end_time	Long	No	Sending end time (e.g. 1714295033250)[Default is the latest month]
messageid	String	No	Message ID
message_status	String	No	Message status (see: message_status param)
taskid	String	No	Task ID
task_name	String	No	Task name
send_agentid	String	No	Sender
sender	String	No	sender
recipient	String	No	recipient ID
page_no	Integer	No	Start page (default 1)
page_size	Integer	No	Query count (default 15, max 100)

Return param:

Param	Type	Description
ret_code	String	Return code
ret_msg	String	Return message
items	Object	Return object
page_count	String	Total pages
page_no	String	Current page
page_size	String	Pieces on each page
total_count	String	Total pieces

items object:

Param	Type	Description
task_name	String	Task name
error_code	String	Error Code(see：error_code )
timezone	String	Time Zone
messageid	String	Message ID
taskid	String	Task ID
recipient_id	String	recipient ID
send_agentid	String	Sender
send_time	Long	Sending time
sender	String	sender（Line Official Account）
status_update_time	Long	Status update time

Request example:

curl https://sg.sobot.io/chat-set/api/line/send_record_list
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "page_no": 1,
    "page_size": 15,
    "send_start_time": "1714295033250",
    "send_end_time": "1714295033250",
    "sender": "123456",
    "messageid": "111111222222222333333333",
    "send_agentid":"4ac37cb2e9c740dba4b75a34d5358802",
    "recipient":"12345678,
    "message_status":"2",
    "taskid": 1123412432341234123412431,
    "task_name": "test"
}'

Return example:

{
  "items": [
    {
      "task_name": "test",
      "send_time": 1720614015369,
      "sender": "2005652357",
      "timezone": "GMT+08:00",
      "messageid": "",
      "error_code": "999999",
      "send_agentid": "67bb2e6ec79b4a43a2e235d6c7256fb0",
      "taskid": "cdd8d20360b54aae9f73bc71296bbdcb",
      "recipient_id": "131231",
      "status_update_time": 1720614015369
    },
    {
      "task_name": "test2",
      "send_time": 1719986115534,
      "sender": "2005652357",
      "timezone": "GMT+08:00",
      "messageid": "515320261680824337,515320261478973734",
      "error_code": "000000",
      "send_agentid": "3bdc079ab21d4db1847e36ae752e1048",
      "taskid": "4ce03cb9585a4c7a941688dda8a695db",
      "recipient_id": "Uf0246987876aea9a6b1e6cd7e3cd81c9",
      "status_update_time": 1719986115534
    }
  ],
  "page_count": 2,
  "page_no": 1,
  "page_size": 12,
  "ret_code": "000000",
  "ret_msg": "success",
  "total_count": 19
}

Error code

● Operation done

Error code	Error description
000000	Operation done (Any code other than this code is an error code)

● System exception

Error code	Error description
900001	Null token
900002	token expired. Get a new one
999994	Param exception. Please check
999999	Unknown system exception

● message_status

code	description
0	sent
1	delivered
2	read
9	failed