Menciones de TikTok por API: encontrar publicaciones y comentarios que mencionan una cuenta
La API de Menciones de TikTok, parte de la API for Business, devuelve las 1,000 publicaciones públicas principales de los últimos 90 días que mencionan una cuenta comercial en su descripción, mediante GET /business/mention/video/list/, y los 1,000 comentarios o respuestas principales que la mencionan, mediante /business/mention/comment/list/. Ambas requieren el scope biz.brand.insights y una cuenta con Advanced Access o una Verified Business Account.
easyCoexistence conecta una cuenta de TikTok mediante la API for Business de TikTok: Claude, ChatGPT o tu propio código leen sus comentarios y responden con herramientas dedicadas y reciben sus eventos de comentarios en cuanto llegan, y get_social_credentials entrega a tu propio código el token para otras llamadas de API for Business, incluidos los endpoints de Menciones donde TikTok los abre a la cuenta.
Publicaciones más mencionadas que devuelve /business/mention/video/list/, todas públicas y de los últimos 90 días, hasta 100 por petición.
Demora aproximada entre que se hace una mención y que está disponible en la Mentions API.
Latencia que TikTok indica para el webhook de menciones tras una mención del negocio en la descripción o en un comentario.
Frecuencia con la que TikTok recomienda llamar a cada endpoint de menciones por cuenta, después de la actualización de 0 a 7 am UTC.
El scope /business/mention/comment/list/ necesita, además de biz.brand.insights, para devolver los comentarios que mencionan la cuenta.
¿Qué endpoints tiene la Mentions API?
Seis endpoints de lectura, cada uno un GET a https://business-api.tiktok.com/open_api/v1.3 con el token de acceso de la cuenta en el encabezado Access-Token y su open_id como business_id. Dos listan menciones, dos resumen lo que dicen las publicaciones mencionadas y dos recuperan una única mención que anunció un webhook:
¿Qué publicaciones y comentarios cuentan como menciones?
Los que etiquetan el identificador de la cuenta con @, en la descripción de una publicación o en el texto de un comentario, en una publicación pública, y que superan los demás filtros de TikTok:
- La publicación se subió en los últimos 90 días.
- Su autor no es menor de edad ni tiene edad desconocida: 17 años o menos cuenta como menor en Europa, y 12 años o menos en EE. UU. y otras regiones.
- Está entre las 1,000 publicaciones o comentarios con más me gusta que mencionan el identificador.
- Las publicaciones propias del negocio que cumplan estas reglas también cuentan.
- Los comentarios formados solo por la mención, sin otro texto, se clasifican con menor prioridad.
¿Qué necesita una cuenta para usarlas?
Una cuenta elegible, una app con el permiso correcto, los scopes en el token y un día de espera tras la autorización del propietario:
- Advanced Access o una Verified Business Account;
has_advanced_accessen /business/get/ indica qué cuentas cualifican. - El permiso Mentions en la app de desarrollador, listado como Mentions, Content para publicaciones y Mentions, Comment para comentarios.
- biz.brand.insights en el token de acceso, más comment.list para las menciones en comentarios.
- 24 horas después de la autorización y antes de la primera consulta, como indica la guía de inicio de TikTok.
¿Cómo se listan las publicaciones que mencionan la cuenta?
Con GET /business/mention/video/list/. fields elige los datos: item_id y caption por defecto, y create_time, video_link, likes, comments, shares, thumbnail_url, views, reach y creator_handle_name bajo petición. sort_field acepta CREATE_TIME, LIKES, COMMENTS o SHARES con sort_type ASC o DESC, number_of_days acota los 90 días, regions filtra a creadores de las regiones elegidas, y cursor con has_more pagina los resultados. views y reach son null por debajo de 1,000, y los enlaces de miniaturas duran 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
}
}¿Cómo se listan los comentarios que mencionan la cuenta?
Con GET /business/mention/comment/list/, cuyo token también necesita comment.list. Por defecto devuelve comment_id y comment_text; item_id, video_link, caption, video_likes, thumbnail_url, commenter_display_name, comment_type, comment_create_time y comment_likes se piden expresamente, y comment_type vale COMMENT o REPLY. Una página contiene 10 salvo que max_count pida hasta 100, ordenada por VIDEO_LIKES, COMMENT_CREATE_TIME o COMMENT_LIKES. Por las políticas de confianza y seguridad de TikTok, una página puede llegar incompleta aunque has_more siga en true.
¿Cómo se responde a una mención?
Mediante el endpoint de respuesta a comentarios de TikTok. POST /business/comment/reply/create/ recibe business_id, video_id con el item_id de la mención en el comentario, comment_id y un text de hasta 1,200 caracteres, y la respuesta aparece públicamente bajo ese comentario, en la publicación que lo contenga. La referencia de TikTok menciona el scope comment.list.manage y el mismo requisito de cuenta para él. Su referencia de menciones solo lista una respuesta para las menciones en comentarios.
¿Pueden llegar las menciones por webhook?
Sí. Con el permiso Mentions, una app llama a POST /business/webhook/update/ con event_type BRAND_MENTION, y TikTok envía entonces brand.mention.event en un plazo de hasta dos o tres horas tras una mención, firmado en Tiktok-Signature como sus otros webhooks. content es una cadena JSON serializada que contiene:
type_of_event: CREATE, EDIT oPRIVACY_CHANGEpara un cambio en la privacidad de una publicación.mention_type: COMMENT para un comentario o respuesta,VIDEO_MENTIONpara la descripción, dondecomment_idvale 0.video_id,video_create_time,share_urlyvideo_caption, que describen la publicación.open_id_of_mentioned_user,unique_name_of_mentioned_useryunique_identifier, un ID del comentarista que se mantiene igual en todas las APIs.- Los detalles se obtienen de /business/mention/video/get/ o /business/mention/comment/get/, dentro de las 48 horas del evento.
¿Con qué frecuencia deben llamarse los endpoints de menciones?
Una vez al día por endpoint y cuenta, después de las 7 am UTC, es el consejo de TikTok. Los endpoints comparten los límites de tasa globales de la app de desarrollador, pero TikTok actualiza los datos del día anterior entre medianoche y las 7 am UTC, y considera innecesarias nuevas consultas dentro del mismo día. Una mención nueva también tarda entre 24 y 48 horas en llegar a los endpoints de listado, lo que hace del webhook la señal más rápida.
¿Cómo funcionan los hashtags de marca?
Amplían las menciones a publicaciones que usan hashtags que el negocio elige. POST /business/mention/hashtag/add/ activa hasta 10 hashtags por petición y 50 por cuenta, tomados de los hasta 100 que sugiere /business/mention/hashtag/verify/list/ o que contienen el identificador completo, como #drinktiktok para @TikTok. Un hashtag activado no puede eliminarse durante siete días, y sus publicaciones llegan a /business/mention/hashtag/video/list/ 24 horas después de activarlo.
¿Qué puede hacer easyCoexistence con las menciones de TikTok?
Entrega a tu propio código el token de la cuenta: get_social_credentials devuelve el token y el business_id para las rutas de API for Business bajo business/, incluidas business/mention/. TikTok responde cuando la cuenta y la app cumplen los requisitos anteriores. Los webhooks de menciones quedan fuera: easyCoexistence suscribe su app solo a eventos de comentarios y mantiene las rutas business/webhook/ para sí, así que los eventos BRAND_MENTION no se reenvían. Los comentarios en las publicaciones propias de la cuenta, incluidas las menciones, siguen llegando como eventos comment.update, que set_social_webhook_destination reenvía:
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!" }Errores comunes
- Llamar a los endpoints de menciones para una cuenta sin Advanced Access. TikTok los sirve a cuentas con Advanced Access o Verified Business Account, lo que informa has_advanced_access en /business/get/.
- Consultar menciones justo después de medianoche UTC. TikTok actualiza los datos del día anterior entre medianoche y las 7 am UTC, así que una consulta posterior a las 7 am ve el día completo.
- Leer un comment_id de 0 como un comentario. En un webhook de mención significa que la mención está en la descripción de la publicación, con mention_type VIDEO_MENTION.
- Activar un hashtag de marca para probarlo. TikTok mantiene un hashtag activado durante siete días antes de poder eliminarlo, y cuenta dentro de los 50 de la cuenta.
US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Puede la API de TikTok encontrar videos que mencionen mi cuenta?
Sí, los que mencionan su identificador con @ en la descripción. /business/mention/video/list/ devuelve hasta 1,000 publicaciones públicas de los últimos 90 días, con creator_handle_name indicando a cada creador.
¿Cuentan como menciones las publicaciones privadas de TikTok?
No. La Mentions API solo cuenta publicaciones públicas de los últimos 90 días y deja fuera a los autores menores de edad o de edad desconocida: 17 años o menos en Europa, y 12 años o menos en EE. UU. y otras regiones.
¿Cuánto tarda en aparecer una mención de TikTok?
Entre 24 y 48 horas a través de los endpoints de listado, y hasta dos o tres horas mediante el webhook de menciones.
¿Puede easyCoexistence avisarme cuando mencionan mi cuenta de TikTok?
No como evento reenviado, ya que reenvía los eventos de comentarios de TikTok y no los eventos de menciones. Tu propio código puede leer las menciones bajo petición, con el token de get_social_credentials, cuando la cuenta cualifica.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el