Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Mentions TikTok via l'API : trouver les publications et commentaires qui mentionnent un compte

L'API Mentions de TikTok, qui fait partie de l'API for Business, renvoie les 1 000 publications publiques les plus populaires des 90 derniers jours qui @mentionnent un compte professionnel dans leur légende, via GET /business/mention/video/list/, ainsi que les 1 000 commentaires ou réponses les plus populaires qui le mentionnent, via /business/mention/comment/list/. Les deux nécessitent le scope biz.brand.insights et un compte disposant d'un accès Advanced ou d'un compte professionnel vérifié.

easyCoexistence connecte un compte TikTok via l'API for Business de TikTok : Claude, ChatGPT ou votre propre code lisent ses commentaires et y répondent avec des outils dédiés et reçoivent ses événements de commentaire dès leur arrivée, et get_social_credentials donne à votre propre code le token pour d'autres appels de l'API for Business, endpoints Mentions compris là où TikTok les ouvre au compte.

1,000

Nombre maximal de publications mentionnées que renvoie /business/mention/video/list/, toutes publiques et des 90 derniers jours, jusqu'à 100 par requête.

24 to 48 hours

Délai approximatif entre une mention et sa disponibilité via l'API Mentions.

2 to 3 hours

Latence annoncée par TikTok pour le webhook de mention après qu'un utilisateur a mentionné l'entreprise dans une légende ou un commentaire.

Once a day

Fréquence recommandée par TikTok pour appeler chaque endpoint Mentions par compte, après l'actualisation de 0 h à 7 h UTC.

comment.list

Scope que /business/mention/comment/list/ requiert en plus de biz.brand.insights pour renvoyer les commentaires qui mentionnent le compte.

Quels endpoints compose l'API Mentions ?

Six endpoints de lecture, chacun en GET sur https://business-api.tiktok.com/open_api/v1.3, avec le token du compte dans l'en-tête Access-Token et son open_id comme business_id. Deux listent les mentions, deux résument ce que disent les publications mentionnées et deux récupèrent une seule mention annoncée par un 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

Quelles publications et quels commentaires comptent comme mentions ?

Ceux qui étiquettent le handle du compte avec @, dans la légende d'une publication ou dans le texte d'un commentaire, sur une publication publique, et qui passent les autres filtres de TikTok :

  • La publication a été mise en ligne au cours des 90 derniers jours.
  • Son auteur n'est pas mineur ni d'âge inconnu : 17 ans ou moins sont considérés comme mineurs en Europe, 12 ans ou moins aux États-Unis et dans les autres régions.
  • Elle figure parmi les 1 000 publications ou commentaires les plus appréciés qui mentionnent le handle.
  • Les publications de l'entreprise elle-même qui respectent ces règles comptent également.
  • Les commentaires composés uniquement de la mention, sans autre texte, sont classés plus bas.

De quoi un compte a-t-il besoin pour les utiliser ?

Un compte éligible, une application avec la bonne autorisation, les scopes sur le token et un jour d'attente après l'autorisation de l'application par le propriétaire :

  • Un accès Advanced ou un compte professionnel vérifié ; has_advanced_access sur /business/get/ indique quels comptes sont éligibles.
  • La permission Mentions sur l'application développeur, listée comme Mentions, Content pour les publications et Mentions, Comment pour les commentaires.
  • biz.brand.insights sur le token, plus comment.list pour les mentions dans les commentaires.
  • 24 heures après l'autorisation avant la première extraction, comme le demande le guide de démarrage de TikTok.

Comment lister les publications qui mentionnent le compte ?

Avec GET /business/mention/video/list/, le paramètre fields choisit les données : item_id et caption par défaut, plus create_time, video_link, likes, comments, shares, thumbnail_url, views, reach et creator_handle_name sur demande. sort_field accepte CREATE_TIME, LIKES, COMMENTS ou SHARES avec sort_type ASC ou DESC, number_of_days réduit les 90 jours, regions ne retient que les créateurs des régions choisies, et cursor avec has_more permet de paginer les résultats. views et reach valent null en dessous de 1 000, et les liens des miniatures restent valides 48 heures :

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
  }
}

Comment lister les commentaires qui mentionnent le compte ?

Avec GET /business/mention/comment/list/, dont le token a aussi besoin de comment.list. Par défaut, il renvoie comment_id et comment_text ; item_id, video_link, caption, video_likes, thumbnail_url, commenter_display_name, comment_type, comment_create_time et comment_likes s'obtiennent sur demande, et comment_type vaut COMMENT ou REPLY. Une page contient 10 éléments, sauf si max_count demande jusqu'à 100, triés par VIDEO_LIKES, COMMENT_CREATE_TIME ou COMMENT_LIKES. En raison des politiques de confiance et de sécurité de TikTok, une page peut revenir incomplète tout en ayant has_more à true.

Comment répondre à une mention ?

Par l'endpoint de réponse aux commentaires de TikTok. POST /business/comment/reply/create/ prend business_id, video_id défini sur l'item_id de la mention du commentaire, comment_id et un texte de 1 200 caractères au maximum ; la réponse apparaît publiquement sous ce commentaire, sur la publication qui le porte. La référence de TikTok nomme le scope comment.list.manage et la même exigence de compte pour celui-ci. Sa référence Mentions ne liste une réponse que pour les mentions de commentaires.

Les mentions peuvent-elles arriver par webhook ?

Oui. Avec la permission Mentions, une application appelle POST /business/webhook/update/ avec event_type BRAND_MENTION, puis TikTok envoie brand.mention.event dans les deux ou trois heures au plus suivant une mention, signé dans Tiktok-Signature comme ses autres webhooks. content est une chaîne JSON sérialisée contenant :

  • type_of_event : CREATE, EDIT ou PRIVACY_CHANGE pour une modification du paramètre de confidentialité d'une publication.
  • mention_type : COMMENT pour un commentaire ou une réponse, VIDEO_MENTION pour une légende, où comment_id vaut 0.
  • video_id, video_create_time, share_url et video_caption, qui décrivent la publication.
  • open_id_of_mentioned_user, unique_name_of_mentioned_user et unique_identifier, un ID d'auteur de commentaire qui reste le même d'une API à l'autre.
  • Les détails s'obtiennent via /business/mention/video/get/ ou /business/mention/comment/get/, dans les 48 heures suivant l'événement.

À quelle fréquence faut-il appeler les endpoints Mentions ?

Une fois par jour, par endpoint et par compte, après 7 h UTC : c'est le conseil de TikTok. Les endpoints partagent les limites globales de débit de l'application développeur, mais TikTok actualise les données de la veille entre minuit et 7 h UTC, et juge inutiles les extractions supplémentaires le même jour. Une nouvelle mention met aussi environ 24 à 48 heures pour atteindre les endpoints de liste, ce qui fait du webhook le signal le plus rapide.

Comment fonctionnent les hashtags de marque ?

Ils élargissent les mentions aux publications qui utilisent des hashtags choisis par l'entreprise. POST /business/mention/hashtag/add/ active jusqu'à 10 hashtags par requête et 50 par compte, pris parmi les 100 maximum que suggère /business/mention/hashtag/verify/list/, ou contenant le handle complet, comme #drinktiktok pour @TikTok. Un hashtag activé ne peut pas être retiré pendant sept jours, et ses publications apparaissent dans /business/mention/hashtag/video/list/ 24 heures après son activation.

Que peut faire easyCoexistence avec les mentions TikTok ?

Donnez à votre propre code le token du compte : get_social_credentials renvoie le token et le business_id pour les chemins de l'API for Business sous business/, dont business/mention/. TikTok répond lorsque le compte et l'application remplissent les conditions ci-dessus. Les webhooks de mention restent hors de ce périmètre : easyCoexistence abonne son application aux seuls événements de commentaire et garde pour lui les chemins business/webhook/, donc les événements BRAND_MENTION ne sont pas transmis. Les commentaires sur les publications du compte, mentions comprises, arrivent toujours sous forme d'événements comment.update, que set_social_webhook_destination transmet :

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!" }

Erreurs courantes

  • Appeler les endpoints Mentions pour un compte sans accès Advanced. TikTok ne les ouvre qu'aux comptes ayant un accès Advanced ou un compte professionnel vérifié, ce que signale has_advanced_access sur /business/get/.
  • Lancer des extractions juste après minuit UTC. TikTok actualise les données de la veille entre minuit et 7 h UTC : une extraction après 7 h voit toute la journée.
  • Lire un comment_id à 0 comme un commentaire. Dans un webhook de mention, cela signifie que la mention figure dans la légende de la publication, avec mention_type VIDEO_MENTION.
  • Activer un hashtag de marque pour l'essayer. TikTok garde un hashtag activé pendant sept jours avant de pouvoir le retirer, et il compte dans la limite de 50 du compte.
Faire cela avec EasyCoexistence

De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec les 3 premiers jours gratuits.

Questions fréquemment posées

L'API TikTok peut-elle trouver les vidéos qui mentionnent mon compte ?

Oui, celles qui @mentionnent son handle dans la légende. /business/mention/video/list/ renvoie jusqu'à 1 000 publications publiques des 90 derniers jours, avec creator_handle_name qui nomme chaque créateur.

Les publications TikTok privées comptent-elles comme mentions ?

Non. L'API Mentions ne compte que les publications publiques des 90 derniers jours et exclut les auteurs mineurs ou d'âge inconnu : 17 ans ou moins en Europe, 12 ans ou moins aux États-Unis et dans les autres régions.

Combien de temps faut-il pour qu'une mention TikTok apparaisse ?

Environ 24 à 48 heures via les endpoints de liste, et jusqu'à deux ou trois heures via le webhook de mention.

easyCoexistence peut-il m'alerter quand mon compte TikTok est mentionné ?

Pas sous forme d'événement transmis, car il transmet les événements de commentaire de TikTok et non les événements de mention. Votre propre code peut lire les mentions sur demande, avec le token de get_social_credentials, lorsque le compte y est éligible.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le