Ads

Impulsionar post do Instagram pela API pela API

POST /ads/boost transforma um post já publicado em anúncio, na conta que o cliente conectou. A mesma árvore do POST /ads (campanha, conjunto e anúncio), mas o criativo vem do post: texto e mídia não fazem parte do impulsionamento. Você não precisa implementar a API do Meta nem passar por revisão de app.

A chamada

POST /api/ads/boost?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "name": "Impulsionar post",
  "status": "active",
  "campaign": {
    "facebook_ads": {
      "objective": "engagement"
    }
  },
  "adset": {
    "budget": {
      "amount": 20,
      "type": "daily"
    },
    "targeting": {
      "countries": [
        "BR"
      ]
    },
    "facebook_ads": {
      "optimization_goal": "post_engagement",
      "billing_event": "impressions"
    }
  },
  "ad": {
    "post_id": "18191649508387596",
    "facebook_ads": {
      "instagram_account_id": "17841442920331135"
    }
  }
}

O que dá para fazer

  • Listar os posts que podem ser impulsionados em GET /ads/facebook_ads/posts.
  • Impulsionar um post criando campanha e conjunto novos, ou reaproveitando existentes com {"id": ...}.
  • Definir orçamento, país, otimização e cobrança do conjunto.
  • Pedir status active para ativar no último passo.
  • Informar link_url e call_to_action opcionais.

Regras e limites

  • Tudo é criado pausado e o status pedido é aplicado no último passo.
  • Idempotency-Key é obrigatório no header; repetir com a mesma chave devolve 200 com Idempotent-Replay: true.
  • ad.post_id vem de GET /ads/facebook_ads/posts. Sem o parâmetro source, a lista traz mídia do Instagram, a única que serve para impulsionar; com source=facebook a lista serve só para descoberta.
  • facebook_ads.instagram_account_id é obrigatório: é por ele que a posse do post é provada.
  • O criativo de um anúncio impulsionado não pode ser trocado depois: 422 boosted_creative_not_replaceable.
  • Se um passo falhar, o que foi criado é desfeito e repetir com a mesma chave retoma. A resposta é síncrona (201).

Campos principais

CampoTipoObrigatórioDescrição
namestringSimNome do anúncio, e dos níveis criados que não tiverem nome.
statusstringNãoEstado final da árvore (active ou paused). Tudo nasce pausado e é ativado no último passo.
campaignobjectNão{"id": ...} para uma campanha existente; sem id, descreve a que será criada.
adsetobjectSim{"id": ...} para um conjunto existente; sem id, descreve o que será criado (orçamento, público, otimização).
ad.post_idstringSimO post a impulsionar, vindo de GET /ads/facebook_ads/posts.
ad.facebook_ads.instagram_account_idstringSimA conta do Instagram dona do post. É por ela que a posse do post é provada.
ad.link_urlstringNãoURL de destino, quando aplicável.
ad.call_to_actionstringNãoBotão do anúncio. Valores em GET /ads/options.

Para quem

  • Botão Impulsionar no seu produto

    Mostre os posts do cliente e, com um clique, crie o impulsionamento com orçamento e público escolhidos.

  • Automação para posts de bom desempenho

    Quando um post passa de um limite de engajamento nas suas métricas, crie o impulsionamento automaticamente, pausado, para aprovação.

  • Agente de IA de social media

    O agente escolhe o post, propõe orçamento e público e o cria pausado para o gestor aprovar.

Funciona com

  • Meta Ads

Perguntas frequentes

Posso impulsionar posts do Facebook?

A lista de posts do Facebook (source=facebook) serve para descoberta, mas não para impulsionar. O impulsionamento usa mídia do Instagram.

Posso mudar o texto ou a imagem do anúncio impulsionado?

Não. O criativo vem do post, e trocá-lo responde 422 boosted_creative_not_replaceable.

O impulsionamento começa a gastar na hora?

Só se você enviar status active. Tudo nasce pausado e a ativação é o último passo.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.