Menções no TikTok através da API: encontrar publicações e comentários que mencionam uma conta
A API de Menções do TikTok, parte da API for Business, devolve as 1.000 principais publicações públicas dos últimos 90 dias que @mencionam uma conta empresarial na legenda, através de GET /business/mention/video/list/, e os 1.000 principais comentários ou respostas que a mencionam, através de /business/mention/comment/list/. Ambas precisam do âmbito biz.brand.insights e de uma conta com Advanced Access ou uma Verified Business Account.
O easyCoexistence liga uma conta do TikTok através da API for Business do TikTok: o Claude, o ChatGPT ou o seu próprio código leem os comentários e respondem-lhes com ferramentas dedicadas e recebem os eventos de comentários à medida que chegam, e get_social_credentials dá ao seu próprio código o token para outras chamadas da API for Business, incluindo os endpoints de Menções onde o TikTok os abre à conta.
A maioria das publicações mencionadas que /business/mention/video/list/ devolve, todas públicas e dos últimos 90 dias, até 100 por pedido.
Atraso aproximado entre uma menção feita e a sua disponibilidade através da API de Menções.
Latência que o TikTok indica para o webhook de menções depois de um utilizador mencionar a empresa numa legenda ou comentário.
Frequência com que o TikTok recomenda chamar cada endpoint de Menções por conta, depois da atualização das 0h às 7h UTC.
O âmbito /business/mention/comment/list/ precisa, além de biz.brand.insights, para devolver comentários que mencionam a conta.
Que endpoints tem a API de Menções?
Seis endpoints de leitura, cada um deles é um GET em https://business-api.tiktok.com/open_api/v1.3, com o token de acesso da conta no cabeçalho Access-Token e o seu open_id como business_id. Dois listam menções, dois resumem o que dizem as publicações mencionadas, e dois obtêm uma única menção anunciada por um webhook:
Que publicações e comentários contam como menções?
Os que marcam o identificador da conta com @, na legenda de uma publicação ou no texto de um comentário, numa publicação pública, e que passam pelos outros filtros do TikTok:
- A publicação foi feita nos últimos 90 dias.
- O autor não é menor nem tem idade desconhecida: 17 anos ou menos conta como menor na Europa, 12 anos ou menos nos EUA e noutras regiões.
- Está entre as 1.000 publicações, ou comentários, mais gostados que mencionam o identificador.
- As publicações da própria empresa que cumprem estas regras também contam.
- Os comentários feitos só com a menção, sem outro texto, são classificados mais abaixo.
O que precisa uma conta para os usar?
Uma conta elegível, uma aplicação com a permissão certa, os âmbitos no token e um dia de espera depois de o proprietário autorizar a aplicação:
- Advanced Access ou uma Verified Business Account;
has_advanced_accessem /business/get/ indica que contas se qualificam. - A permissão de Menções na aplicação de programador, listada como Mentions, Content para publicações e Mentions, Comment para comentários.
- biz.brand.insights no token de acesso, mais comment.list para menções em comentários.
- 24 horas depois da autorização e antes da primeira consulta, como pede o guia de introdução do TikTok.
Como listar as publicações que mencionam a conta?
Com GET /business/mention/video/list/. fields escolhe os dados: item_id e caption por defeito, e create_time, video_link, likes, comments, shares, thumbnail_url, views, reach e creator_handle_name a pedido. sort_field aceita CREATE_TIME, LIKES, COMMENTS ou SHARES com sort_type ASC ou DESC, number_of_days reduz os 90 dias, regions limita os criadores às regiões escolhidas, e cursor com has_more pagina os resultados. views e reach aparecem como null abaixo de 1.000, e as ligações das miniaturas duram 48 horas:
curl --get 'https://business-api.tiktok.com/open_api/v1.3/business/mention/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","video_link","caption","likes","creator_handle_name"]' \
--data-urlencode 'sort_field=LIKES' \
--data-urlencode 'number_of_days=30' \
--data-urlencode 'max_count=100'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"videos": [
{
"item_id": "<ITEM_ID>",
"video_link": "https://www.tiktok.com/@/video/<ITEM_ID>",
"caption": "<CAPTION>",
"likes": 243,
"creator_handle_name": "<HANDLE>"
}
],
"cursor": 100,
"has_more": true
}
}Como listar os comentários que mencionam a conta?
Com GET /business/mention/comment/list/, cujo token precisa também de comment.list. Por defeito devolve comment_id e comment_text; item_id, video_link, caption, video_likes, thumbnail_url, commenter_display_name, comment_type, comment_create_time e comment_likes vêm a pedido, e comment_type indica COMMENT ou REPLY. Uma página tem 10, a menos que max_count peça até 100, ordenada por VIDEO_LIKES, COMMENT_CREATE_TIME ou COMMENT_LIKES. Devido às políticas de confiança e segurança do TikTok, uma página pode vir curta enquanto has_more continua a ser verdadeiro.
Como responder a uma menção?
Através do endpoint de resposta a comentários do TikTok. POST /business/comment/reply/create/ recebe business_id, video_id com o item_id da menção no comentário, comment_id e um texto de até 1.200 caracteres, e a resposta aparece publicamente por baixo desse comentário, na publicação que o contém. A referência do TikTok indica o âmbito comment.list.manage e o mesmo requisito de conta para o usar. A referência de Menções só lista uma resposta para menções em comentários.
As menções podem chegar por webhook?
Sim. Com a permissão de Menções, uma aplicação chama POST /business/webhook/update/ com event_type BRAND_MENTION, e o TikTok envia então brand.mention.event até duas ou três horas após uma menção, assinado em Tiktok-Signature como os seus outros webhooks. content é uma cadeia de caracteres JSON serializada que contém:
type_of_event: CREATE, EDIT ouPRIVACY_CHANGEpara uma alteração à definição de privacidade de uma publicação.mention_type: COMMENT para um comentário ou resposta,VIDEO_MENTIONpara uma legenda, caso em quecomment_idtem o valor 0.video_id,video_create_time,share_urlevideo_caption, que descrevem a publicação.open_id_of_mentioned_user,unique_name_of_mentioned_usereunique_identifier, um ID do autor do comentário que se mantém igual em todas as APIs.- Os detalhes obtêm-se com /business/mention/video/get/ ou /business/mention/comment/get/, nas 48 horas seguintes ao evento.
Com que frequência devem ser chamados os endpoints de Menções?
Uma vez por dia, por endpoint e por conta, depois das 7h UTC, é o que o TikTok recomenda. Os endpoints partilham os limites globais de pedidos da aplicação de programador, mas o TikTok atualiza os dados do dia anterior entre a meia-noite e as 7h UTC, e considera desnecessárias novas consultas no mesmo dia. Uma nova menção também demora cerca de 24 a 48 horas a chegar aos endpoints de listagem, o que torna o webhook o sinal mais rápido.
Como funcionam as hashtags de marca?
Alargam as menções às publicações que usam hashtags escolhidas pela empresa. POST /business/mention/hashtag/add/ ativa até 10 hashtags por pedido e 50 por conta, escolhidas entre as até 100 que /business/mention/hashtag/verify/list/ sugere, ou que contenham o identificador completo, como #drinktiktok faria para @TikTok. Uma hashtag ativada não pode ser removida durante sete dias, e as suas publicações chegam a /business/mention/hashtag/video/list/ 24 horas depois de ativada.
O que pode fazer o easyCoexistence com as menções do TikTok?
Entregue ao seu próprio código o token da conta: get_social_credentials devolve o token e o business_id para os caminhos da API for Business sob business/, incluindo business/mention/. O TikTok responde quando a conta e a aplicação cumprem os requisitos acima. Os webhooks de menções ficam fora deste acesso: o easyCoexistence subscreve a sua aplicação apenas a eventos de comentários e mantém os caminhos business/webhook/ para si, pelo que os eventos BRAND_MENTION não são reencaminhados. Os comentários nas publicações da própria conta, incluindo as menções, continuam a chegar como eventos comment.update, que set_social_webhook_destination reencaminha:
GET https://business-api.tiktok.com/open_api/v1.3/business/mention/comment/list/
?business_id=<BUSINESS_ID>
&fields=["item_id","comment_id","comment_text","commenter_display_name","comment_type"]
&sort_field=COMMENT_CREATE_TIME&max_count=50
Access-Token: <ACCESS_TOKEN>
POST https://business-api.tiktok.com/open_api/v1.3/business/comment/reply/create/
Access-Token: <ACCESS_TOKEN>
{ "business_id": "<BUSINESS_ID>", "video_id": "<ITEM_ID>", "comment_id": "<COMMENT_ID>", "text": "Thanks for the mention!" }Erros comuns
- Chamar os endpoints de Menções para uma conta sem Advanced Access. O TikTok só os serve a contas com Advanced Access ou com uma Verified Business Account, o que has_advanced_access em /business/get/ indica.
- Consultar menções logo após a meia-noite UTC. O TikTok atualiza os dados do dia anterior entre a meia-noite e as 7h UTC, pelo que uma consulta depois das 7h vê o dia inteiro.
- Ler um comment_id de 0 como um comentário. Num webhook de menções, significa que a menção está na legenda da publicação, com mention_type VIDEO_MENTION.
- Ativar uma hashtag de marca para a experimentar. O TikTok mantém uma hashtag ativada durante sete dias antes de poder ser removida, e ela conta para o limite de 50 da conta.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Pode a API do TikTok encontrar vídeos que mencionam a minha conta?
Sim, os que @mencionam o seu identificador na legenda. /business/mention/video/list/ devolve até 1.000 publicações públicas dos últimos 90 dias, com creator_handle_name a indicar cada criador.
As publicações privadas do TikTok contam como menções?
Não. A API de Menções conta apenas publicações públicas dos últimos 90 dias, e deixa de fora os autores menores ou de idade desconhecida: 17 anos ou menos na Europa, 12 anos ou menos nos EUA e noutras regiões.
Quanto tempo demora a aparecer uma menção no TikTok?
Cerca de 24 a 48 horas nos endpoints de listagem, e até duas ou três horas através do webhook de Menções.
Pode o easyCoexistence avisar-me quando a minha conta do TikTok for mencionada?
Não como evento reencaminhado, já que reencaminha os eventos de comentários do TikTok e não os de menções. O seu próprio código pode ler as menções a pedido, com o token de get_social_credentials, quando a conta se qualifica.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em