Facebook Messenger 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"
}

Send Message

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/send

Request param:

Param	Type	Required	Description
messaging_type	String	No	RESPONSE (used to respond to received messages. This includes promotional and non-promotional messages sent within the 24-hour standard message time range. For example, when a customer asks about appointment confirmation or status updates, you can use this tag to respond) UPDATE (sent proactively and not used to respond to received messages. This includes promotional and non-promotional messages sent within the 24-hour standard message time range) MESSAGE_TAG (messages that are non-promotional and sent after the 24-hour standard message time range using message tags)
recipientid	String	No	Required when sending non marketing messages, mutually exclusive with recipient_token(Receiver)
recipient_token	String	No	Required when sending marketing messages (recipient)
pageid	String	Yes	Sender
type	String	Yes	text/image/audio/video/file/template (fixed value)
tag	String	No	Required when messaging_type is MESSAGE_TAG
payload	Object	Yes	Message Content

Tag parameter:

Param	Type	Required	Description
ACCOUNT_UPDATE	String	No	Tag the message you want to send to the customer as irregular updates regarding their application or account
CONFIRMED_EVENT_UPDATE	String	No	Tag the message you want to send to the customer as a reminder of recent events, or updates on events the customer has signed up for
HUMAN_AGENT	String	No	After adding this tag to the message sent to the customer, the agent can reply to the user's message
POST_PURCHASE_UPDATE	String	No	Tag the message you want to send to the customer as an update on the customer's recent purchase behavior

1. payload example

1.1 type is text type

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"text",
   "payload":"What do you want to do next?"
}

1.2 type is image/audio/video/file type

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"image",
   "payload": {
       "url":"https://sg.sobot.io/console/common/face/admin.png"
   }
}

1.3 messaging_type is MESSAGE_TAG type

{
   "messaging_type":"MESSAGE_TAG",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"text",
   "tag": "ACCOUNT_UPDATE",
   "payload":"What do you want to do next?"
}

1.4 type is text type

• 1.4.1 Template type is button

Param	Type	Required	Description
template_type	String	Yes	button (fixed value)
text	String	Yes	No more than 640 chars. Text will be displayed above the button
buttons	Array	Yes	A set of buttons (quantity ranges from 1 to 3)

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"template",
   "payload": {
       "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
        {
          "type":"web_url",
          "url":"https://www.messenger.com",
          "title":"Visit Messenger"
       }]
   }
}

• 1.4.2 Template type is generic

Param	Type	Required	Description
template_type	String	Yes	generic (fixed value)
elements	Array	Yes	No more than 640 chars. Text will be displayed above the button
buttons	Array	Yes	A set of buttons (quantity ranges from 1 to 3)

elements object:

Param	Type	Required	Description
title	String	Yes	Template title, not exceeding 80 chars.
subtitle	String	No	Subtitle displayed in the template. No more than 80 chars.
image_url	String	No	URL of the image displayed in the template.
default_action	object	No	Default action performed when the template is clicked
buttons	Array	No	A set of buttons (quantity ranges from 1 to 3)

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"template",
   "payload": {
       "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_url":"https://petersfancybrownhats.com/company_image.png",
            "subtitle":"We have the right hat for everyone.",
            "default_action": {
              "type": "web_url",
              "url": "https://petersfancybrownhats.com/view?item=103",
              "messenger_extensions": false,
              "webview_height_ratio": "tall",
              "fallback_url": "https://petersfancybrownhats.com/"
            },
            "buttons":[
              {
                "type":"web_url",
                "url":"https://petersfancybrownhats.com",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"DEVELOPER_DEFINED_PAYLOAD"
              }              
            ]      
          }
      ]
   }
}

• 1.4.3 Template type is media

Param	Type	Required	Description
template_type	String	Yes	media (fixed value)
elements	Array	Yes	No more than 640 chars. Text will be displayed above the button

elements object:

Param	Type	Required	Description
media_type	String	Yes	image/video
attachment_id	String	Yes	Media ID

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"template",
   "payload": {
       "template_type":"media",
        "elements":[
        {
          "media_type":"image|video",
          "attachment_id":"ATTACHMENT_ID"
       }]
   }
}

Using Facebook URL

Param	Type	Required	Description
media_type	String	Yes	image/video
url	String	Yes	Only support Facebook URL

{
   "messaging_type":"RESPONSE",
   "recipientid":"RECIPIENTID",
   "pageid":"PAGEID",
   "type":"template",
   "payload": {
       "template_type":"media",
        "elements":[
        {
          "media_type":"image|video",
          "url": "FACEBOOK_URL"
       }]
   }
}

Upload Attachments

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/upload_async

Request param:

Param	Type	Required	Description
pageid	String	Yes	Page ID
type	String	Yes	image/audio/video/file (fixed value)
payload	Object	Yes	Attachment path

Request example:

{
   "pageid":"PAGEID",
   "type":"image",
   "payload":{
      "url":"URL"
    }
}

Return example:

{
  "item": "d13415bb2b704e58aa373bb5e0e11914",
  "ret_code": "000000",
  "ret_msg": "success"
}

Attachment_id is returned through webhook and can be tracked as track_id based on item

{
  "track_id": "d13415bb2b704e58aa373bb5e0e11914",
  "attachment_id": "1234567890"
}

Query subscription topic users

Request method:

GET

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/query_sub_users

Request param:

Param	Type	Required	Description
appid	String	Yes	Public homepage ID
title	String	Yes	Subscription topic
page_no	Integer	Yes	Start page number, not passed or wrong param. 1 by default
page_size	Integer	Yes	Pieces on each page, not passed or wrong param. 15 by default

Request example:

curl -H 'token:4ac37cb2e9c740dba4b75a34d5358802' https://sg.sobot.io/chat-facebook/api/messenger/query_sub_users?appid=22222222&title=test&page_no=1&page_size=100

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
items	List	No	Object list
page_count	Integer	Yes	Total pages
page_no	Integer	Yes	Start page
page_size	Integer	Yes	Pieces on each page
total_count	Integer	Yes	Pieces of data

Items set:

Param	Type	Required	Description
companyid	String	Yes	Company ID
create_time	Long	Yes	Creation Time
facebookid	String	Yes	Facebook ID
pageid	String	Yes	Public homepage ID
sub_status	Integer	Yes	Subscription status(1 Subscribed 0 Unsubscribed)
sub_title	String	Yes	Subscription topic
sub_token	String	Yes	Subscription user token
timezone	String	Yes	Timezone
title_describe	String	Yes	Subscription topic description
update_time	Long	Yes	Subscription status update time

Return example:

{
    "items": [
        {
            "companyid": "5f5262b52feb463bbf4e732323sdgfset",
            "create_time": 1715079942588,
            "facebookid": "5611755588",
            "pageid": "1087397686",
            "sub_status": 1,
            "sub_title": "nice day",
            "sub_token": "6956578469XXXXXX",
            "timezone": "UTC",
            "title_describe": "132",
            "update_time": 1715155761777
        }
    ],
    "page_count": 1,
    "page_no": 1,
    "page_size": 15,
    "ret_code": "000000",
    "ret_msg": "success
    "total_count": 1
}

Webhook message forwarding

Request URL:

   webhook notification message return example, configured in the Sobot Admin Center backend

1. Text

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120447751,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "524807506000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120446870,
			"message": {
				"mid": "m_hAxxtkOsBG8UEtO0RQNcwPgfxWKYaLWowT0Z7iLv",
				"text": "11"
			}
		}]
	}]
}

2. Video

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120224310,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "5248075068000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120223681,
			"message": {
				"mid": "m_6RK4gK9eklpa6uPCNFvNEvgfxWKYaLWowT0Z7iLv8BXpnCPA8KDnJOQOD26NINRuF",
				"attachments": [{
					"type": "video",
					"payload": {
						"url": "URL"
					}
				}]
			}
		}]
	}]
}

3. Image

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120138060,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "524807506000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120137558,
			"message": {
				"mid": "m_378ZrH7cpKmUUlmqOi5jQPgfxWKYaLWowT0Z7iLv8BWDeU",
				"attachments": [{
					"type": "image",
					"payload": {
						"url": "URL"
					}
				}]
			}
		}]
	}]
}

4. File

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120108440,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "5248075068000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120107805,
			"message": {
				"mid": "m_0xp5Sj8GPFoLroU33qbcjPgfxWKYaLWowT0Z7iLv8BWnRj",
				"attachments": [{
					"type": "file",
					"payload": {
						"url": "URL"
					}
				}]
			}
		}]
	}]
}

● Message sending status notification

Status attribute	Status meaning
delivery	Delivered
read	Read

1. Delivered

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120251647,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "5248075068000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120251542,
			"delivery": {
				"mids": ["m_UdMtmDiovEo-vSR_awTk2_gfxWKYaLWowT0Z7iLv8BVMtn2OGld3BIc2naK-pB2hE"],
				"watermark": 1714120250796
			}
		}]
	}]
}

2. Read

Return example:

{
	"object": "page",
	"entry": [{
		"time": 1714120249177,
		"id": "110661988000000",
		"messaging": [{
			"sender": {
				"id": "5248075068000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120248829,
			"read": {
				"watermark": 1714120247551
			}
		}]
	}]
}

3. Subscribe

Return example:

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714119984959,
		"messaging": [{
			"sender": {
				"id": "524807506000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714119984091,
			"optin": {
				"type": "notification_messages",
				"payload": "Description",
				"notification_messages_token": "863341894114000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_timezone": "UTC",
				"title": "Subscription topic"
			}
		}]
	}]
}

4. Unsubscribe

Return example:

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714120013874,
		"messaging": [{
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120013874,
			"sender": {
				"id": "524807506000000"
			},
			"optin": {
				"type": "notification_messages",
				"payload": "Description",
				"notification_messages_token": "86334189411000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_status": "STOP_NOTIFICATIONS",
				"title": "Subscription topic"
			}
		}]
	}]
}

5. Resubscribe

Return example:

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714120082018,
		"messaging": [{
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120082018,
			"sender": {
				"id": "524807506000000"
			},
			"optin": {
				"type": "notification_messages",
				"payload": "Description",
				"notification_messages_token": "863341894114000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_status": "RESUME_NOTIFICATIONS",
				"title": "Subscription topic"
			}
		}]
	}]
}

Subscription topic management

● Create or modify subscription topic

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/create_or_update_title

Request param:

Param	Type	Required	Description
appid	String	Yes	Page ID
title	String	Yes	Subscription topics
describe	String	Yes	Description of subscription topics
image_ratio	String	Yes	See: image_ratio param:
button_type	String	Yes	See: button_type param:
image_url	String	No	Image Link
timezone	String	No	Time Zone
configid	String	No	If it is a modification, the config_id is passed in

image_ratio param:

Param	Meaning
SQUARE	1:1
HORIZONTAL	1.91:1

button_type param:

Param	Meaning
ALLOW	Allow to receive messages
GET	Receive message
GET_UPDATES	Receive dynamic updates
OPT_IN	Choose to receive messages
SIGN_UP	Subscribe to messages

Request example:

curl https://sg.sobot.io/chat-facebook/api/messenger/create_or_update_title
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "appid": "106474898833640",
    "title": "Subscription topic",
    "describe": "Description message",
    "image_url": "https://xxx.xx.com/xxx/image.png",
    "image_ratio": "SQUARE",
    "button_type": "ALLOW",
    "timezone": "UTC"
}'

Return example:

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

● Delete subscription topic

Request method:

GET

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/del_title

Request param:

Param	Type	Required	Description
configid	String	Yes	Topic ID

Request example:

curl -XGET https://sg.sobot.io/chat-facebook/api/messenger/del_title?configid=482716046a4242e7a5fa42e18d943ae0655810 
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 

Return example:

{
  "ret_code": "000000",
  "ret_msg": "success"
}

● Query subscription topics

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-facebook/api/messenger/get_title_list

Request param:

Param	Type	Required	Description
start_time	Long	No	Create start time (ms)
end_time	Long	No	Creation end time (ms)
appids	String	No	Page ID (separated by commas for multiple IDs)
title	String	No	Subscription topics
page_no	Integer	Yes	Pages queried, default: 1
page_size	Integer	Yes	Pieces queried, default: 15

Request example:

curl https://sg.sobot.io/chat-facebook/api/messenger/get_title_list
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "start_time": 1317698342419,
    "end_time": 1573693149125,
    "appids": "11,22,33",
    "title": "Subscription topic",
    "page_no": 1,
    "page_size": 15
}'

Return example:

{
  "item": [
    {
      "companyid": "c72d7e67c0f64d38879747c9cfd68e85",
      "create_time": 1713871710134,
      "timezone": "UTC",
      "button_type": "ALLOW",
      "image_url": "https://xxx.xx.com/xxx/image.png",
      "title": "Subscription topic",
      "app_name": "appname",
      "update_time": 1713871710134,
      "configid": "10d7de1db4884c43b4b88e3fcbbf47d2",
      "image_ratio": "SQUARE",
      "describe": "describe message",
      "appid": "106474898833640"
    }
  ],
  "page_count": 1,
  "page_no": 1,
  "page_size": 15,
  "ret_code": "000000",
  "ret_msg": "success",
  "total_count": 1
}

Send optin message

Request method:

POST

Request URL:

  https://sg.sobot.io/chat-facebook/api/messenger/send_opt_in_message

Request param:

Param	Type	Required	Description
appid	String	Yes	Page ID
title	String	Yes	Subscription topics
recipientid	String	Yes	Facebook user ID
describe	String	No	Description of subscription topics
image_url	String	No	Image Link
image_ratio	String	No	Image ratio
button_type	String	No	Button type
timezone	String	No	Time Zone

Request example:

curl https://sg.sobot.io/chat-facebook/api/messenger/send_opt_in_message
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "appid": "106474898833640",
    "title": "Subscription topic",
    "recipient_id": "123456789"
}'

Return example:

{
  "item": {
    "message_id": "m_PWpxCEkBhmD6guuH7FnlVtlnpgH1w6kCmPWZypSP-IHxHmHwJf02vcR2t3tE2HGTtzEm27GCqXLyIhG4WazTDw",
    "recipient_id": "123456789"
  },
  "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/messenger/query_task_list

Request param:

Param	Type	Required	Description
task_start_time	Long	No	Task start time (eg：1714295033250)
task_end_time	Long	No	Task end time(eg：1714295033250)
sender	String	No	sender（Page）
task_name	String	No	Task name
message_topic_or_tag	String	No	Subscription Topics/Tags Message （Tags Message see ：message_tag type ）
message_type	Integer	No	Message Type（1.Marketing Messages 2.Tags Message）
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
already_send_num	Long	Delivered
already_read_num	Long	Read
reply_data_num	Long	Reply No.

Request example:

curl https://sg.sobot.io/chat-set/api/messenger/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",
    "message_topic_or_tag":"test topic",
    "message_type":1
}'

Return example:

{
  "items": [
    {
      "task_name": "123",
      "estimate_send_num": 3,
      "task_source": 1,
      "timezone": "GMT+08:00",
      "reply_data_num": 0,
      "task_start_time": "2024-07-18 20:02:58",
      "send_error_num": 2,
      "task_end_time": "2024-07-18 20:03:10",
      "send_success_num": 1,
      "already_send_num": 1,
      "send_time_type": 1,
      "taskid": "91f9dba1879c4a5ebc778c03665a7a47",
      "already_read_num": 0
    },
    {
      "task_name": "excel88_copy",
      "estimate_send_num": 1,
      "task_source": 1,
      "timezone": "GMT+08:00",
      "reply_data_num": 0,
      "task_start_time": "2024-07-18 19:54:03",
      "send_error_num": 11,
      "task_end_time": "2024-07-18 19:54:10",
      "send_success_num": 0,
      "already_send_num": 0,
      "send_time_type": 1,
      "taskid": "5004117ee78c4328b6d5f29faaa17413",
      "already_read_num": 0
    }
  ],
  "page_count": 12,
  "page_no": 1,
  "page_size": 2,
  "ret_code": "000000",
  "ret_msg": "success",
  "total_count": 24
}

Query sending records

API description: Query sending records

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-set/api/messenger/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（Page）
recipient	String	No	recipient ID
message_topic_or_tag	String	No	Subscription Topics/Tags Message （Tags Message see ：message_tag type ）
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（Page）
status_update_time	Long	Status update time
message_topic_or_tag	String	Subscription Topics/Tags Message

Request example:

curl https://sg.sobot.io/chat-set/api/messenger/send_record_list
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "items": [
        {
            "task_name": "test",
            "send_time": 1717051932316,
            "message_topic_or_tag": "test topic",
            "sender": "110661988252225",
            "timezone": "GMT+08:00",
            "messageid": "m_5ya2l01zq7cWZowdCAJ87-bKbz_gk7K-4b2fv6QOA4iY4_a_R44RmPh8Nz4I_oFnwls4matTIkLcD8DUFJLS9g",
            "error_code": "000000",
            "send_agentid": "3bdc079ab21d4db1847e36ae752e1048",
            "taskid": "17fe5afc271d48769f2e4bb24cf6a4f4",
            "recipient_id": "7608034689289950",
            "status_update_time": 1717051932316
        },
        {
            "task_name": "test2",
            "send_time": 1717051930714,
            "message_topic_or_tag": "test2",
            "sender": "110661988252225",
            "timezone": "GMT+08:00",
            "error_code": "1893015",
            "send_agentid": "3bdc079ab21d4db1847e36ae752e1048",
            "taskid": "17fe5afc271d48769f2e4bb24cf6a4f4",
            "recipient_id": "7336944743071365",
            "status_update_time": 1717051930714
        }
    ],
    "page_count": 1,
    "page_no": 1,
    "page_size": 100,
    "ret_code": "000000",
    "ret_msg": "success",
    "total_count": 2
}'

Return example:

{
    "items": [
        {
            "task_name": "test",
            "send_time": 1715839580345,
            "message_topic_or_tag": "ACCOUNT_UPDATE",
            "sender": "111756121635281",
            "timezone": "GMT+08:00",
            "messageid": "m_uR4fzPWk4y22dnJy95ts0FG1RsvrHC5RZ_wqwyIGTcMIwEx-Smscjvw5V3CqquPDLFgXk87RBNXsVEioobBf_g",
            "error_code": "000000",
            "send_agentid": "8532a283d2df41cc9a212bace7bf1d0b",
            "taskid": "0fd27d6f98524995bfa03a5487a23ba7",
            "recipient_id": "5194793377264405",
            "status_update_time": 1716187640915
        }
    ],
    "page_count": 1,
    "page_no": 1,
    "page_size": 15,
    "ret_code": "000000",
    "ret_msg": "success",
    "total_count": 1
}

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
999999	Unknown system exception

● Business exception

Error code	Error description
210001	Facebook page ID cannot be blank
210002	The Facebook page ID does not exist or was entered incorrectly
210003	"Subscription topics" cannot be blank
210004	The subscription topic cannot exceed 65 chars
210005	The subscription topic description cannot be blank
210006	The subscription topic description cannot exceed 65 chars
210007	The button type cannot be blank
210008	The subscription topic already exists on the current page
210009	The Facebook ID cannot be blank
210010	The subscription topic for the page does not exist in the system
210011	Changing the subscription topic does not support modifying the page ID and subscription topic
210012	The image ratio cannot be blank
210013	The configID passed in is incorrect or has been deleted

● message_tag type

code	description
CONFIRMED_EVENT_UPDATE	Confirm Event Update
POST_PURCHASE_UPDATE	Post-purchase Update
ACCOUNT_UPDATE	Account Update

● message_status

code	description
0	sent
1	delivered
2	read
9	failed

● error_code

error_code	description
1	An unknown error occurred.
1357046	Received invalid JSON reply.
2	An unexpected error has occurred.
2018344	Service temporarily unavailable
4	Rate Limit error: Application request limit reached.
2018354	Marketing Messages – There has to be a minimum delay between 2 notifications for the given notification
2018352	User is performing too many actions
10	No Permission For Pages Associated to Instant Games.
1404170	Application does not have permission for this action
1893015	This user has currently stopped notification messages for this topic
2018336	User Thread Impact
2534022	This message is sent outside of allowed window.
2534077	Cannot verify the connection between the IG account, the logged in user and the page. Please try reconnecting or verify if the user needs 2–factor authentication.
2018278	This message is sent outside of allowed window.
2018065	This message is sent outside of allowed window.
2018108	This Person Cannot Receive Messages: This person isn't receiving messages from you right now.
100	Check to make sure the ID or token you are using is valid.
33	Make sure the ID in your request exists and that your app has the proper permissions to access it.
2018001	No matching user found
2018008	Failed to fetch the file from the url. Check that the URL is valid, with a valid SSL certificate, valid file size, and that the server is responding fast enough to avoid timeouts.
2018014	Cannot send both message and state at the same time.
2018047	Upload attachment failure. A common way to trigger this error is that the provided media type does not match type of file provided int the URL.
2018074	Possible invalid ID or you do not own the attachment.
2018109	Attachment size exceeds allowable limit
2018164	Incorrect App ID.
2018294	Video upload timed out or video is corrupted. Note that if the video can't be fetched within 75 seconds, it will time out.
2018320	Invalid product id
2018328	Product template is not supported below version 8. Use API version 8 or higher to use product templates.
2534013	The page is not linked to an Instagram account
2534014	No matching Instagram user
2534015	Invalid message data
2534025	The comment is invalid for a private reply
2534029	The business has been blocked from sending messages via the IG Messaging API
2534037	The action is invalid since it's not the thread owner.
190	Access Token Error: Invalid OAuth access token.
200	Permission Error: Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live.
1545041	Message Not Sent: This person isn't available right now.
2018021	Requires phone matching access fee to be paid by this page unless the recipient user is an admin, developer, or tester of the app.
2018027	Cannot message users who are not admins, developers or testers of the app until pages_messaging_phone_number permission is reviewed and the app is live.
2018028	Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live.
2534041	The owner of the Instagram Professional account has revoked your app's access.
551	User Block Error: This person isn't receiving messages from you right now.
1545041	This person isn't available right now.
1893016	When a Page sends more than 1 opt–in request to the user on the same topic.
2018338	Warning! You are engaging in behavior that may be considered bothersome or abusive by users. You must significantly decrease the rate at which you are sending messages using message tags to this person. Further misuse of API features may result in messaging restrictions being placed on your Page
2534040	Calls to this api have exceeded the rate limit.
2022	The ability to send commerce messages has been temporarily disabled. This is the result of a feature limit placed after a policy violation.
10303	Account Linking Error: Invalid account_linking_token.
24001	User canceled payment flow
24002	Payment request cannot be processed due to missing privacy url
24005	Failed to get user ID
36103	To onboard creator accounts during Instagram phased rollout
2018144	Could not send Instant Game message to the user at this time, only 5 notifications can be sent to a user within 10 days since they last played.
2018154	Messenger Extensions unexpected error
2018163	Begin Share Param Validation Error
2018166	Permission not valid to call the SDK API
2018171	Only available to Primary and Secondary Receivers.
2018218	No profile available for this user.
2018234	Denying visibility of any secondary receiver to another secondary receiver other than itself.
2018247	Insufficient permission to access user profile.
2018300	Message failed to send because another app is controlling this thread now.
2018321	The chat is currently controlled by Messenger while the user is in an automated question and answer flow. Please wait for the flow to finish before trying again.
2071010	This SDK method is not supported on this Messenger client. Please upgrade
2071011	Messenger Extensions are not enabled – could be "messenger_extensions" was not set on a url, the domain was not added to the allow list or this is an outdated version of Messenger client
2071014	Invalid MessageContent provided to SDK API call
2071015	Invalid title string provided in message content
2071016	Invalid subtitle string provided in message content
2071017	Invalid image URL provided in message content
2071018	Invalid item URL provided in message content
2071019	Invalid button data provided in message content
2071020	URL data is missing in message content. Please provide item_url, button_url or both
2071021	sharingType provided in beginShareFlow call is not valid
2071022	Invalid attachment in begin share flow message content
2071023	Attachment type in message content must be set to template
2071024	Payload is not valid in message content attachment
2071025	Invalid open graph url provided in message content
9000001	This Message has been deleted by the user or the business.
1893022	Message not sent as part of an experiment.
000000	--
999997	Return data parsing exception
999998	Facebook Id not found
999999	Unsubscribed