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/optionsdevolve 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 caminho | Para que serve |
|---|---|
GET /ads/options | Listas que a validação usa. |
POST /ads/drafts/validate | Valida a árvore e devolve os problemas em issues, a taxa (fee) e o mínimo diário da Meta (budgetMinimum). |
POST /ads/publish | Publica a árvore enviada no corpo. Responde 201 com a publicação. |
POST /ads/drafts | Guarda um rascunho como está, mesmo incompleto. |
PUT /ads/drafts/{id} | Substitui a árvore. version é a versão lida. |
POST /ads/drafts/{id}/publish | Publica 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
| Campo | Tipo | Regra |
|---|---|---|
adAccountId | string | Obrigatório. Conta de anúncios do workspace. |
identity.pageId | string | Obrigatório. Página do Facebook que assina o anúncio. |
identity.instagramUserId | string | Obrigatório com o destino INSTAGRAM_DIRECT. |
campaign | objeto | name (obrigatório numa campanha nova, até 400 caracteres), objective, specialCategory, budget e bid. Com existingId, usa uma campanha que já existe. |
adSet | objeto | name, destination, goal, budget, bid, startAt, endAt, schedule, targeting, placements e os campos do destino. Com existingId, usa um conjunto que já existe. |
ads | lista | De 1 a 10 itens, cada um com name (opcional, até 400) e creative. |
keepPaused | booleano | Publica 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.
| Objetivo | Destino | Metas aceitas |
|---|---|---|
OUTCOME_AWARENESS | NONE | REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY |
OUTCOME_TRAFFIC | WEBSITE | LANDING_PAGE_VIEWS, LINK_CLICKS, REACH, IMPRESSIONS |
OUTCOME_TRAFFIC | WHATSAPP, MESSENGER | LINK_CLICKS, REACH, IMPRESSIONS |
OUTCOME_ENGAGEMENT | ON_POST | POST_ENGAGEMENT, REACH |
OUTCOME_ENGAGEMENT | WEBSITE | OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS |
OUTCOME_ENGAGEMENT | WHATSAPP, MESSENGER, INSTAGRAM_DIRECT | CONVERSATIONS, LINK_CLICKS |
OUTCOME_LEADS | ON_AD (formulário instantâneo) | LEAD_GENERATION, QUALITY_LEAD |
OUTCOME_LEADS | WEBSITE | OFFSITE_CONVERSIONS, LINK_CLICKS |
OUTCOME_LEADS | WHATSAPP | CONVERSATIONS |
OUTCOME_SALES | WEBSITE | OFFSITE_CONVERSIONS, VALUE, LANDING_PAGE_VIEWS, LINK_CLICKS |
OUTCOME_SALES | CATALOG | OFFSITE_CONVERSIONS, VALUE |
OUTCOME_SALES | WHATSAPP, MESSENGER | CONVERSATIONS |
OUTCOME_APP_PROMOTION | APP | APP_INSTALLS, LINK_CLICKS |
Cada destino pede os seus campos no conjunto:
| Destino | Campos exigidos |
|---|---|
WHATSAPP | whatsAppNumber com 8 a 15 dígitos (o que não é dígito é descartado). |
INSTAGRAM_DIRECT | identity.instagramUserId. Os posicionamentos precisam incluir o Instagram. |
MESSENGER | Os posicionamentos precisam incluir o Facebook ou o Messenger. |
APP | appId e appStoreUrl (HTTPS). |
CATALOG | catalogId 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
| Assunto | Regra |
|---|---|
| Orçamento | budget.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 total | LIFETIME exige adSet.endAt. schedule (dias de 0 a 6, horas cheias, no mínimo 1 hora) só vale com orçamento total. |
| Lance | bid.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 especial | specialCategory: 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. |
| Locais | targeting.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ênero | ageMin e ageMax de 13 a 65 (padrão 18 e 65). genders: 1 (masculino) e 2 (feminino). |
| Posicionamentos | placements.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
| Destino | Formatos aceitos |
|---|---|
ON_POST | EXISTING_POST |
CATALOG | CATALOG, COLLECTION |
ON_AD, WEBSITE, APP, NONE | IMAGE, VIDEO, CAROUSEL, FLEXIBLE, EXISTING_POST |
WHATSAPP, MESSENGER, INSTAGRAM_DIRECT | IMAGE, VIDEO, CAROUSEL, FLEXIBLE |
| Formato | Campos do criativo |
|---|---|
IMAGE (padrão) e VIDEO | primaryText (obrigatório, até 2200) e media do tipo image ou video. |
CAROUSEL | primaryText e de 2 a 10 cards, cada um com media e, opcionalmente, headline, description e link. |
FLEXIBLE | De 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_POST | postId ou instagramMediaId, nunca os dois. |
CATALOG | primaryText. |
COLLECTION | primaryText, 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:
| Destino | Regra |
|---|---|
WHATSAPP, MESSENGER, INSTAGRAM_DIRECT | A chamada para ação é fixa (WHATSAPP_MESSAGE, MESSAGE_PAGE e INSTAGRAM_MESSAGE). greeting até 300 caracteres e até 3 iceBreakers de até 80. |
WEBSITE, CATALOG | link HTTPS obrigatório (opcional no carrossel e não exigido em EXISTING_POST). |
ON_AD | leadFormId obrigatório, de um formulário ativo da página. |
WEBSITE, CATALOG, APP, ON_AD | callToAction 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ódigo | Status | Quando |
|---|---|---|
invalid_draft | 422 | A árvore tem campos a corrigir. |
budget_below_minimum | 422 | A Meta recusou o orçamento por ficar abaixo do mínimo. |
fee_not_charged, insufficient_balance | 402 | A taxa por anúncio não pôde ser cobrada do saldo. |
draft_changed | 409 | Outra pessoa salvou o rascunho depois da versão enviada. |
draft_publishing | 409 | O rascunho está sendo publicado ou já foi. |
reconnect_required | 409 | A conta de anúncios precisa ser reconectada. |