EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Marcar pessoas e adicionar localização a uma publicação do Instagram pela API

A API do Instagram marca pessoas com user_tags e adiciona um local com location_id, ambos definidos no contêiner de mídia antes da publicação. user_tags recebe nomes de usuário públicos, com coordenadas x e y de 0.0 a 1.0 obrigatórias em imagens; a Meta descreve o recurso para imagens, vídeos e Stories. location_id recebe o ID de uma Página com dados de localização, encontrado pela Pages Search API.

O easyCoexistence publica fotos, carrosséis, Reels e Stories com publish_instagram_post a partir do Claude, do ChatGPT ou do seu próprio código.

0.0 to 1.0

Intervalo das coordenadas x e y em user_tags, medidas a partir das bordas esquerda e superior da imagem.

Images

Onde user_tags exige x e y; são opcionais em Stories e se aplicam apenas a imagens e Stories.

Carousels

location_id não é suportado nas imagens ou vídeos dentro de um carrossel, segundo a referência de mídia da Meta.

USER_TAGGING_FAILURE

O valor config_issue quando a mídia é publicada sem as marcações de usuário, que a Meta chama de sucesso parcial.

13 Mar 2018

Quando a Meta abriu a marcação de locais e usuários públicos do Instagram em fotos publicadas pela API, primeiro para parceiros beta.

Como marcar pessoas em uma publicação?

Adicione user_tags ao contêiner. É um array de objetos, cada um com o nome de usuário de uma conta pública do Instagram e, em uma imagem, x e y: floats de 0.0 a 1.0 que indicam a distância da marcação até as bordas esquerda e superior. Um local vai em location_id na mesma chamada, e o contêiner é então publicado com media_publish, como de costume.

An image container with a user tag and a location
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>"
}

Quais publicações aceitam marcações de usuários e local?

A referência de mídia da Meta descreve user_tags para imagens, vídeos e Stories, com x e y aplicáveis apenas a imagens e Stories, e lista os parâmetros que cada contêiner aceita. Em um carrossel, o local vai no contêiner do carrossel, já que location_id não é suportado nas imagens ou vídeos dentro dele:

Imageuser_tags with x and y, and location_id
Reeluser_tags by username, and location_id
Storyuser_tags, with x and y optional; no location_id in its syntax
Carousel containerlocation_id, and no user_tags in its syntax
Carousel itemsNo location_id

Como encontrar um location_id?

Busque uma Página. location_id é o ID de uma Página associada a um local, e a referência da Meta aponta para a Pages Search API, GET /pages/search com q e fields=id,name,location, depois para a verificação de que a Página escolhida tem dados de localização. Uma Página sem eles falha com INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID. A busca roda na Graph API da Meta com o token do seu próprio app na Meta: um token de usuário ou, para informações públicas da Página, um token de app com o recurso Page Public Metadata Access.

Searching for a Page with a location
GET /pages/search
  ?q=<PLACE_NAME>
  &fields=id,name,location
  &access_token=<ACCESS_TOKEN>

O que acontece se uma marcação não for aplicada?

A publicação pode ir ao ar mesmo assim. media_publish então retorna config_issue definido como USER_TAGGING_FAILURE, o que significa que a mídia foi publicada sem as marcações de usuário. A Meta chama isso de sucesso parcial e pede que os apps tratem como um sinal para reconciliar, e não como erro, já que o ID da mídia é válido; publicar de novo criaria uma segunda publicação.

As marcações de usuário funcionam com o Instagram Login?

A referência de mídia da Meta lista user_tags e location_id para a criação de contêiner sem vinculá-los a um login específico. Já a página da API do Instagram com Instagram Login diz que essa configuração não pode acessar anúncios nem marcações, sem dizer qual marcação quer dizer. Antes de construir sobre qualquer um dos parâmetros com Instagram Login, publique uma publicação de teste e verifique a resposta e a própria publicação.

Como marcar pessoas pelo easyCoexistence?

Ainda não é possível. publish_instagram_post cria o contêiner sozinho e não recebe user_tags nem location_id, e os tokens do Instagram não são entregues para uma chamada própria. Publique o post com publish_instagram_post e depois adicione as marcações e o local no app do Instagram, pela opção Editar da publicação.

Erros comuns

  • Deixar x e y de fora em uma marcação de imagem. A Meta exige ambos em imagens; só Stories os tornam opcionais.
  • Informar coordenadas em pixels ou porcentagem. x e y são floats de 0.0 a 1.0, medidos a partir das bordas esquerda e superior.
  • Definir location_id em itens de carrossel. A Meta não suporta isso nas imagens ou vídeos dentro de um carrossel.
  • Marcar uma conta privada. user_tags aceita apenas nomes de usuário de contas públicas do Instagram.
Fazendo isso com o EasyCoexistence

A ferramenta não recebe user_tags nem location_id, então pessoas e lugares são marcados no app do Instagram, pela opção Editar da publicação. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Posso marcar uma conta privada do Instagram pela API?

Não. A referência de mídia da Meta diz que user_tags aceita nomes de usuário de contas públicas do Instagram, então uma conta privada não pode ser marcada dessa forma.

Quantas pessoas podem ser marcadas em uma publicação?

A referência da Meta para user_tags não informa máximo. O limite de 20 que ela indica é para marcações @ na legenda.

Posso adicionar um local a um Story pela API?

Não. A sintaxe da Meta para um contêiner de Story lista user_tags, mas não location_id.

Posso marcar um produto em vez de uma pessoa?

Marcações de produto são um recurso separado, que a visão geral da Meta lista como compatível com Facebook Login e Unified Login, e não com Instagram Login.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em