Guia de anúncios

Como montar um rascunho de anúncio da Meta, com as combinações de objetivo, destino e meta de otimização e os formatos de criativo que a API aceita.

Um anúncio é publicado a partir de um rascunho: uma árvore com a campanha, o conjunto de anúncios e de 1 a 10 anúncios. A campanha define o objetivo, o conjunto define para onde a pessoa vai (o destino) e o que a Meta deve otimizar (a meta), e cada anúncio leva um criativo. A publicação cobra a taxa por anúncio do saldo, cria tudo pausado na Meta e só então liga.

GET /ads/options devolve as mesmas listas desta página (objetivos com destinos e metas, chamadas para ação por destino, posicionamentos, eventos de pixel e formatos). Use essa rota em vez de copiar as tabelas. Todas as rotas estão no grupo Anúncios da Referência da API.

Rotas principais

Método e caminhoPara que serve
GET /ads/optionsListas que a validação usa.
POST /ads/drafts/validateValida a árvore e devolve os problemas em issues, a taxa (fee) e o mínimo diário da Meta (budgetMinimum).
POST /ads/publishPublica a árvore enviada no corpo. Responde 201 com a publicação.
POST /ads/draftsGuarda um rascunho como está, mesmo incompleto.
PUT /ads/drafts/{id}Substitui a árvore. version é a versão lida.
POST /ads/drafts/{id}/publishPublica a versão conferida do rascunho guardado.
GET /ads/publish-jobs/{id}Acompanha uma publicação.

As rotas que recebem a árvore usam o corpo {"draft": ...}. Guardar um rascunho só confere a conta e os limites de tamanho; a validação completa acontece em POST /ads/drafts/validate e na publicação.

Estrutura do rascunho

CampoTipoRegra
adAccountIdstringObrigatório. Conta de anúncios do workspace.
identity.pageIdstringObrigatório. Página do Facebook que assina o anúncio.
identity.instagramUserIdstringObrigatório com o destino INSTAGRAM_DIRECT.
campaignobjetoname (obrigatório numa campanha nova, até 400 caracteres), objective, specialCategory, budget e bid. Com existingId, usa uma campanha que já existe.
adSetobjetoname, destination, goal, budget, bid, startAt, endAt, schedule, targeting, placements e os campos do destino. Com existingId, usa um conjunto que já existe.
adslistaDe 1 a 10 itens, cada um com name (opcional, até 400) e creative.
keepPausedbooleanoPublica sem ligar no fim; a publicação é ligada depois por POST /ads/publish-jobs/{id}/activate.

Objetivo, destino e meta

O par adSet.destination e adSet.goal precisa estar entre as rotas do campaign.objective. Fora delas, a validação devolve adSet.goal com not_for_objective.

ObjetivoDestinoMetas aceitas
OUTCOME_AWARENESSNONEREACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY
OUTCOME_TRAFFICWEBSITELANDING_PAGE_VIEWS, LINK_CLICKS, REACH, IMPRESSIONS
OUTCOME_TRAFFICWHATSAPP, MESSENGERLINK_CLICKS, REACH, IMPRESSIONS
OUTCOME_ENGAGEMENTON_POSTPOST_ENGAGEMENT, REACH
OUTCOME_ENGAGEMENTWEBSITEOFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS
OUTCOME_ENGAGEMENTWHATSAPP, MESSENGER, INSTAGRAM_DIRECTCONVERSATIONS, LINK_CLICKS
OUTCOME_LEADSON_AD (formulário instantâneo)LEAD_GENERATION, QUALITY_LEAD
OUTCOME_LEADSWEBSITEOFFSITE_CONVERSIONS, LINK_CLICKS
OUTCOME_LEADSWHATSAPPCONVERSATIONS
OUTCOME_SALESWEBSITEOFFSITE_CONVERSIONS, VALUE, LANDING_PAGE_VIEWS, LINK_CLICKS
OUTCOME_SALESCATALOGOFFSITE_CONVERSIONS, VALUE
OUTCOME_SALESWHATSAPP, MESSENGERCONVERSATIONS
OUTCOME_APP_PROMOTIONAPPAPP_INSTALLS, LINK_CLICKS

Cada destino pede os seus campos no conjunto:

DestinoCampos exigidos
WHATSAPPwhatsAppNumber com 8 a 15 dígitos (o que não é dígito é descartado).
INSTAGRAM_DIRECTidentity.instagramUserId. Os posicionamentos precisam incluir o Instagram.
MESSENGEROs posicionamentos precisam incluir o Facebook ou o Messenger.
APPappId e appStoreUrl (HTTPS).
CATALOGcatalogId e productSetId.
Metas OFFSITE_CONVERSIONS e VALUE (fora de CATALOG)pixelId e pixelEvent: PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATE_CHECKOUT, CONTACT, SCHEDULE ou SUBSCRIBE.

Orçamento, lance e público

AssuntoRegra
Orçamentobudget.kind é DAILY ou LIFETIME, e budget.amount é positivo, em unidades menores da moeda da conta. Vai na campanha ou no conjunto, nunca nos dois.
Orçamento totalLIFETIME exige adSet.endAt. schedule (dias de 0 a 6, horas cheias, no mínimo 1 hora) só vale com orçamento total.
Lancebid.strategy: LOWEST_COST_WITHOUT_CAP (padrão), LOWEST_COST_WITH_BID_CAP e COST_CAP (com amount) ou LOWEST_COST_WITH_MIN_ROAS (com roasFloor até 1000, só no conjunto e só com a meta VALUE). Sem orçamento na campanha, o lance da campanha fica no padrão; com orçamento na campanha, o lance do conjunto fica no padrão.
Categoria especialspecialCategory: NONE (padrão), HOUSING, EMPLOYMENT ou FINANCIAL_PRODUCTS_SERVICES. ISSUES_ELECTIONS_POLITICS é recusada com political_not_supported. Nas três aceitas, a idade fica de 18 a 65, sem gênero, sem exclusões e com raio de cidade de pelo menos 25 km.
Locaistargeting.locations: de 1 a 50, kind country (código de 2 letras), region ou city (raio opcional de 17 a 80 km).
Idade e gêneroageMin e ageMax de 13 a 65 (padrão 18 e 65). genders: 1 (masculino) e 2 (feminino).
Posicionamentosplacements.automatic: true é o padrão quando nenhuma plataforma é enviada. Manualmente: platforms entre facebook, instagram, messenger, audience_network e threads, positions por plataforma e devices mobile ou desktop.

Formatos de criativo

DestinoFormatos aceitos
ON_POSTEXISTING_POST
CATALOGCATALOG, COLLECTION
ON_AD, WEBSITE, APP, NONEIMAGE, VIDEO, CAROUSEL, FLEXIBLE, EXISTING_POST
WHATSAPP, MESSENGER, INSTAGRAM_DIRECTIMAGE, VIDEO, CAROUSEL, FLEXIBLE
FormatoCampos do criativo
IMAGE (padrão) e VIDEOprimaryText (obrigatório, até 2200) e media do tipo image ou video.
CAROUSELprimaryText e de 2 a 10 cards, cada um com media e, opcionalmente, headline, description e link.
FLEXIBLEDe 1 a 5 texts, até 5 headlines e 5 descriptions, e de 1 a 10 medias. Fora dos objetivos de vendas e de app, exige um conjunto novo com um único anúncio.
EXISTING_POSTpostId ou instagramMediaId, nunca os dois.
CATALOGprimaryText.
COLLECTIONprimaryText, instantExperienceId e media.

headline e description têm até 255 caracteres. media.mediaId é o id de uma imagem ou vídeo da biblioteca de mídia do workspace, ou meta: seguido do id de uma mídia que já está na Meta.

O destino completa o criativo:

DestinoRegra
WHATSAPP, MESSENGER, INSTAGRAM_DIRECTA chamada para ação é fixa (WHATSAPP_MESSAGE, MESSAGE_PAGE e INSTAGRAM_MESSAGE). greeting até 300 caracteres e até 3 iceBreakers de até 80.
WEBSITE, CATALOGlink HTTPS obrigatório (opcional no carrossel e não exigido em EXISTING_POST).
ON_ADleadFormId obrigatório, de um formulário ativo da página.
WEBSITE, CATALOG, APP, ON_ADcallToAction opcional, entre LEARN_MORE, SHOP_NOW, SIGN_UP, CONTACT_US, DOWNLOAD, BOOK_NOW, GET_OFFER, SUBSCRIBE, APPLY_NOW, ORDER_NOW, GET_QUOTE, WATCH_MORE e NO_BUTTON; APP aceita também INSTALL_MOBILE_APP. Sem valor, vale INSTALL_MOBILE_APP em APP, SIGN_UP em ON_AD, SHOP_NOW em CATALOG e LEARN_MORE nos outros.

Exemplo: conversa no WhatsApp

POST /ads/drafts/validate

{
  "draft": {
    "adAccountId": "5b0c8a52-6f3e-4d1a-9a7b-2c4d6e8f0a13",
    "identity": { "pageId": "104857600123456" },
    "campaign": {
      "name": "Promoção de novembro",
      "objective": "OUTCOME_ENGAGEMENT"
    },
    "adSet": {
      "destination": "WHATSAPP",
      "goal": "CONVERSATIONS",
      "whatsAppNumber": "5511987654321",
      "budget": { "kind": "DAILY", "amount": 5000 },
      "targeting": {
        "locations": [{ "kind": "country", "key": "BR", "name": "Brasil" }],
        "ageMin": 25,
        "ageMax": 55
      },
      "placements": { "automatic": true }
    },
    "ads": [
      {
        "creative": {
          "format": "IMAGE",
          "primaryText": "Fale com a gente pelo WhatsApp e garanta 20% de desconto.",
          "headline": "20% de desconto",
          "media": { "kind": "image", "mediaId": "9d2f6a1e-3b4c-4d5e-8f70-1a2b3c4d5e6f" },
          "greeting": "Olá! Quero saber da promoção.",
          "iceBreakers": ["Quais produtos estão em promoção?", "Vocês entregam na minha cidade?"]
        }
      }
    ]
  }
}

Erros

Na validação, os problemas voltam com status 200 em issues, cada um com field (o caminho, como ads[0].creative.media) e code. Além das regras desta página, a validação confere a conta, a página, o número e as mídias: por exemplo, adSet.whatsAppNumber com not_in_workspace ou not_linked_to_page, ads[0].creative.media com not_found e identity.pageId com lead_terms_not_accepted. Na publicação, a mesma árvore inválida responde 422 invalid_draft, com os problemas em expected:

{
  "error": true,
  "code": "invalid_draft",
  "message": "Há campos a corrigir",
  "expected": { "adSet.goal": "not_for_objective" }
}
CódigoStatusQuando
invalid_draft422A árvore tem campos a corrigir.
budget_below_minimum422A Meta recusou o orçamento por ficar abaixo do mínimo.
fee_not_charged, insufficient_balance402A taxa por anúncio não pôde ser cobrada do saldo.
draft_changed409Outra pessoa salvou o rascunho depois da versão enviada.
draft_publishing409O rascunho está sendo publicado ou já foi.
reconnect_required409A conta de anúncios precisa ser reconectada.