Facebook Messenger API

接口声明

在调用接口时必须在 https 请求的 header 中携带 "token" 参数。

Token 是智齿客服接口开放平台全局唯一的接口调用凭据。 开发者在调用各业务接口时都需使用 Token，开发者需要进行妥善保存。 Token 的存储至少要保留 32 个字符空间。Token 的有效期目前为 24 个小时，需定时刷新，或根据接口返回的 Token 失效提示，进行重新获取。请求 Token 接口，无论 Token 是否存在，都会返回新的 Token，并重置 Token 的过期时间（目前 24 小时）。

Token 使用方式说明： 1、开发者需要统一获取和管理 Token，在调用智齿客服各个业务开放接口时都应该使用同一个的 Token，不应该每个业务都刷新获取新的 Token，否则容易导致 Token 失效，影响接口的正常调用； 2、目前 Token 的有效期通过返回的 expire_in 来传达，目前是 86,400 秒之内的值。开发者需要根据这个有效时间提前去刷新新 Token。 3、开发者需要根据接口返回的 Token 失效提示，进行重新获取 Token。

接口调用

● 获取Token

接口说明：

获取 API 开放接口 Token，此 Token 仅适用于智齿开放平台 5.0 版本全部 API 接口 。API 接口中的参数 appid 、 app_key 请联系智齿售后人员获取。

请求方式：

GET

请求地址：

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

请求参数：

参数	类型	必填	描述
appid	String	是	接口凭证 Id，第三方用户接口调用唯一凭证 id
create_time	String	是	10位数时间戳
sign	String	是	签名 md5(appid+create_time+app_key)

返回参数：

参数	类型	必填	描述
ret_code	String	是	返回编码
ret_msg	String	是	返回信息
item	Object	否	返回对象

item 对象：

参数	类型	必填	描述
token	String	是	token 编码
expires_in	String	是	凭证有效时间，单位：秒

时间戳转换参考工具：

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

sign 签名生成示例：

例如，appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") 为 258eec3118705112b2c53dc8043d4d34。

请求示例：

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

返回示例：

{
  "item": {
    "token": "4ac37cb2e9c740dba4b75a34d5358802",
    "expires_in": "86400"
  },
  "ret_code": "000000",
  "ret_msg": "操作成功"
}

发送消息

请求方式：

POST

请求地址：

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

请求参数：

参数	类型	必填	描述
messaging_type	String	否	RESPONSE(用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息。例如，在用户询问预约确认或状态更新情况时，您可以使用此标签回复) UPDATE(主动发出且并非用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息) MESSAGE_TAG(属于非推广消息的消息，而且是在 24 小时标准消息时间范围过后使用消息标签发出)
recipientid	String	否	当发送非营销消息时必填,和recipient_token互斥(接收方)
recipient_token	String	否	当发送营销消息时必填(接收方)
pageid	String	是	发送方
type	String	是	text/image/audio/video/file/template (固定值)
tag	String	否	当messaging_type为 MESSAGE_TAG 为必填
payload	Object	是	消息内容

tag参数：

参数	类型	必填	描述
ACCOUNT_UPDATE	String	否	将您要向客户发送的消息标记为针对其申请或帐户的不定期更新
CONFIRMED_EVENT_UPDATE	String	否	将您要向客户发送的消息标记为近期事件的提醒，或客户已报名参加的进行中事件的更新
HUMAN_AGENT	String	否	在向客户发送的消息中添加此标签后，人工客服便可回复用户消息
POST_PURCHASE_UPDATE	String	否	将您要向客户发送的消息标记为针对客户最近购买行为的更新

1. payload示例

1.1 type为 text 类型

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

1.2 type为 image/audio/video/file 类型

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

1.3 messaging_type为 MESSAGE_TAG 类型

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

1.4 type为 template 类型

• 1.4.1 模板类型为button

参数	类型	必填	描述
template_type	String	是	button(固定值)
text	String	是	不超过 640 个字符。文本将显示在按钮上方
buttons	Array	是	一组按钮（数量为 1 至 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 模板类型为generic

参数	类型	必填	描述
template_type	String	是	generic(固定值)
elements	Array	是	不超过 640 个字符。文本将显示在按钮上方
buttons	Array	是	一组按钮（数量为 1 至 3 个）

elements对象：

参数	类型	必填	描述
title	String	是	模板标题，不超过 80 个字符。
subtitle	String	否	模板中显示的副标题。不超过 80 个字符。
image_url	String	否	模板中显示图片的网址。
default_action	object	否	点击模板时执行的默认操作
buttons	Array	否	一组按钮（数量为 1 至 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 模板类型为media

参数	类型	必填	描述
template_type	String	是	media(固定值)
elements	Array	是	不超过 640 个字符。文本将显示在按钮上方

elements对象：

参数	类型	必填	描述
media_type	String	是	image/video
attachment_id	String	是	媒体id

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

使用Facebook网址

参数	类型	必填	描述
media_type	String	是	image/video
url	String	是	仅支持Facebook网址

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

上传附件

请求方式：

该上传方式为异步上传,返回track_id。上传结果通过webhook返回。

POST

请求地址：

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

请求参数：

参数	类型	必填	描述
pageid	String	是	主页id
type	String	是	image/audio/video/file (固定值)
payload	Object	是	附件路径

请求示例：

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

返回示例：

{
  "item": "d13415bb2b704e58aa373bb5e0e11914",
  "ret_code": "000000",
  "ret_msg": "成功"
}

attachment_id通过webhook返回，可根据item作为track_id追踪

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

查询订阅主题用户

请求方式：

GET

请求地址：

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

请求参数：

参数	类型	必填	描述
appid	String	是	主页id
title	String	是	订阅主题名称
page_no	Integer	是	当前页数（默认从第一页）
page_size	Integer	是	每页条数（默认每页100条）

请求示例：

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

返回参数：

参数	类型	必填	描述
ret_code	String	是	返回编码
ret_msg	String	是	返回信息
items	List	否	对象列表
page_count	Integer	是	总页数
page_no	Integer	是	当前页数
page_size	Integer	是	每页条数
total_count	Integer	是	总条数

items集合：

参数	类型	必填	描述
companyid	String	是	公司id
create_time	Long	是	创建时间
facebookid	String	是	用户id
pageid	String	是	公共主页id
sub_status	Integer	是	订阅状态(1 已订阅 0 已退订)
sub_title	String	是	订阅主题
sub_token	String	是	用户token
timezone	String	是	时区
title_describe	String	是	订阅主题描述
update_time	String	是	订阅状态更新时间

返回示例：

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

Webhook消息转发

请求地址：

   webhook通知消息返回示例, 在智齿管理中心后台配置

1. 文本

返回示例：

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

2. 视频

返回示例：

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

返回示例：

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

返回示例：

{
	"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"
					}
				}]
			}
		}]
	}]
}

● 消息发送状态通知

状态属性	状态含义
delivery	已送达
read	已阅读

1. 已送达

返回示例：

{
	"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. 已阅读

返回示例：

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

3. 订阅

返回示例：

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714119984959,
		"messaging": [{
			"sender": {
				"id": "524807506000000"
			},
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714119984091,
			"optin": {
				"type": "notification_messages",
				"payload": "描述",
				"notification_messages_token": "863341894114000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_timezone": "UTC",
				"title": "订阅主题"
			}
		}]
	}]
}

4. 取消订阅

返回示例：

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714120013874,
		"messaging": [{
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120013874,
			"sender": {
				"id": "524807506000000"
			},
			"optin": {
				"type": "notification_messages",
				"payload": "描述",
				"notification_messages_token": "86334189411000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_status": "STOP_NOTIFICATIONS",
				"title": "订阅主题"
			}
		}]
	}]
}

5. 重新订阅

返回示例：

{
	"object": "page",
	"entry": [{
		"id": "110661988000000",
		"time": 1714120082018,
		"messaging": [{
			"recipient": {
				"id": "110661988000000"
			},
			"timestamp": 1714120082018,
			"sender": {
				"id": "524807506000000"
			},
			"optin": {
				"type": "notification_messages",
				"payload": "描述",
				"notification_messages_token": "863341894114000000",
				"token_expiry_timestamp": 2145916800000,
				"user_token_status": "NOT_REFRESHED",
				"notification_messages_status": "RESUME_NOTIFICATIONS",
				"title": "订阅主题"
			}
		}]
	}]
}

订阅主题管理

● 创建或修改订阅主题

请求方式：

POST

请求地址：

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

请求参数：

参数	类型	必填	描述
appid	String	是	主页Id
title	String	是	订阅主题
describe	String	是	订阅主题描述
image_ratio	String	是	见：image_ratio参数：
button_type	String	是	见：button_type参数：
image_url	String	否	图片链接
timezone	String	否	时区
configid	String	否	如果是修改,传入config_id

image_ratio参数：

参数	含义
SQUARE	1:1
HORIZONTAL	1.91:1

button_type参数：

参数	含义
ALLOW	允许接收消息
GET	接收消息
GET_UPDATES	接收动态更新
OPT_IN	选择接收消息
SIGN_UP	订阅消息

请求示例：

curl https://sg.sobot.com/chat-facebook/api/messenger/create_or_update_title
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "appid": "106474898833640",
    "title": "测试",
    "describe": "这是一条测试消息",
    "image_url": "https://xxx.xx.com/xxx/image.png",
    "image_ratio": "SQUARE",
    "button_type": "ALLOW",
    "timezone": "UTC"
}'

返回示例：

{
  "item": "4ac37cb2e9c740dba4b75a34d5358802",
  "ret_code": "000000",
  "ret_msg": "成功"
}

● 删除订阅主题

请求方式：

GET

请求地址：

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

请求参数：

参数	类型	必填	描述
configid	String	是	主题id

请求示例：

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

返回示例：

{
  "ret_code": "000000",
  "ret_msg": "成功"
}

● 查询订阅主题

请求方式：

POST

请求地址：

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

请求参数：

参数	类型	必填	描述
start_time	Long	否	创建开始时间(毫秒级)
end_time	Long	否	创建结束时间(毫秒级)
appids	String	否	主页id(多个按到逗号分割)
title	String	否	订阅主题
page_no	Integer	是	查询页数,默认:1
page_size	Integer	是	查询条数,默认:15

请求示例：

curl https://sg.sobot.com/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": "测试",
    "page_no": 1,
    "page_size": 15
}'

返回示例：

{
  "item": [
    {
      "companyid": "c72d7e67c0f64d38879747c9cfd68e85",
      "create_time": 1713871710134,
      "timezone": "UTC",
      "button_type": "ALLOW",
      "image_url": "https://xxx.xx.com/xxx/image.png",
      "title": "测试",
      "app_name": "爱你一万年",
      "update_time": 1713871710134,
      "configid": "10d7de1db4884c43b4b88e3fcbbf47d2",
      "image_ratio": "SQUARE",
      "describe": "这是一条测试消息",
      "appid": "106474898833640"
    }
  ],
  "page_count": 1,
  "page_no": 1,
  "page_size": 15,
  "ret_code": "000000",
  "ret_msg": "成功",
  "total_count": 1
}

发送optin消息

请求方式：

POST

请求地址：

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

请求参数：

参数	类型	必填	描述
appid	String	是	主页id
title	String	是	订阅主题
recipientid	String	是	facebook用户ID
describe	String	否	订阅主题描述
image_url	String	否	图片链接
image_ratio	String	否	图片比例
button_type	String	否	按钮类型
timezone	String	否	时区

请求示例:

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

返回示例：

{
  "item": {
    "message_id": "m_PWpxCEkBhmD6guuH7FnlVtlnpgH1w6kCmPWZypSP-IHxHmHwJf02vcR2t3tE2HGTtzEm27GCqXLyIhG4WazTDw",
    "recipient_id": "123456789"
  },
  "ret_code": "000000",
  "ret_msg": "成功"
}

错误编码

● 操作成功

错误编码	错误说明
000000	操作成功（除此编码以外的编码为错误编码）

● 系统异常

错误编码	错误说明
900001	token 为空
900002	token 已失效，请重新获取
999999	系统未知异常

● 业务异常

错误编码	错误说明
210001	Facebook主页ID不能为空
210002	Facebook主页ID不存在或者输入错误
210003	订阅主题不能为空
210004	订阅主题长度不能超过65个字符
210005	订阅主题描述不能为空
210006	订阅主题描述不能超过65个字符
210007	按钮类型不能为空
210008	当前主页下订阅主题已存在
210009	用户Facebook ID不能为空
210010	系统上不存在该主页的订阅主题
210011	修改订阅主题不支持修改主页ID和订阅主题
210012	图片比例不能为空
210013	传入的configID不正确或已删除