Etiquetar personas y añadir una ubicación a una publicación de Instagram mediante la API
La API de Instagram etiqueta personas con user_tags y añade un lugar con location_id, ambos definidos en el contenedor de medios antes de publicarlo. user_tags recibe nombres de usuario públicos, con coordenadas x e y de 0.0 a 1.0 obligatorias en las imágenes; Meta lo documenta para imágenes, videos y Stories. location_id acepta el ID de una Página con datos de ubicación, que se encuentra con la Pages Search API.
easyCoexistence publica fotos, carruseles, Reels y Stories con publish_instagram_post desde Claude, ChatGPT o tu propio código.
Rango de las coordenadas x e y en user_tags, medido desde los bordes izquierdo y superior de la imagen.
Dónde user_tags exige x e y; son opcionales en Stories, y solo se aplican a imágenes y Stories.
location_id no es compatible con las imágenes ni los videos dentro de un carrusel, según la referencia de medios de Meta.
El valor config_issue cuando el contenido se publica sin sus etiquetas de usuario, que Meta llama éxito parcial.
Cuándo Meta abrió el etiquetado de ubicaciones y de cuentas públicas de Instagram en fotos publicadas por API, primero a socios beta.
¿Cómo etiquetas a personas en una publicación?
Añade user_tags al contenedor. Es un array de objetos, cada uno con el nombre de usuario de una cuenta pública de Instagram y, en una imagen, x e y: números decimales de 0.0 a 1.0 que indican la distancia de la etiqueta a los bordes izquierdo y superior. Una ubicación va en location_id en la misma llamada, y el contenedor se publica después con media_publish como de costumbre.
POST /<IG_ID>/media
Content-Type: application/json
{
"image_url": "https://example.com/team.jpg",
"caption": "<CAPTION>",
"user_tags": [
{ "username": "<USERNAME>", "x": 0.42, "y": 0.61 }
],
"location_id": "<PAGE_ID>"
}¿Qué publicaciones admiten etiquetas de usuario y una ubicación?
La referencia de medios de Meta describe user_tags para imágenes, videos y Stories, con x e y aplicables solo a imágenes y Stories, y enumera los parámetros que admite cada contenedor. En un carrusel, la ubicación va en el contenedor del carrusel, ya que location_id no es compatible con las imágenes ni los videos que contiene:
¿Cómo encuentras un location_id?
Busca una Página. location_id es el ID de una Página asociada a una ubicación, y la referencia de Meta apunta a la Pages Search API, GET /pages/search con q y fields=id,name,location, y luego a comprobar que la Página elegida tiene datos de ubicación. Una Página sin ellos falla con INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID. La búsqueda se ejecuta en la Graph API de Meta con el token de tu propia app de Meta: un token de usuario o, para información pública de Página, un token de app con la función Page Public Metadata Access.
GET /pages/search
?q=<PLACE_NAME>
&fields=id,name,location
&access_token=<ACCESS_TOKEN>¿Qué pasa si una etiqueta no se adjunta?
La publicación puede salir igualmente. media_publish devuelve entonces config_issue con el valor USER_TAGGING_FAILURE, lo que significa que el contenido se publicó sin sus etiquetas de usuario. Meta lo llama éxito parcial y pide a las apps tratarlo como una señal para reconciliar, no como un error, ya que el ID del medio es válido; volver a publicar crearía una segunda publicación.
¿Funcionan las etiquetas de usuario con Instagram Login?
La referencia de medios de Meta enumera user_tags y location_id para crear contenedores sin vincularlos a un inicio de sesión concreto. Sin embargo, su página sobre la API de Instagram con Instagram Login dice que esa configuración no puede acceder a anuncios ni al etiquetado, sin indicar a cuál de los dos etiquetados se refiere. Antes de construir sobre cualquiera de los dos parámetros con Instagram Login, publica una prueba y revisa la respuesta y la publicación en sí.
¿Cómo etiquetas personas a través de easyCoexistence?
Todavía no se puede. publish_instagram_post crea el contenedor por sí mismo y no recibe user_tags ni location_id, y los tokens de Instagram no se entregan para una llamada propia. Publica la publicación con publish_instagram_post y después añade las etiquetas y la ubicación en la app de Instagram, desde la opción Editar de la publicación.
Errores comunes
- Omitir x e y en una etiqueta de imagen. Meta los exige en las imágenes; solo en Stories son opcionales.
- Dar coordenadas en píxeles o porcentaje. x e y son decimales de 0.0 a 1.0, medidos desde los bordes izquierdo y superior.
- Definir location_id en elementos de un carrusel. Meta no lo admite en las imágenes ni en los videos dentro de un carrusel.
- Etiquetar una cuenta privada. user_tags acepta solo nombres de usuario de cuentas públicas de Instagram.
La herramienta no recibe user_tags ni location_id, así que las personas y los lugares se etiquetan en la app de Instagram, desde la opción Editar de la publicación. De US$ 9 a US$ 0.75 por conexión al mes, con descenso al añadir conexiones, y los primeros 3 días gratis.
Preguntas frecuentes
¿Puedo etiquetar una cuenta privada de Instagram a través de la API?
No. La referencia de Meta para user_tags indica que solo acepta nombres de usuario de cuentas públicas de Instagram, así que una cuenta privada no puede etiquetarse de esta forma.
¿Cuántas personas se pueden etiquetar en una publicación?
La referencia de Meta para user_tags no indica un máximo. El límite de 20 que menciona es para las etiquetas @ en un pie de foto.
¿Puedo añadir una ubicación a una Story a través de la API?
No. La sintaxis de Meta para un contenedor de Story incluye user_tags, pero no location_id.
¿Puedo etiquetar un producto en lugar de una persona?
Las etiquetas de producto son una función aparte, que la descripción general de Meta indica como compatible con Facebook Login y Unified Login, no con Instagram Login.
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