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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome do anúncio, e dos níveis criados que não tiverem nome. |
| status | string | Não | Estado final da árvore (active ou paused). Tudo nasce pausado e é ativado no último passo. |
| campaign | object | Não | {"id": ...} para uma campanha existente; sem id, descreve a que será criada. |
| adset | object | Sim | {"id": ...} para um conjunto existente; sem id, descreve o que será criado (orçamento, público, otimização). |
| ad.post_id | string | Sim | O post a impulsionar, vindo de GET /ads/facebook_ads/posts. |
| ad.facebook_ads.instagram_account_id | string | Sim | A conta do Instagram dona do post. É por ela que a posse do post é provada. |
| ad.link_url | string | Não | URL de destino, quando aplicável. |
| ad.call_to_action | string | Não | Botã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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
