Menções no TikTok pela API: posts e comentários que citam uma conta
A API de Menções do TikTok, parte da API for Business, retorna os 1.000 principais posts públicos dos últimos 90 dias que citam uma conta empresarial na legenda, pelo GET /business/mention/video/list/, e os 1.000 principais comentários ou respostas que a citam, por /business/mention/comment/list/. Ambos exigem o escopo biz.brand.insights e uma conta com Advanced Access ou uma Verified Business Account.
O easyCoexistence conecta uma conta do TikTok pela API for Business do TikTok: Claude, ChatGPT ou seu próprio código leem seus comentários e respondem a eles com ferramentas dedicadas e recebem os eventos de comentário conforme chegam, e get_social_credentials entrega 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 libera para a conta.
Posts por requisição que /business/mention/video/list/ retorna no máximo: todos públicos e dos últimos 90 dias, até 100.
Atraso aproximado entre uma menção ser feita e sua disponibilidade pela API de Menções.
Latência que o TikTok informa para o webhook de Menções depois que um usuário menciona a empresa em uma legenda ou comentário.
Frequência que o TikTok recomenda para chamar cada endpoint de Menções por conta, após a atualização entre 0h e 7h UTC.
O escopo /business/mention/comment/list/ exige, além de biz.brand.insights, para retornar comentários que mencionam a conta.
Quais endpoints a API de Menções tem?
Seis endpoints de leitura, cada um 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 seu open_id como business_id. Dois listam menções, dois resumem o que dizem os posts mencionados, e dois buscam uma única menção que um webhook anunciou:
Quais posts e comentários contam como menções?
Aqueles que marcam o nome de usuário da conta com @, na legenda de um post ou no texto de um comentário, em um post público, e que passam pelos outros filtros do TikTok:
- O post foi publicado nos últimos 90 dias.
- Seu autor não é menor de idade nem tem idade desconhecida: 17 anos ou menos conta como menor na Europa, 12 anos ou menos nos EUA e em outras regiões.
- Está entre os 1.000 posts, ou comentários, mais curtidos que citam o nome de usuário.
- Os posts da própria empresa que atendem a essas regras também contam.
- Comentários feitos apenas com a menção, sem outro texto, têm classificação mais baixa.
O que a conta precisa antes de usá-las?
Uma conta elegível, um app com a permissão certa, os escopos no token e um dia de espera depois que o dono autoriza o app:
- Advanced Access ou uma Verified Business Account;
has_advanced_accessem /business/get/ mostra quais contas se qualificam. - A permissão de Menções no app de desenvolvedor, listada como Mentions, Content para posts e Mentions, Comment para comentários.
- biz.brand.insights no token de acesso, mais comment.list para menções em comentários.
- 24 horas após a autorização antes da primeira consulta, como pede o guia de primeiros passos do TikTok.
Como listar os posts que citam a conta?
Com GET /business/mention/video/list/. fields escolhe os dados, com item_id e caption por padrão, além de create_time, video_link, likes, comments, shares, thumbnail_url, views, reach e creator_handle_name quando solicitados. sort_field aceita CREATE_TIME, LIKES, COMMENTS ou SHARES com sort_type ASC ou DESC, number_of_days restringe os 90 dias, regions mantém apenas criadores de regiões escolhidas, e cursor com has_more pagina os resultados. views e reach aparecem como null abaixo de 1.000, e os links de miniatura 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 citam a conta?
Com GET /business/mention/comment/list/, cujo token também precisa de comment.list. Por padrão retorna 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 quando solicitados, e comment_type traz COMMENT ou REPLY. Uma página tem 10 itens, salvo se max_count pedir até 100, ordenada por VIDEO_LIKES, COMMENT_CREATE_TIME ou COMMENT_LIKES. Por causa das políticas de confiança e segurança do TikTok, uma página pode vir incompleta enquanto has_more continua verdadeiro.
Como responder a uma menção?
Pelo endpoint de resposta a comentários do TikTok. POST /business/comment/reply/create/ recebe business_id, video_id definido como o item_id da menção no comentário, comment_id e um text de até 1.200 caracteres, e a resposta aparece publicamente abaixo daquele comentário, no post que o contém. A referência do TikTok cita o escopo comment.list.manage e o mesmo requisito de conta para ele. Sua referência de Menções lista a resposta apenas para menções em comentários.
As menções podem chegar por webhook?
Sim. Com a permissão de Menções, um app chama POST /business/webhook/update/ com event_type BRAND_MENTION, e o TikTok então envia brand.mention.event em até duas ou três horas após uma menção, assinado em Tiktok-Signature como seus outros webhooks. content é uma string JSON serializada contendo:
type_of_event: CREATE, EDIT ouPRIVACY_CHANGEpara uma mudança na configuração de privacidade de um post.mention_type: COMMENT para um comentário ou resposta,VIDEO_MENTIONpara uma legenda, caso em quecomment_idvale 0.video_id,video_create_time,share_urlevideo_caption, que descrevem o post.open_id_of_mentioned_user,unique_name_of_mentioned_usereunique_identifier, um ID do comentarista que permanece o mesmo em todas as APIs.- Os detalhes vêm de /business/mention/video/get/ ou /business/mention/comment/get/, em até 48 horas após o evento.
Com que frequência chamar os endpoints de Menções?
Uma vez por dia, por endpoint e por conta, depois das 7h UTC, é o conselho do TikTok. Os endpoints compartilham os limites globais de taxa do app de desenvolvedor, mas o TikTok atualiza os dados do dia anterior entre 0h e 7h UTC, e consultas adicionais no mesmo dia são desnecessárias. Uma nova menção também leva cerca de 24 a 48 horas para chegar aos endpoints de listagem, o que torna o webhook o sinal mais rápido.
Como funcionam as hashtags de marca?
Elas ampliam as menções para posts que usam hashtags escolhidas pela empresa. POST /business/mention/hashtag/add/ habilita até 10 hashtags por requisição e 50 por conta, tiradas das até 100 sugeridas por /business/mention/hashtag/verify/list/ ou que contenham o nome de usuário completo, como #drinktiktok faria para @TikTok. Uma hashtag habilitada não pode ser removida por sete dias, e seus posts chegam a /business/mention/hashtag/video/list/ 24 horas após ela ser habilitada.
O que o easyCoexistence pode fazer com 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 em business/, incluindo business/mention/. O TikTok responde quando a conta e o app atendem aos requisitos acima. Os webhooks de menção ficam de fora: o easyCoexistence assina apenas os eventos de comentário do seu app e mantém os caminhos business/webhook/ para si, então os eventos BRAND_MENTION não são encaminhados. Comentários nos próprios posts da conta, incluindo menções, continuam chegando como eventos comment.update, que set_social_webhook_destination encaminha:
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 os entrega a contas com Advanced Access ou Verified Business Account, o que has_advanced_access em /business/get/ informa.
- Consultar menções logo após a meia-noite UTC. O TikTok atualiza os dados do dia anterior entre 0h e 7h UTC, então uma consulta após as 7h enxerga o dia inteiro.
- Ler um comment_id de 0 como um comentário. Em um webhook de menção, isso significa que a menção está na legenda do post, com mention_type VIDEO_MENTION.
- Habilitar uma hashtag de marca para testar. O TikTok mantém uma hashtag habilitada por sete dias antes de poder removê-la, e ela conta para o limite de 50 da conta.
De US$ 9 até US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
A API do TikTok consegue encontrar vídeos que citam minha conta?
Sim, aqueles que mencionam o nome de usuário na legenda. /business/mention/video/list/ retorna até 1.000 posts públicos dos últimos 90 dias, com creator_handle_name identificando cada criador.
Posts privados do TikTok contam como menções?
Não. A API de Menções considera apenas posts públicos dos últimos 90 dias e deixa de fora autores menores de idade ou de idade desconhecida: 17 anos ou menos na Europa, 12 anos ou menos nos EUA e em outras regiões.
Quanto tempo uma menção no TikTok leva para aparecer?
Cerca de 24 a 48 horas pelos endpoints de listagem, e até duas ou três horas pelo webhook de Menções.
O easyCoexistence pode me avisar quando minha conta do TikTok for mencionada?
Não como evento encaminhado, já que ele encaminha os eventos de comentário do TikTok e não os eventos de menção. O seu próprio código pode ler menções sob demanda, com o token de get_social_credentials, quando a conta se qualifica.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em