EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

1,000

Posts por requisição que /business/mention/video/list/ retorna no máximo: todos públicos e dos últimos 90 dias, até 100.

24 to 48 hours

Atraso aproximado entre uma menção ser feita e sua disponibilidade pela API de Menções.

2 to 3 hours

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.

Once a day

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.

comment.list

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:

/business/mention/video/list/Up to 1,000 posts whose caption mentions the account, 100 a page
/business/mention/comment/list/Up to 1,000 comments or replies whose text mentions the account
/business/mention/top_word/list/The 20 keywords that appear most in mentioned posts' captions
/business/mention/top_hashtag/list/The 20 hashtags used most in those captions
/business/mention/video/get/One mentioned post from a webhook event, within 48 hours
/business/mention/comment/get/One comment mention from a webhook event, within 48 hours

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_access em /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:

Mentioned posts, sorted by likes
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 ou PRIVACY_CHANGE para uma mudança na configuração de privacidade de um post.
  • mention_type: COMMENT para um comentário ou resposta, VIDEO_MENTION para uma legenda, caso em que comment_id vale 0.
  • video_id, video_create_time, share_url e video_caption, que descrevem o post.
  • open_id_of_mentioned_user, unique_name_of_mentioned_user e unique_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:

Comment mentions and a reply, from your own code
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.
Fazendo isso com o EasyCoexistence

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