Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

1,000

A maioria das publicações mencionadas que /business/mention/video/list/ devolve, todas públicas e dos últimos 90 dias, até 100 por pedido.

24 to 48 hours

Atraso aproximado entre uma menção feita e a sua disponibilidade através da API de Menções.

2 to 3 hours

Latência que o TikTok indica para o webhook de menções depois de um utilizador mencionar a empresa numa legenda ou comentário.

Once a day

Frequência com que o TikTok recomenda chamar cada endpoint de Menções por conta, depois da atualização das 0h às 7h UTC.

comment.list

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:

/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

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

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 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 ou PRIVACY_CHANGE para uma alteração à definição de privacidade de uma publicação.
  • mention_type: COMMENT para um comentário ou resposta, VIDEO_MENTION para uma legenda, caso em que comment_id tem o valor 0.
  • video_id, video_create_time, share_url e video_caption, que descrevem a publicação.
  • open_id_of_mentioned_user, unique_name_of_mentioned_user e unique_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:

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 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.
Fazer isto com a EasyCoexistence

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