抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

抖音客服平台-客服能力消息推送接入指引

收藏
我的收藏

技术接入流程

参考流程图:

详细路径:

步骤一:消息推送能力接入

参考:消息推送配置接入指引 进行接入

步骤二:接收消息

在具体的推送请求中,有效的 payload 会放在请求的 body 中,开发者可在验签成功后对 body 进行解析,并执行具体的推送业务逻辑。

请求

编码协议:JSON
字段
必须
说明
app_id
小游戏ID
conversation_id
会话ID,当前用户所处的会话
msg_id
消息ID(可用作幂等保证)
由于平台无法保障一次推送逻辑只触发一次消息推送,在执行推送时,开发者需通过 msg_id 保障幂等,避免同一个 msg_id 被多次使用。
create_time
用户消息的创建时间,秒级时间戳
msg_type
当前消息的类型:text、image、video、score
open_id
用户的 open_id
content
文本消息内容(msg_type = "text" 时返回)
pic_url
图片 url(msg_type = "image" 时返回)
video_url
视频 url(msg_type = "video" 时返回)
score_content
评分消息内容(msg_type = "score" 时返回)
示例:
// 文本消息 { "app_id": "tt123", "conversation_id": 7494205308479291111, "msg_id": 7494460928000411111, "create_time": 1744940173524, "msg_type": "text", "open_id": "_000Iuoq1hxt4Kva16Y6szdms7qujIqiwvOx", "pic_url": null, "content": "{\"text\":\"1\",\"action\":{}}" // 只需要关注 text 字段 } // 图片消息 { "app_id": "tt123", "conversation_id": 7494205308479291111, "msg_id": 7494460928000411111, "create_time": 1747386717944, "msg_type": "image", "open_id": "_000Iuoq1hxt4Kva16Y6szdms7qujIqiwvOx", "pic_url": "https://lf6-developer-sign.bytemastatic.com/tos-cn-i-noahc9e5u2/96e3e119894443bc8b02828f7c505825?lk3s=86e038d0&x-expires=2062745687&x-signature=H3V6EZy%2FNuwt9uIXx4bqWrtwfRQ%3D", "content": null } // 视频消息 { "app_id": "tt123", "conversation_id": 7494205308479291111, "msg_id": 7494460928000411111, "create_time": 1747386717944, "msg_type": "video", "pic_url": null, "video_url": "https://v26-default.douyinvod.com/1bd9e41c63ae552385e4cb96e64a7cb9/684f909c/video/tos/cn/tos-cn-v-5f73e7/ocUnGerP1IOaQQB2hAQALC2fQxrwOANwEBfADv/?a=371173&ch=0&cr=0&dr=2&er=0&lr=test&cd=0%7C0%7C0%7C0&br=606&bt=606&ds=3&ft=GwL5G6EEBBkq8ZmossSL-_vjVQWw&mime_type=video_mp4&qs=13&rc=M3c2OnQ5cjRyNDQzNGdnM0BpM3c2OnQ5cjRyNDQzNGdnM0BqM2BwMmRzMjRhLS1kXmFzYSNqM2BwMmRzMjRhLS1kXmFzcw%3D%3D&btag=c0000e00008000&dy_q=1750041225&l=02175004122535300000000000000000000ffff0ad2b6a8ff283e", "content": null, "score_content": null, "open_id": "_000Iuoq1hxt4Kva16Y6szdms7qujIqiwvOx", } // 评分消息 { "app_id": "tt123", "conversation_id": 7494205308479291111, "msg_id": 7494460928000411111, "create_time": 1747386717944, "msg_type": "score", "pic_url": null, "video_url": null, "content": null, // score:评分;label:评分标签;coment:评论;state:1-已解决;2-未解决 "score_content": "{\"payload\":{\"score\":5,\"labels\":[{\"id\":1,\"text\":\"处理流畅及时\"},{\"id\":2,\"text\":\"服务态度良好\"},{\"id\":3,\"text\":\"准确理解问题\"}],\"comment\":\"非常\",\"state\":1}}", "open_id": "_000Iuoq1hxt4Kva16Y6szdms7qujIqiwvOx" }

响应

正常响应
HTTP 状态码:200
HTTP 响应体:JSON
{ "success": true }
异常响应
HTTP 状态码:200
HTTP 响应体:JSON
{ "success": false, "err_code": 100002, "reason": "失败原因" }
err_code 错误码枚举
err_code
说明
100002
触发频控,允许稍后重试

步骤三:回复消息

用户发送信息后,可在48小时内,至多回复5条信息
curl 示例如下:
    回复文本消息:
curl --location 'http://minigame.zijieapi.com/mgplatform/api/apps/reply/reply_user_text' \ --header 'Content-Type: application/json' \ --header 'access-token: 0801121847445a664742744e5643524d38462f41314d4c736c513d3d' \ --data '{ "micro_game_id": "tt411d37a0de37d565", "conversation_id": "7483846274349842751", "msg_id": "5123031140113221826", "create_time": 2872345199, "msg_type": "link", "content": "测试demo\n<a rel=\"noopener noreferrer\" target=\"_blank\" href=\"https://www.baidu.com/\">https://www.baidu.com/</a>" }'
    回复图片消息:
curl --location 'http://minigame.zijieapi.com/mgplatform/api/apps/reply/reply_user_image?micro_game_id=tt411d37a0de37d565&conversation_id=7483846274349842751&msg_id=51230312401132218143&create_time=1744106803&sender_name=userName' \ --header 'Content-Type: multipart/form-data' \ --header 'access-token: 0801121847445a6576303563624e384971796a58636c505a4e413d3d' \ --data-binary '@/Users/bytedance/Pictures/蓝色头像.png'
具体细节可参考 回复文本消息回复图片消息