企业号 / 全部接口
入门指南
快速入门
术语解释
接口清单(Scope权限点)
Oauth2.0授权
简版授权流程说明
授权管理说明
新版授权常见问题
OAuth2.0原理及Marketing-API使用
回调地址怎么设置和使用
Token管理
获取Access Token
刷新Refresh Token
获取已授权账户
获取授权User信息
获取APP Access Token
账号服务
企业号账号管理
获取企业号信息
纵横组织账户管理
获取纵横组织下资产账户列表
获取纵横组织下资产账户列表(分页)
抖音企业号
消息管理
企业号私信发送消息接口
企业号私信菜单保存接口
企业号私信自动回复保存接口
企业号私信消息卡片保存接口
企业号私信消息卡片删除接口
企业号私信菜单读取接口
企业号私信自动回复读取接口
企业号私信用户群聊读取接口
企业号私信经营工具读取接口
企业号私信消息卡片读取接口
基础信息
企业号用户权限读取接口
评论管理
获取评论列表
获取评论的回复
获取评论从属信息
回复评论
获取企业号视频列表
经营分析
获取广告主关联的企业号列表
获取企业号推广操作记录
获取企业号基础数据
获取企业号流量来源数据
获取企业号视频分析数据
不同时间维度下支持查询指标一览表
用户分析
企业号意向用户标签创建
企业号意向用户标签编辑
企业号意向用户标签删除
企业号意向用户标签查询
企业号意向用户列表查询
企业号意向用户打标签或取消标签
企业号意向用户互动记录查询
素材管理
企业号用户素材列表接口
企业号永久素材上传接口
企业号素材删除接口
数据订阅服务
SPI数据订阅
SPI回调地址设置
订阅服务类型
X-Open-Signature签名校验
推送失败数据查询
获取推送数据列表
频控限制
最佳实践
附录
枚举值
返回码
过滤条件
企业号私信发送消息接口

该接口用于主动发送私信至抖音用户,支持文本、图片、消息卡片、群聊邀请、经营工具,视频消息暂不支持。

  • 企业号给抖音用户发送私信的频次限制与展示规则,与抖音APP内规则一致。
    规则可能动态调整,请以抖音APP内的实际规则为准,以下内容仅做参考:
    • 若企业号与用户是互相关注状态:
      企业号向用户发送消息,无条数、频次限制。
    • 若企业号与用户不是互相关注状态,用户主动向企业号发送消息:
      企业号可在48小时内向用户发送6条消息
    • 若企业号与用户不是互相关注状态,用户有主动咨询行为:
      主动咨询行为包括:进入私信对话、在商家主页或在线预约页提交预约、拨打个人主页真实电话;
      企业号可通过自动回复功能,即时向用户发送1条自动回复消息,该条自动回复不计入上述的6条消息之内,且展示在用户私信列表的【消息列表】处;
      用户主动咨询后,如企业号上述可发送消息条数已用完,则企业号可在48小时后再发3条消息,消息将展示在用户的私信列表处,但会被标记为“免打扰”,即不对用户进行新消息提示。
    • 若企业号与用户不是互相关注状态,用户无主动咨询行为:
      企业号可给同一用户主动发消息数不超过3条;1小时最多发送40个用户,1天最多发送100个用户
      关键词自动回复消息,计入3条可发送消息的额度中,例如用户触发企业号的关键词自动回复,企业号可发送消息条数减少1条; 消息将展示在用户私信列表的【陌生人列表】处。
  • 发送消息时,如使用经营工具、消息卡片、图片素材等能力,请确保对应功能为审核通过状态,否则会报错。

请求地址

https://ad.oceanengine.com/open_api/v1.0/enterprise/im/message/send/

请求方法

POST

请求Header

字段类型描述
Access-Token必填
string
授权access-token,获取方法见接口文档【获取Access-Token】

请求参数

字段类型描述
e_douyin_id必填
string
企业号账户ID,纵横组织管理员授权后,先通过【获取已授权账户】接口,查询到账号角色为2纵横组织的纵横组织账户ID,再通过【获取纵横组织下资产账户列表】接口,查询到e_douyin_id,即为企业号账户ID
to_open_id 必填
string
私信发送对象
msg_content
object
私信内容
msg_type必填
string
私信内容类型
允许值:TEXT 文字内容、IMAGE 图片内容、CARD 消息卡片、GROUP 群聊邀请、COMPONENT 经营工具
text
string
文字内容,私信内容类型为 TEXT 文字内容 时可用且必填
media_id
string
素材ID,私信内容类型为 IMAGE 图片内容 时可用且必填,素材ID,传入图片链接类型的消息卡片的素材ID,可以通过【企业号永久素材上传接口】上传素材,获取素材ID,仅支持图片类型素材,仅支持审核通过的素材,可以通过【企业号用户素材列表接口】查询素材审核状态
card_id
string
消息卡片ID,私信内容类型为 CARD 消息卡片 时可用且必填,可以通过【企业号私信消息卡片读取接口】读取授权企业号创建的消息卡片
group_id
string
群聊ID,私信内容类型为 GROUP 群聊邀请 时可用且必填,可以通过【企业号私信用户群聊读取接口】读取授权企业号所在群聊的列表
component
object
经营工具
component_id
string
经营工具ID,私信内容类型为 COMPONENT 经营工具 时必填,可以通过【企业号私信经营工具读取接口】读取授权企业号创建的经营工具列表
component_type
string
经营工具类型
允许值:
AD_ADVANCED_CONTACT_US 联系我们
RESERVE_SERVICE 在线预约
LEADS_COLLECTOR 线索收集
CAR_LEADS_COLLECTOR 汽车线索收集
AD_ADVANCED_OFFICIAL_SITE 官网主页
GROUPON_ACTIVITY 团购商品聚合页
SHOP_PRODUCT 电商商品
SHOP_COUPON 电商卡券

请求示例

Python请求示例
JAVA请求示例
PHP请求示例
curl请求示例
# coding=utf-8 import json import requests from six import string_types from six.moves.urllib.parse import urlencode, urlunparse # noqa ACCESS_TOKEN = "xxx" PATH = "/open_api/v1.0/enterprise/im/message/send/" def build_url(path, query=""): # type: (str, str) -> str """ Build request URL :param path: Request path :param query: Querystring :return: Request URL """ scheme, netloc = "https", "ad.oceanengine.com" return urlunparse((scheme, netloc, path, "", query, "")) def post(json_str): # type: (str) -> dict """ Send POST request :param json_str: Args in JSON format :return: Response in JSON format """ url = build_url(PATH) args = json.loads(json_str) headers = { "Access-Token": ACCESS_TOKEN, "Content-Type": "application/json", } rsp = requests.post(url, headers=headers, json=args) return rsp.json() if __name__ == '__main__': e_douyin_id = E_DOUYIN_ID to_open_id = TO_OPEN_ID msg_type = MSG_TYPE text = TEXT media_id = MEDIA_ID item_id = ITEM_ID card_id = CARD_ID group_id = GROUP_ID component_id = COMPONENT_ID component_type = COMPONENT_TYPE # Args in JSON format my_args = "{\"e_douyin_id\": \"%s\", \"to_open_id\": \"%s\", \"msg_content\": {\"msg_type\": \"%s\", \"text\": \"%s\", \"media_id\": \"%s\", \"item_id\": \"%s\", \"card_id\": \"%s\", \"group_id\": \"%s\", \"component\": {\"component_id\": \"%s\", \"component_type\": \"%s\"}}}" % (e_douyin_id, to_open_id, msg_type, text, media_id, item_id, card_id, group_id, component_id, component_type) print(post(my_args))
import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; import okhttp3.*; import org.apache.http.client.utils.URIBuilder; import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; import java.net.URL; import java.util.List; import java.util.Map; import java.util.stream.Collectors; public class Demo { private static final String ACCESS_TOKEN = "xxx"; private static final String PATH = "/open_api/v1.0/enterprise/im/message/send/"; private static final ObjectMapper mapper = new ObjectMapper(); /** * Build request URL * * @param path Request path * @return Request URL */ private static String buildUrl(String path) throws URISyntaxException { URI uri = new URI("https", "ad.oceanengine.com", path, "", ""); return uri.toString(); } /** * Send POST request * * @param jsonStr Args in JSON format * @return Response in JSON format */ private static String post(String jsonStr) throws IOException, URISyntaxException { OkHttpClient client = new OkHttpClient().newBuilder().build(); String url = buildUrl(PATH); RequestBody body = RequestBody.create(MediaType.parse("application/json"), jsonStr); Request request = new Request.Builder() .url(url) .method("POST", body) .addHeader("Content-Type", "application/json") .addHeader("Access-Token", ACCESS_TOKEN) .build(); Response response = client.newCall(request).execute(); return response.body().string(); } public static void main(String[] args) throws IOException, URISyntaxException { String e_douyin_id = E_DOUYIN_ID; String to_open_id = TO_OPEN_ID; String msg_type = MSG_TYPE; String text = TEXT; String media_id = MEDIA_ID; String item_id = ITEM_ID; String card_id = CARD_ID; String group_id = GROUP_ID; String component_id = COMPONENT_ID; String component_type = COMPONENT_TYPE; // Args in JSON format String myArgs = String.format("{\"e_douyin_id\": \"%s\", \"to_open_id\": \"%s\", \"msg_content\": {\"msg_type\": \"%s\", \"text\": \"%s\", \"media_id\": \"%s\", \"item_id\": \"%s\", \"card_id\": \"%s\", \"group_id\": \"%s\", \"component\": {\"component_id\": \"%s\", \"component_type\": \"%s\"}}}",e_douyin_id, to_open_id, msg_type, text, media_id, item_id, card_id, group_id, component_id, component_type); System.out.println(post(myArgs)); } }
$ACCESS_TOKEN = "xxx"; $PATH = "/open_api/v1.0/enterprise/im/message/send/"; /** * Build request URL * @param $path : Request path * @return string */ function build_url($path) { return "https://ad.oceanengine.com" . $path; } /** * Send POST request * @param $json_str : Args in JSON format * @return bool|string : Response in JSON format */ function post($json_str) { global $ACCESS_TOKEN, $PATH; $curl = curl_init(); $url = build_url($PATH); curl_setopt_array($curl, array( CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => $json_str, CURLOPT_HTTPHEADER => array( "Content-Type: application/json", "Access-Token: " . $ACCESS_TOKEN, ), )); $response = curl_exec($curl); curl_close($curl); return $response; } $e_douyin_id = E_DOUYIN_ID; $to_open_id = TO_OPEN_ID; $msg_type = MSG_TYPE; $text = TEXT; $media_id = MEDIA_ID; $item_id = ITEM_ID; $card_id = CARD_ID; $group_id = GROUP_ID; $component_id = COMPONENT_ID; $component_type = COMPONENT_TYPE; /* Args in JSON format */ $my_args = sprintf("{\"e_douyin_id\": \"%s\", \"to_open_id\": \"%s\", \"msg_content\": {\"msg_type\": \"%s\", \"text\": \"%s\", \"media_id\": \"%s\", \"item_id\": \"%s\", \"card_id\": \"%s\", \"group_id\": \"%s\", \"component\": {\"component_id\": \"%s\", \"component_type\": \"%s\"}}}", $e_douyin_id, $to_open_id, $msg_type, $text, $media_id, $item_id, $card_id, $group_id, $component_id, $component_type); echo post($my_args);
curl -H "Access-Token:xxx" -H "Content-Type:application/json" -X POST \ -d '{ "e_douyin_id": "E_DOUYIN_ID", "to_open_id": "TO_OPEN_ID", "msg_content": { "msg_type": "MSG_TYPE", "text": "TEXT", "media_id": "MEDIA_ID", "item_id": "ITEM_ID", "card_id": "CARD_ID", "group_id": "GROUP_ID", "component": { "component_id": "COMPONENT_ID", "component_type": "COMPONENT_TYPE" } } }' \ https://ad.oceanengine.com/open_api/v1.0/enterprise/im/message/send/

应答字段

字段类型描述
code
number
返回码,详见【附录-返回码】
message
string
返回信息,详见【附录-返回码】
data
json
json返回值
request_id
string
请求日志ID

应答示例

{ "code": 0, "message": "OK", "request_id": "xxxx", "data": {} }