Publicação de conteúdo

Com a Graph API do Instagram, você pode publicar imagens, vídeos ou reels individuais (publicações de mídia única) ou criar publicações contendo várias imagens, vídeos (publicações em carrossel) nas contas profissionais do Instagram.

A partir de 1º de julho de 2023, todos os vídeos únicos do feed publicados por meio da API de Publicação de Conteúdo do Instagram serão compartilhados como reels.

Requisitos

Tokens de acesso

Todas as solicitações devem incluir o token de acesso do usuário do app.

Permissões

A publicação é baseada em uma combinação das permissões a seguir. A combinação exata depende dos pontos de extremidade usados pelo app. Consulte nossas referências de ponto de extremidade para determinar quais permissões são necessárias.

Para que os usuários sem uma função no app ou na empresa que o obteve possam usar o produto, você precisará solicitar aprovação para cada uma das permissões via análise do app. Os usuários só poderão conceder permissões ao seu app depois que você fizer essa solicitação.

Servidor público

Criamos um cURL para mídias usadas em tentativas de publicação. Por isso, as mídias precisam estar hospedadas em um servidor acessível publicamente no momento da tentativa.

Autorização para publicação na Página

Em contas profissionais do Instagram vinculadas a uma Página que requer PPA (Autorização de Publicação na Página), não será possível fazer publicações enquanto a PPA não for obtida.

É possível que um usuário do app consiga executar tarefas em uma Página que inicialmente não tinha PPA, mas que começa a exigir essa autorização em um momento posterior. Nessa situação, o usuário do app fica impedido de publicar conteúdo na conta profissional do Instagram até obter a PPA. Já que não há como determinar se a Página de um usuário requer ou não PPA, recomendamos que você oriente os usuários do app a concluir o processo de autorização para prevenir problemas futuros.

Limitações

O único formato de imagem compatível é o JPEG. Não há compatibilidade com formatos derivados de JPEG, como MPO e JPS.
Não há compatibilidade com tags de compras.
Não há compatibilidade com tags de conteúdo de marca.
Não há compatibilidade com filtros.
Não há compatibilidade com publicações no Instagram TV.

Para ver outras limitações, consulte a referência de cada ponto de extremidade.

Limite de volume

Em um período de 24 horas, a API pode fazer no máximo 50 publicações por conta do Instagram. Os carrosséis contam como uma publicação. Esse limite é aplicado no ponto de extremidade POST /{ig-user-id}/media_publish a cada tentativa de publicação de um contêiner de mídia. Também recomendamos que seu app imponha o limite, principalmente se ele permitir que os usuários agendem publicações futuras.

Para verificar o uso atual do limite de volume de uma conta profissional do Instagram, consulte o ponto de extremidade GET /{ig-user-id}/content_publishing_limit.

Pontos de extremidade

A API consiste nos pontos de extremidade a seguir. Consulte o documento de referência dos pontos de extremidade para ver os requisitos de uso de cada um deles.

POST /{ig-user-id}/media: para carregar mídias e criar contêineres de mídia.
POST /{ig-user-id}/media_publish: para publicar mídias carregadas usando contêineres de mídia.
GET /{ig-container-id}?fields=status_code: para verificar a qualificação e o status da publicação do contêiner de mídia.
GET /{ig-user-id}/content_publishing_limit: para verificar o uso atual do limite de volume de publicações do usuário do app.

Publicações de mídia única

O processo de criação de publicações com imagens individuais, vídeos, story ou reels ocorre em duas etapas:

Use o ponto de extremidade POST /{ig-user-id}/media para criar o contêiner de uma imagem ou um vídeo hospedado no seu servidor público.
Use o ponto de extremidade POST /{ig-user-id}/media_publish para publicar o contêiner.

Etapa 1 de 2. Criar o contêiner

Digamos que você tem uma imagem em:

https://www.example.com/images/bronz-fonz.jpg

Você quer publicar a foto com a legenda "#BronzFonz". Envie uma solicitação para o ponto de extremidade POST /{ig-user-id}/media:

Exemplo de solicitação

POST https://graph.facebook.com/v20.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Retorna um ID do contêiner para a imagem.

Exemplo de resposta

{
  "id": "17889455560051444"  // IG Container ID
}

Etapa 2 de 2. Publicar o contêiner

Use o ponto de extremidade POST /{ig-user-id}/media_publish para publicar o ID do contêiner retornado na etapa anterior.

Exemplo de solicitação

POST https://graph.facebook.com/v20.0/17841400008460056/media_publish ?creation_id=17889455560051444

Exemplo de resposta

{
  "id": "17920238422030506" // IG Media ID
}

Publicações em carrossel

Você pode incluir até 10 itens, entre imagens, vídeos ou uma combinação das duas mídias, em uma única publicação (uma publicação em carrossel). O processo de publicação de carrosséis ocorre em três etapas:

Use o ponto de extremidade POST /{ig-user-id}/media para criar contêineres de itens individuais para cada imagem e vídeo que aparecerá no carrossel.
Use o ponto de extremidade POST /{ig-user-id}/media novamente para criar um contêiner de carrossel único para os itens.
Use o ponto de extremidade POST /{ig-user-id}/media_publish para publicar o contêiner de carrossel.

Para o limite de volume da conta, as publicações em carrossel contam como uma única publicação.

Limitações

Não é possível turbinar os carrosséis.
Os carrosséis podem ter no máximo 10 itens, entre imagens, vídeos ou uma combinação das duas mídias.
Todas as imagens do carrossel são cortadas com base na primeira escolhida. A taxa de proporção padrão é de 1:1.

Etapa 1 de 3. Criar o contêiner de item

Use o ponto de extremidade POST /{ig-user-id}/media para criar o contêiner de item para uma imagem ou um vídeo que aparecerá no carrossel. Os carrosséis podem ter até 10 itens, entre imagens, vídeos ou uma combinação das duas mídias.

POST /{ig-user-id}/media

Parâmetros

Os parâmetros a seguir são obrigatórios. Consulte a referência do ponto de extremidade POST /{ig-user-id}/media para conferir outros parâmetros compatíveis.

is_carousel_item: definido como true. Indica que a imagem ou o vídeo aparecerá em um carrossel.
image_url: (somente imagem) o caminho da imagem. Criaremos um cURL para a imagem a partir da URL fornecida, que deve estar em um servidor público.
media_type: (somente vídeo) definido como VIDEO. Indica que a mídia é um vídeo.
video_url: (somente vídeo) o caminho do vídeo. Criaremos um cURL para o vídeo a partir da URL fornecida, que deve estar em um servidor público.

Se a operação for bem-sucedida, a API retornará um ID do contêiner de item, que pode ser usado ao criar o contêiner de carrossel.

Repita esse processo para cada imagem ou vídeo que deve aparecer no carrossel.

Exemplo de solicitação

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Exemplo de resposta

{
  "id": "17899506308402767"
}

Etapa 2 de 3. Criar o contêiner de carrossel

Use o ponto de extremidade POST /{ig-user-id}/media para criar o contêiner de carrossel.

POST /{ig-user-id}/media

Parâmetros

Os parâmetros a seguir são obrigatórios. Consulte a referência do ponto de extremidade POST /{ig-user-id}/media para conferir outros parâmetros aceitos.

media_type: definido como CAROUSEL. Indica que o contêiner é destinado a um carrossel.
children: uma matriz com até 10 IDs de contêiner de cada imagem e vídeo que deve aparecer no carrossel publicado. Os carrosséis podem ter até 10 itens, entre imagens, vídeos ou uma combinação das duas mídias.

Exemplo de solicitação

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Exemplo de resposta

{
  "id": "18000748627392977"
}

Etapa 3 de 3. Publicar o contêiner de carrossel

Use o ponto de extremidade POST /{ig-user-id}/media_publish para publicar o contêiner de carrossel (uma publicação em carrossel). Em um período de 24 horas, as contas podem fazer no máximo 50 publicações. Publicar um carrossel conta como uma única publicação.

POST /{ig-user-id}/media_publish

Parâmetros

Os parâmetros a seguir são obrigatórios.

creation_id: o ID do contêiner de carrossel.

Se a operação for bem-sucedida, a API retornará um ID de mídia do Instagram para o álbum do carrossel.

Exemplo de solicitação

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Exemplo de resposta

{
  "id": "90010778390276"
}

Publicações no Reels

Os reels são vídeos curtos qualificados para aparecer na aba Reels do app Instagram se atenderem às especificações e forem selecionados pelo algoritmo. Para publicar um reel, siga as etapas de Publicações de mídia única e inclua o parâmetro media_type=REELS com o caminho do vídeo em video_url.

Os reels não são um novo tipo de mídia, apesar de você definir media_type=REELS ao publicá-los. Se você solicitar o campo media_type depois de publicar um reel, o valor será retornado como VIDEO. Para verificar se um vídeo publicado foi designado como reel, é preciso solicitar o campo media_product_type.

Você pode usar o código de exemplo do GitHub (insta_reels_publishing_api_sample) para saber como publicar reels no Instagram.

Para oferecer mais praticidade aos desenvolvedores, a Meta publicou o conjunto completo de chamadas da Graph API para Instagram Reels na plataforma de APIs Postman. Para saber mais, consulte Postman Collections for Facebook and Instagram Reels.

Para ver mais informações sobre Reels, consulte Developer Documentation for Reels.

Publicações de story

No momento, somente contas empresariais podem publicar stories usando a API de Publicação de Conteúdo.

Os Stories são vídeos e imagens publicados como stories no Instagram. Para publicar um story, execute as mesmas etapas para criar uma publicação de mídia individual e inclua o parâmetro media_type=STORIES junto com o caminho para a imagem/vídeo usando o parâmetro image_url ou video_url.

Observação: os stories não são um novo tipo de mídia, mesmo que você esteja definindo media_type=STORIES ao publicar um story. Se você solicitar o campo media_type após publicar um story, o valor será retornado como IMAGE/VIDEO. Para verificar se uma mídia de imagem/vídeo publicada foi designada como um story, será preciso solicitar o campo media_product_type.

Protocolo de carregamento retomável

O protocolo de carregamento retomável é um novo fluxo para publicação de conteúdo do Instagram que suporta carregamentos de vídeo para reels, stories em vídeo e itens de carrossel de vídeo media_types.

Esse novo protocolo suporta a criação de conteúdos multimídia do Instagram a partir de vídeos locais e de vídeos hospedados em URLs públicas. O protocolo permite retomar uma operação de carregamento de arquivos locais após uma interrupção na rede ou outra falha de transmissão, poupando tempo e largura de banda em caso de falhas de rede. Ele mantém as mesmas especificações de mídia.

Pontos de extremidade

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media — inicialize contêineres de criação de vídeo definindo upload_type=resumable.
POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id} — carregue o vídeo a partir de um arquivo de vídeo local ou de uma URL hospedada de forma mais confiável usando o protocolo de carregamento retomável.
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish — publique mídias carregadas usando contêineres de mídia.
GET /{ig-container-id}?fields=status_code — verifique a qualificação e o status da publicação do contêiner de mídia.

Dicas de codificação de URL HTML

Alguns parâmetros são suportados no formato lista/dict.
Alguns caracteres precisam ser codificados em um formato que possa ser transmitido pela internet. Por exemplo: user_tags=[{username:’ig_user_name’}] é codificado como user_tags=%5B%7Busername:ig_user_name%7D%5D, onde [ é codificado como %5B e { é codificado como %7B. Para ver mais conversões, consulte o padrão de codificação de URL HTML.

Etapa 1: inicializar uma sessão de carregamento para reels, stories em vídeo ou itens de carrossel

Exemplo de solicitação de reels

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

Exemplo de solicitação de story em vídeo

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Exemplo de solicitação de item de vídeo em carrossel

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Exemplo de resposta

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

Etapa 2: carregar o vídeo usando o protocolo de carregamento retomável

A maioria das chamadas da Graph API usam o host graph.facebook.com. No entanto, as chamadas para carregar vídeos para o Reels usam rupload.facebook.com.

As seguintes fontes de arquivos são suportadas para arquivos de vídeo carregados:

Um arquivo localizado no seu computador
Um arquivo hospedado em um servidor voltado para o público, como um CDN

Exemplo de solicitação para carregar um arquivo de vídeo local

Com o ig-container-id retornado a partir de uma chamada de sessão de carregamento retomável, carregue o vídeo.

O host precisa ser rupload.facebook.com.
Todos os media_type compartilham o mesmo fluxo para carregar o vídeo.
ig-container-id é a identificação retornada das chamadas de sessão de carregamento.
access-token é o mesmo usado nas etapas anteriores.
offset é definido como o primeiro byte a ser carregado, geralmente 0.
file_size é definido como o tamanho do seu arquivo em bytes.
Your_file_local_path é definido como o caminho do arquivo local; por exemplo, se você estiver carregando um arquivo a partir da pasta Downloads no macOS, o caminho será @Downloads/example.mov.

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Exemplo de solicitação para carregar um vídeo público hospedado

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

Exemplo de resposta

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Passo 3: (apenas para carrossel) criar contêineres de carrossel

Você pode reutilizar as etapas 1 e 2 para criar vários ig-container-ids com o parâmetro is_carousel_item definido como true. Em seguida, crie um contêiner de carrossel para incluir todos os itens do carrossel, que podem ser combinados com imagens e vídeos.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

Passo 4: publicar a mídia

Para reels e stories em vídeo, o {ig-container-id} criado na etapa 1 é usado para publicar o vídeo, e para o contêiner de carrossel, o {ig-container-id} criado na etapa 3 é usado para publicar esse contêiner.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

Etapa 5: obter o status de mídia

graph.facebook.com fornece um ponto de extremidade GET para ler o status do carregamento, e o campo video_status contém detalhes sobre o processo de carregamento local.

O uploading_phase informa se o arquivo foi carregado e quantos bytes foram transferidos.
O processing_phase contém os detalhes sobre o status do processamento de vídeo após o carregamento do arquivo de vídeo.

// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

Exemplo de resposta a partir do ponto de extremidade `graph.facebook.com`

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

Tags de colaborador

É possível adicionar usuários públicos do Instagram como colaboradores a uma imagem, um carrossel e um reel. Se você fizer isso, eles receberão um convite para serem colaboradores daquela mídia específica. Para marcar usuários em uma imagem, siga as etapas da seção Publicações de mídia única acima. No entanto, ao criar o contêiner de mídia, inclua o parâmetro "collaborators" e uma matriz de strings que indicam os nomes de usuário do Instagram das pessoas que você quer convidar para serem colaboradoras da mídia.

Exemplo de solicitação

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Notas

O valor de "collaborators" deve ser uma matriz de strings.
Somente usuários com contas públicas do Instagram podem ser marcados.
Não é possível adicionar mais do que 3 colaboradores a uma mídia.
Os colaboradores não podem ser adicionados a uma mídia de story.

Marcar a localização

Você pode usar a API de Pesquisa de Páginas (incluindo o campo "location" na sua consulta) para buscar Páginas com nomes correspondentes a uma string de pesquisa. Depois, analise os resultados e identifique as Páginas criadas para uma localização física. Se você incluir a identificação de uma Página ao publicar uma imagem ou um vídeo, a mídia será marcada com a localização associada a essa Página.

Limitações

Para receber marcações, uma Página precisa conter dados de localização sobre latitude e longitude.

Verifique se a Página que você quer usar tem dados de latitude e longitude na resposta. A tentativa de criação de um contêiner com uma Página sem dados de localização resultará em uma falha com o código de exceção INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Depois de obter a identificação da Página, atribua-a ao parâmetro location_id ao publicar contêineres de item de mídia única ou carrossel.

Tags de produto

É possível fazer publicações de mídias únicas ou de carrossel marcadas com produtos de uma Loja do Instagram. Para ver mais informações, consulte o guia Marcação de produto.

Marcar usuários

Você pode marcar usuários públicos do Instagram em uma imagem, e eles receberão uma notificação de que foram marcados.

Para marcar usuários em uma imagem, siga as etapas da seção Publicações de mídia única acima. No entanto, ao criar o contêiner de mídia, inclua o parâmetro user_tags e uma matriz de objetos que indicam os usuários do Instagram na imagem, bem como as coordenadas x/y deles na própria imagem.

Exemplo de solicitação

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

Isso retornará o ID do contêiner para você publicar usando o ponto de extremidade Publicação de mídia do usuário do Instagram.

Notas

O valor user_tags deve ser uma matriz de objetos formatados em JSON.
Somente usuários com contas públicas do Instagram podem ser marcados.
O objeto deve conter as três propriedades (username, x e y) para cada usuário.
Os valores x e y devem ser números float originados no canto superior esquerdo da imagem, com uma faixa de 0.0 a 1.0.
As marcações de usuários podem ser usadas com imagens em carrosséis.

Solução de problemas

Se você criar um contêiner para o vídeo, mas o ponto de extremidade POST /{ig-user-id}/media_publish não retornar o ID da mídia publicada, consulte o ponto de extremidade GET /{ig-container-id}?fields=status_code para obter o status de publicação do contêiner. O ponto de extremidade retornará um dos status a seguir:

EXPIRED: o contêiner não foi publicado dentro de 24 horas e expirou.
ERROR: o processo de publicação do contêiner não foi concluído.
FINISHED: o contêiner e o objeto de mídia estão prontos para publicação.
IN_PROGRESS: o processo de publicação do contêiner está em andamento.
PUBLISHED: o objeto de mídia do contêiner foi publicado.

Recomendamos consultar o status de um contêiner uma vez por minuto, por no máximo 5 minutos.

Erros

Consulte a referência de códigos de erro.

Publicação de conteúdo

Requisitos

Tokens de acesso

Permissões

Servidor público

Autorização para publicação na Página

Limitações

Limite de volume

Pontos de extremidade

Publicações de mídia única

Exemplo de solicitação

Exemplo de resposta

Exemplo de solicitação

Exemplo de resposta

Publicações em carrossel

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Publicações no Reels

Publicações de story

Protocolo de carregamento retomável

Pontos de extremidade

Dicas de codificação de URL HTML

Etapa 1: inicializar uma sessão de carregamento para reels, stories em vídeo ou itens de carrossel

Exemplo de solicitação de reels

Exemplo de solicitação de story em vídeo

Exemplo de solicitação de item de vídeo em carrossel

Exemplo de resposta

Etapa 2: carregar o vídeo usando o protocolo de carregamento retomável

Exemplo de solicitação para carregar um arquivo de vídeo local

Exemplo de solicitação para carregar um vídeo público hospedado

Exemplo de resposta

Passo 3: (apenas para carrossel) criar contêineres de carrossel

Passo 4: publicar a mídia

Etapa 5: obter o status de mídia

Exemplo de resposta a partir do ponto de extremidade graph.facebook.com

Tags de colaborador

Exemplo de solicitação

Notas

Marcar a localização

Limitações

Tags de produto

Marcar usuários

Exemplo de solicitação

Notas

Solução de problemas

Erros

Exemplo de resposta a partir do ponto de extremidade `graph.facebook.com`