Facebook Messenger API
# 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": "操作成功"
}
2
3
4
5
6
7
8
# 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?"
}
2
3
4
5
6
7
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"
}
}
2
3
4
5
6
7
8
9
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?"
}
2
3
4
5
6
7
8
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"
}]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- 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"
}
]
}
]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
- 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"
}]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
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"
}]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
# 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"
}
}
2
3
4
5
6
7
Return example:
{
"item": "d13415bb2b704e58aa373bb5e0e11914",
"ret_code": "000000",
"ret_msg": "成功"
}
2
3
4
5
Attachment_id is returned through webhook and can be tracked as track_id based on item
{
"track_id": "d13415bb2b704e58aa373bb5e0e11914",
"attachment_id": "1234567890"
}
2
3
4
# 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": "成功",
"total_count": 1
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 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"
}
}]
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"
}
}]
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"
}
}]
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# ● 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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 2. Read
Return example:
{
"object": "page",
"entry": [{
"time": 1714120249177,
"id": "110661988000000",
"messaging": [{
"sender": {
"id": "5248075068000000"
},
"recipient": {
"id": "110661988000000"
},
"timestamp": 1714120248829,
"read": {
"watermark": 1714120247551
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 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"
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"
}
}]
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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"
}'
2
3
4
5
6
7
8
9
10
11
12
13
Return example:
{
"item": "4ac37cb2e9c740dba4b75a34d5358802",
"ret_code": "000000",
"ret_msg": "成功"
}
2
3
4
5
# ● 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'
2
Return example:
{
"ret_code": "000000",
"ret_msg": "成功"
}
2
3
4
# ● 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
}'
2
3
4
5
6
7
8
9
10
11
12
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": "成功",
"total_count": 1
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 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"
}'
2
3
4
5
6
7
8
9
Return example:
{
"item": {
"message_id": "m_PWpxCEkBhmD6guuH7FnlVtlnpgH1w6kCmPWZypSP-IHxHmHwJf02vcR2t3tE2HGTtzEm27GCqXLyIhG4WazTDw",
"recipient_id": "123456789"
},
"ret_code": "000000",
"ret_msg": "成功"
}
2
3
4
5
6
7
8
# 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 |