Menzioni TikTok tramite API: trovare post e commenti che menzionano un account
L'API Mentions di TikTok, parte dell'API for Business, restituisce i primi 1.000 post pubblici degli ultimi 90 giorni che menzionano un account aziendale nella didascalia, tramite GET /business/mention/video/list/, e i primi 1.000 commenti o risposte che lo menzionano, tramite /business/mention/comment/list/. Entrambi richiedono lo scope biz.brand.insights e un account con Advanced Access o un Verified Business Account.
easyCoexistence collega un account TikTok tramite l'API for Business di TikTok: Claude, ChatGPT o il tuo codice leggono i suoi commenti e rispondono con strumenti dedicati e ricevono gli eventi dei commenti appena arrivano, e get_social_credentials fornisce al tuo codice il token per le altre chiamate dell'API for Business, inclusi gli endpoint Mentions dove TikTok li apre all'account.
Post più menzionati restituiti da /business/mention/video/list/, tutti pubblici e degli ultimi 90 giorni, fino a 100 per richiesta.
Ritardo approssimativo tra una menzione e la sua disponibilità tramite l'API Mentions.
Latenza indicata da TikTok per il webhook delle menzioni, dopo che un utente menziona l'azienda in una didascalia o in un commento.
Frequenza consigliata da TikTok per chiamare ogni endpoint Mentions per account, dopo l'aggiornamento dalle 0 alle 7 UTC.
Scope che /business/mention/comment/list/ richiede oltre a biz.brand.insights per restituire i commenti che menzionano l'account.
Quali endpoint ha l'API Mentions?
Sei endpoint di sola lettura, ciascuno una GET su https://business-api.tiktok.com/open_api/v1.3 con il token di accesso dell'account nell'header Access-Token e il suo open_id come business_id. Due elencano le menzioni, due riassumono cosa dicono i post menzionati e due recuperano una singola menzione annunciata da un webhook:
Quali post e commenti contano come menzioni?
Quelli che taggano l'handle dell'account con @, nella didascalia di un post o nel testo di un commento, su un post pubblico, e che superano gli altri filtri di TikTok:
- Il post è stato pubblicato negli ultimi 90 giorni.
- Il suo autore non è minorenne né di età sconosciuta: 17 anni o meno contano come minorenni in Europa, 12 anni o meno negli Stati Uniti e in altre regioni.
- Rientra tra i primi 1.000 post, o commenti, più apprezzati che menzionano l'handle.
- Contano anche i post dell'azienda stessa che rispettano queste regole.
- I commenti composti solo dalla menzione, senza altro testo, vengono classificati più in basso.
Di cosa ha bisogno un account prima di usarle?
Un account idoneo, un'app con il permesso giusto, gli scope sul token e un giorno di attesa dopo che il proprietario autorizza l'app:
- Advanced Access o un Verified Business Account;
has_advanced_accesssu /business/get/ indica quali account si qualificano. - Il permesso Mentions sull'app di sviluppatore, elencato come Mentions, Content per i post e Mentions, Comment per i commenti.
- biz.brand.insights sul token di accesso, più comment.list per le menzioni nei commenti.
- 24 ore dopo l'autorizzazione prima del primo recupero, come chiede la guida introduttiva di TikTok.
Come si elencano i post che menzionano l'account?
Con GET /business/mention/video/list/. fields sceglie i dati: item_id e caption per impostazione predefinita, più create_time, video_link, likes, comments, shares, thumbnail_url, views, reach e creator_handle_name su richiesta. sort_field accetta CREATE_TIME, LIKES, COMMENTS o SHARES con sort_type ASC o DESC, number_of_days restringe i 90 giorni, regions limita ai creator delle regioni scelte, e cursor con has_more pagina i risultati. views e reach risultano null sotto 1.000, e i link alle miniature restano validi 48 ore:
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
}
}Come si elencano i commenti che menzionano l'account?
Con GET /business/mention/comment/list/, il cui token ha bisogno anche di comment.list. Per impostazione predefinita restituisce 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 arrivano su richiesta, e comment_type vale COMMENT o REPLY. Una pagina ne contiene 10, a meno che max_count non chieda fino a 100, ordinati per VIDEO_LIKES, COMMENT_CREATE_TIME o COMMENT_LIKES. Per le politiche di fiducia e sicurezza di TikTok, una pagina può tornare con meno elementi del previsto mentre has_more resta vero.
Come si risponde a una menzione?
Tramite l'endpoint di risposta ai commenti di TikTok. POST /business/comment/reply/create/ richiede business_id, video_id impostato sull'item_id della menzione nel commento, comment_id e un text fino a 1.200 caratteri, e la risposta compare pubblicamente sotto quel commento, sul post che lo contiene. Il riferimento di TikTok indica lo scope comment.list.manage e lo stesso requisito di account per usarlo. Il riferimento Mentions di TikTok prevede una risposta solo per le menzioni nei commenti.
Le menzioni possono arrivare tramite webhook?
Sì. Con il permesso Mentions, un'app chiama POST /business/webhook/update/ con event_type BRAND_MENTION, e TikTok invia poi brand.mention.event entro due o tre ore da una menzione, firmato in Tiktok-Signature come i suoi altri webhook. content è una stringa JSON serializzata che contiene:
type_of_event: CREATE, EDIT oPRIVACY_CHANGEper una modifica dell'impostazione di privacy di un post.mention_type: COMMENT per un commento o una risposta,VIDEO_MENTIONper una didascalia, dovecomment_idvale 0.video_id,video_create_time,share_urlevideo_caption, che descrivono il post.open_id_of_mentioned_user,unique_name_of_mentioned_usereunique_identifier, un ID di chi commenta che resta lo stesso tra le API.- I dettagli si ottengono da /business/mention/video/get/ o /business/mention/comment/get/, entro 48 ore dall'evento.
Con quale frequenza vanno chiamati gli endpoint Mentions?
Una volta al giorno per endpoint e per account, dopo le 7 UTC, è il consiglio di TikTok. Gli endpoint condividono i limiti di frequenza globali dell'app di sviluppatore, ma TikTok aggiorna i dati del giorno precedente tra la mezzanotte e le 7 UTC, e ulteriori richieste nella stessa giornata sono superflue. Una nuova menzione impiega anche circa 24 a 48 ore per arrivare agli endpoint di elenco, il che rende il webhook il segnale più rapido.
Come funzionano gli hashtag del brand?
Estendono le menzioni ai post che usano gli hashtag scelti dall'azienda. POST /business/mention/hashtag/add/ abilita fino a 10 hashtag per richiesta e 50 per account, presi dai fino a 100 suggeriti da /business/mention/hashtag/verify/list/ oppure che contengono l'handle completo, come farebbe #drinktiktok per @TikTok. Un hashtag abilitato non può essere rimosso per sette giorni, e i suoi post arrivano a /business/mention/hashtag/video/list/ 24 ore dopo l'abilitazione.
Cosa può fare easyCoexistence con le menzioni di TikTok?
Affida al tuo codice il token dell'account: get_social_credentials restituisce il token e il business_id per i percorsi dell'API for Business sotto business/, tra cui business/mention/. TikTok risponde quando account e app soddisfano i requisiti sopra. I webhook delle menzioni restano fuori: easyCoexistence iscrive la sua app solo agli eventi dei commenti e gestisce internamente i percorsi business/webhook/, quindi gli eventi BRAND_MENTION non vengono inoltrati. I commenti sui post dell'account, menzioni incluse, arrivano comunque come eventi comment.update, che set_social_webhook_destination inoltra:
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!" }Errori comuni
- Chiamare gli endpoint Mentions per un account senza Advanced Access. TikTok li offre agli account con Advanced Access o un Verified Business Account, che has_advanced_access su /business/get/ segnala.
- Recuperare le menzioni subito dopo la mezzanotte UTC. TikTok aggiorna i dati del giorno precedente tra la mezzanotte e le 7 UTC, quindi un recupero dopo le 7 vede l'intera giornata.
- Leggere un comment_id di 0 come un commento. In un webhook di menzione significa che la menzione è nella didascalia del post, con mention_type VIDEO_MENTION.
- Abilitare un hashtag del brand per provarlo. TikTok mantiene un hashtag abilitato per sette giorni prima che possa essere rimosso, e conta nel limite di 50 dell'account.
Da US$ 9 a US$ 0,75 per connessione al mese, con tariffa che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.
Domande frequenti
L'API di TikTok può trovare video che menzionano il mio account?
Sì, quelli che citano il suo handle con @ nella didascalia. /business/mention/video/list/ restituisce fino a 1.000 post pubblici degli ultimi 90 giorni, con creator_handle_name che indica ogni creator.
I post privati di TikTok contano come menzioni?
No. L'API Mentions conta solo i post pubblici degli ultimi 90 giorni, ed esclude gli autori minorenni o di età sconosciuta: 17 anni o meno in Europa, 12 anni o meno negli Stati Uniti e in altre regioni.
Quanto tempo impiega una menzione su TikTok a comparire?
Circa 24 a 48 ore tramite gli endpoint di elenco, e fino a due o tre ore tramite il webhook delle menzioni.
easyCoexistence può avvisarmi quando il mio account TikTok viene menzionato?
Non come evento inoltrato, perché inoltra gli eventi dei commenti di TikTok e non quelli delle menzioni. Il tuo codice può leggere le menzioni su richiesta, con il token di get_social_credentials, dove l'account si qualifica.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il