iron-edge 2.33.1 → 2.35.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -3
- package/agents/iron-paidmedia.md +3 -1
- package/agents/iron-spy.md +2 -2
- package/iron-routing-map.md +1 -1
- package/package.json +2 -2
- package/skills/anuncios/SKILL.md +1 -1
- package/skills/brandkit/SKILL.md +5 -5
- package/skills/minerar/SKILL.md +6 -4
- package/skills/subir-anuncio/SKILL.md +307 -0
- package/skills/subir-anuncio/references/copy-e-nomes.md +80 -0
- package/skills/subir-anuncio/references/estrutura-meta.md +244 -0
- package/skills/subir-anuncio/templates/painel.html +654 -0
- package/skills/subir-anuncio/templates/plano.json +100 -0
- package/skills/trilha/steps/loja.md +2 -1
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# copy-e-nomes — como nomear e como escrever a peça
|
|
2
|
+
|
|
3
|
+
Referência de consulta da skill `subir-anuncio`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Convenção de nome
|
|
8
|
+
|
|
9
|
+
O nome é o único campo que a API lê **e** um humano também. Por isso **o que vence vai no nome**.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
campanha: <negócio> - <objetivo> - <oferta> - MM/AA
|
|
13
|
+
conjunto: <público> - <otimização> - <destino>
|
|
14
|
+
anúncio: <produto> - <ângulo> - <formato> - DD/MM
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Exemplos:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
campanha: Loja X - vendas - coleção verão - 09/26
|
|
21
|
+
conjunto: Brasil 25-45 - conversões - site
|
|
22
|
+
anúncio: Tênis Alfa - prova - vídeo 9x16 - 15/09
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Regras:
|
|
26
|
+
- **Data no nome do anúncio quando a peça vence** (atendimento, turma, promoção com prazo). Peça sempre-verde não leva data, e isso é normal.
|
|
27
|
+
- Duas datas no nome ("11 e 12/09") vencem na ÚLTIMA.
|
|
28
|
+
- O nome não substitui a arte: a data no nome pode divergir da data dentro da imagem. Conferir a arte é passo humano.
|
|
29
|
+
- Renomear peça antiga zera o `updated_time` dela e a faz parecer nova para quem lê a conta (a skill `anuncios` inclusive). Renomeie com intenção.
|
|
30
|
+
- Se o negócio já usa outra convenção, **mantenha a dele** e adapte a leitura. Convenção nova se propõe, não se impõe.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 2. Os quatro campos de texto
|
|
35
|
+
|
|
36
|
+
| Campo no MCP | O que é | Tamanho que costuma caber |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| `message` | texto primário, acima da mídia | as 2 primeiras linhas aparecem antes do "ver mais" |
|
|
39
|
+
| `headline` | título, abaixo da mídia, em negrito | curtíssimo, some rápido no celular |
|
|
40
|
+
| `description` | descrição sob o título | nem sempre aparece; nunca ponha aí o que é essencial |
|
|
41
|
+
| `call_to_action_type` | o botão | valor de lista fechada, não texto livre |
|
|
42
|
+
|
|
43
|
+
O limite exato varia por posicionamento e muda sem aviso. Em vez de decorar número: **escreva o essencial nas duas primeiras linhas do `message`** e trate `headline` e `description` como reforço.
|
|
44
|
+
|
|
45
|
+
CTA mais usados: `SHOP_NOW`, `BUY_NOW`, `LEARN_MORE`, `SIGN_UP`, `GET_QUOTE`, `WHATSAPP_MESSAGE`, `MESSAGE_PAGE`, `BOOK_NOW`, `APPLY_NOW`, `DOWNLOAD`, `CONTACT_US`, `GET_OFFER`, `SUBSCRIBE`. Escolha pelo rótulo que o dono usaria, não pelo que soa mais forte.
|
|
46
|
+
|
|
47
|
+
⛔ **Valor fora da lista da API é recusado.** Não deduza o nome pelo texto do botão: para mandar mensagem os valores reais são `WHATSAPP_MESSAGE` e `MESSAGE_PAGE` (não existe `SEND_MESSAGE`). Na dúvida, confira a lista de `call_to_action_type` na descrição de `ads_create_creative` antes de usar.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Como escrever
|
|
52
|
+
|
|
53
|
+
- **O que a ficha não diz, o anúncio não promete.** Preço, prazo, garantia, resultado, número de clientes: só entra na peça o que está na ficha do negócio ou o dono confirmou nesta sessão. Faltando, escreva `[PREENCHER: ...]` e leve como decisão aberta no painel. Dado inventado em anúncio é risco jurídico e queima conta.
|
|
54
|
+
- **Específico vence esperto.** "Entrega em 48 h em toda a capital" vale mais que "agilidade que você merece".
|
|
55
|
+
- **Voz ativa, e o botão diz o que acontece.** "Falar no WhatsApp", não "Saiba mais" quando o destino é conversa. O mesmo nome do produto segue até o fim: anúncio, página e checkout.
|
|
56
|
+
- **A primeira linha carrega a oferta.** O resto do texto é para quem já parou.
|
|
57
|
+
- Sem emoji como marcador de lista. Sem travessão. Sem "eleve", "desbloqueie", "transforme", "não perca". Sem caixa alta gritada.
|
|
58
|
+
- Uma promessa por peça. Anúncio que promete três coisas não é lembrado por nenhuma.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 4. Regras que valem em toda peça
|
|
63
|
+
|
|
64
|
+
1. **Peça permanente não leva data nem preço** que mudam. A peça fica mentindo na tela depois que a promoção acaba, e ninguém lembra de tirar.
|
|
65
|
+
2. **Data na copy e data na arte mudam no mesmo passo.** Trocar uma e esquecer a outra é o defeito mais comum da troca de criativo.
|
|
66
|
+
3. **Um destino só, o mesmo em tudo.** O número de WhatsApp escrito na copy, o da arte e o que está ligado à Página têm que ser o mesmo número. Confira os três.
|
|
67
|
+
4. **Setor regulado tem regra própria** (saúde, estética, finanças, crédito, emagrecimento, emprego), às vezes com conselho de classe. Avise o dono antes de publicar; a responsabilidade é dele, mas o aviso é seu.
|
|
68
|
+
5. **Palavras proibidas da ficha do negócio** passam por cima de qualquer sugestão sua.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 5. Antes de dar a copy por pronta
|
|
73
|
+
|
|
74
|
+
- [ ] Toda afirmação sai da ficha, do dono ou de uma campanha antiga real?
|
|
75
|
+
- [ ] A oferta está nas duas primeiras linhas do texto primário?
|
|
76
|
+
- [ ] O CTA descreve o que acontece ao clicar, e bate com o destino do conjunto?
|
|
77
|
+
- [ ] Data, preço e número aparecem iguais na copy, na arte e no destino?
|
|
78
|
+
- [ ] Alguma promessa fora do que o negócio entrega hoje?
|
|
79
|
+
- [ ] Trocando o nome do produto, o texto serviria para qualquer concorrente? Então falta o que só este negócio pode dizer.
|
|
80
|
+
- [ ] Restou algum `[PREENCHER: ...]`? Ele vai como decisão aberta no painel, não como texto publicado.
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# estrutura-meta — o que a API aceita, e onde ela recusa
|
|
2
|
+
|
|
3
|
+
Referência de consulta da skill `subir-anuncio`.
|
|
4
|
+
|
|
5
|
+
**Duas proveniências, e a diferença importa.** O que está marcado **[schema]** foi lido na descrição das ferramentas `ads_*` do MCP do Meta (conferido de novo em 11/11/2026). O que está marcado **[medido em DD/MM/AAAA]** foi observado rodando de verdade, criando, publicando e apagando objetos numa conta de teste, com início agendado para 30 dias à frente e gasto zero conferido por leitura. O que o schema diz e ninguém mediu está marcado **[schema, não medido]**. O primeiro envelhece quando o Meta muda a ferramenta; o medido envelhece quando o Meta muda o comportamento, sem aviso e sem nada na documentação mudar. Onde os dois divergiram, vale o medido, e a divergência está escrita.
|
|
6
|
+
|
|
7
|
+
Schema muda: quando uma chamada for recusada por um campo que este arquivo dá como certo, **a resposta da ferramenta manda, não este texto** — e a correção vem para cá.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 0. Modo rascunho (o que muda tudo na hora de criar)
|
|
12
|
+
|
|
13
|
+
Em algumas contas o conector do Meta está em **modo rascunho**: `ads_create_campaign`, `ads_create_ad_set` e `ads_create_ad` não criam nada de verdade, só montam o rascunho do Gerenciador da conta. Como saber: **a resposta do `ads_create_campaign` traz `status: "DRAFT"`** [schema; medido em 11/11/2026]. Sem isso, a conta está no modo ao vivo e os objetos nascem `PAUSED` [medido em 08/09/2026].
|
|
14
|
+
|
|
15
|
+
O que foi medido em 11/11/2026, numa conta com modo rascunho:
|
|
16
|
+
|
|
17
|
+
| Passo | O que acontece |
|
|
18
|
+
|---|---|
|
|
19
|
+
| Criar campanha, conjunto, anúncio | cada um volta `status: "DRAFT"` e um id; o rascunho guarda **`status ACTIVE`** preparado em todos. A leitura normal (`ads_get_ad_entities` sem `object_state`) **não acha** a campanha; com `object_state: "draft"` ela aparece em `ad_drafts`, com `action: "add"`, `values.status.new = "ACTIVE"` e `active_errors` |
|
|
20
|
+
| Criar criativo | **não passa pelo rascunho**: `ads_create_creative` cria na hora e devolve o `creative_id` |
|
|
21
|
+
| Publicar sem `publish_as_active` | `ads_activate_entity` na campanha → `PUBLISHING` (assíncrono); segundos depois, campanha `ACTIVE` e anúncio `ACTIVE` em análise. **Publicar o rascunho como veio põe tudo no ar.** O schema diz que o publicar "preserva o status preparado", e o status preparado é `ACTIVE`: os dois textos do schema estão certos, quem engana é o padrão |
|
|
22
|
+
| Preparar `PAUSED` antes de publicar | `ads_update_entity {"status":"PAUSED"}` em campanha, conjunto e anúncio (cada um volta `is_draft: true`); publicar sem `publish_as_active` → os três publicados em `PAUSED`. **É a receita da skill** |
|
|
23
|
+
| Erro bloqueante no rascunho | aparece em `active_errors` do objeto; o publicar recusa o lote inteiro: "Nothing was published because of blocking validation errors" |
|
|
24
|
+
| Ativar objeto já publicado | `ads_activate_entity` responde `ACTIVE` na hora; ativar a campanha **não** ativou o conjunto |
|
|
25
|
+
| Pausar objeto já publicado | `{"status":"PAUSED"}` sozinho vale ao vivo na hora (`is_draft: false`) |
|
|
26
|
+
| `{"status":"DELETED"}` em objeto publicado | **fica preparado** (`is_draft: true`) e o objeto segue como estava; só apaga publicando esses objetos com `ads_activate_entity` (`entity_id` = a campanha, `entity_type: "campaign"`, `object_ids` = os ids; o schema exige `entity_id` mesmo com `object_ids`). Assim a campanha se apagou pelo conector |
|
|
27
|
+
| Descartar rascunho nunca publicado | `discard_draft_changes: true` → prévia (`discard_preview`) + `confirmation_token`; segunda chamada com o token → `draft_changes_discarded: true`, a campanha some com os filhos |
|
|
28
|
+
|
|
29
|
+
Não medido: `publish_as_active: true`, `allow_partial_publish`, `ignore_validation_errors` [schema, não medido]. Pelo schema, `publish_as_active` ativa só o objeto do `entity_id`; os outros publicados junto ficam com o status preparado.
|
|
30
|
+
|
|
31
|
+
O rascunho é por usuário: lista o que ESTE login montou, não o que outra pessoa montou na mesma conta [schema].
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 1. Objetivo da campanha (`ads_create_campaign`)
|
|
36
|
+
|
|
37
|
+
Só valores ODAX. Objetivo antigo (`LINK_CLICKS`, `CONVERSIONS`, `REACH`, `LEAD_GENERATION`, `APP_INSTALLS`, `VIDEO_VIEWS`, `BRAND_AWARENESS`) é recusado com erro de validação.
|
|
38
|
+
|
|
39
|
+
| O dono diz | `objective` |
|
|
40
|
+
|---|---|
|
|
41
|
+
| "quero vender no meu site / na loja" | `OUTCOME_SALES` |
|
|
42
|
+
| "quero contato, orçamento, cadastro" | `OUTCOME_LEADS` |
|
|
43
|
+
| "quero conversa no WhatsApp / Direct" | `OUTCOME_SALES` ou `OUTCOME_ENGAGEMENT` com destino de mensagem |
|
|
44
|
+
| "quero visita no site / no perfil" | `OUTCOME_TRAFFIC` |
|
|
45
|
+
| "quero que conheçam a marca" | `OUTCOME_AWARENESS` |
|
|
46
|
+
| "quero instalação do meu aplicativo" | `OUTCOME_APP_PROMOTION` |
|
|
47
|
+
|
|
48
|
+
Obrigatórios no create: `ad_account_id`, `campaign_name`, `objective`, `buying_type` (use `AUCTION`). `special_ad_categories` vai como string JSON, `"[]"` quando não há categoria (seção 12).
|
|
49
|
+
No rascunho, o objetivo aparece com o nome antigo (`OUTCOME_TRAFFIC` foi lido de volta como `LINK_CLICKS` em `values.objective.new`) [medido em 11/11/2026]. É só a gravação interna: na criação, continue mandando ODAX.
|
|
50
|
+
|
|
51
|
+
**A resposta do create traz `valid_optimization_goals` e `recommended_optimization_goal`** [schema]. Use essa lista no conjunto. Otimização fora da lista é auto-corrigida para a recomendada no servidor, e aí o conjunto não faz o que o dono pediu sem ninguém perceber.
|
|
52
|
+
|
|
53
|
+
⚠️ **A lista devolvida pela conta pode ser MAIOR que a tabela da seção 2** [medido em 08/09/2026]. Em 08/09/2026, uma campanha `OUTCOME_TRAFFIC` numa conta real veio com `PROFILE_AND_PAGE_ENGAGEMENT` entre as válidas, e o schema associa essa meta a `OUTCOME_ENGAGEMENT`. Metas liberadas conta a conta explicam a diferença. Quando divergir, **a resposta manda** — e o `destination_type` exigido por aquela meta (seção 3) continua valendo.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 2. Otimização compatível por objetivo (`optimization_goal` do conjunto)
|
|
58
|
+
|
|
59
|
+
O primeiro de cada linha é o padrão [schema, conferido em 11/11/2026].
|
|
60
|
+
|
|
61
|
+
- **OUTCOME_AWARENESS**: `REACH`, `IMPRESSIONS`, `AD_RECALL_LIFT`, `THRUPLAY`, `TWO_SECOND_CONTINUOUS_VIDEO_VIEWS`
|
|
62
|
+
- **OUTCOME_TRAFFIC**: `LINK_CLICKS`, `LANDING_PAGE_VIEWS`, `OFFSITE_CONVERSIONS`, `IMPRESSIONS`, `POST_ENGAGEMENT`, `REACH`, `CONVERSATIONS`, `THRUPLAY`, `VISIT_INSTAGRAM_PROFILE`, `PROFILE_VISIT`, `QUALITY_CALL`, `REMINDERS_SET`
|
|
63
|
+
- **OUTCOME_ENGAGEMENT**: `THRUPLAY`, `POST_ENGAGEMENT`, `EVENT_RESPONSES`, `PAGE_LIKES`, `IMPRESSIONS`, `REACH`, `TWO_SECOND_CONTINUOUS_VIDEO_VIEWS`, `LINK_CLICKS`, `CONVERSATIONS`, `OFFSITE_CONVERSIONS`, `LANDING_PAGE_VIEWS`, `QUALITY_CALL`
|
|
64
|
+
- **OUTCOME_LEADS**: `OFFSITE_CONVERSIONS`, `LEAD_GENERATION`, `QUALITY_LEAD`, `LANDING_PAGE_VIEWS`, `LINK_CLICKS`, `IMPRESSIONS`, `REACH`, `VALUE`, `CONVERSATIONS` (só com destino que inclua WhatsApp), `QUALITY_CALL`
|
|
65
|
+
- **OUTCOME_SALES**: `OFFSITE_CONVERSIONS`, `VALUE`, `LANDING_PAGE_VIEWS`, `IMPRESSIONS`, `POST_ENGAGEMENT`, `REACH`, `LINK_CLICKS`, `CONVERSATIONS`
|
|
66
|
+
- **OUTCOME_APP_PROMOTION**: `APP_INSTALLS`, `OFFSITE_CONVERSIONS`, `IMPRESSIONS`, `LINK_CLICKS`, `REACH`, `VALUE`
|
|
67
|
+
|
|
68
|
+
`VIDEO_VIEWS` (visualização de 10 segundos) está aposentado em todos os objetivos: use `THRUPLAY`.
|
|
69
|
+
Algumas metas são liberadas conta a conta: `ENGAGED_PAGE_VIEWS` (Tráfego), `MEANINGFUL_CALL_ATTEMPT` (Tráfego, Engajamento), `MESSAGING_PURCHASE_CONVERSION` (Engajamento, Vendas, só com destino de mensagem). Se a conta não for elegível, a API recusa; não insista, troque pela padrão e diga ao dono o que trocou.
|
|
70
|
+
Na conta de teste, `OUTCOME_TRAFFIC` devolveu os mesmos 12 valores da lista acima, em ordem alfabética e sem extras [medido em 11/11/2026].
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 3. Destino (`destination_type`) e o que ele exige
|
|
75
|
+
|
|
76
|
+
| Otimização | `destination_type` obrigatório |
|
|
77
|
+
|---|---|
|
|
78
|
+
| `CONVERSATIONS`, `MESSAGING_PURCHASE_CONVERSION`, `MEANINGFUL_CALL_ATTEMPT` | `MESSENGER`, `WHATSAPP` ou `INSTAGRAM_DIRECT` |
|
|
79
|
+
| `VISIT_INSTAGRAM_PROFILE` | `INSTAGRAM_PROFILE` |
|
|
80
|
+
| `PROFILE_VISIT` | `FACEBOOK_PAGE` ou `INSTAGRAM_PROFILE` |
|
|
81
|
+
| `PROFILE_AND_PAGE_ENGAGEMENT` | `INSTAGRAM_PROFILE`, `FACEBOOK_PAGE` ou `INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE` |
|
|
82
|
+
| `POST_ENGAGEMENT` / `PAGE_LIKES` / `THRUPLAY` e `TWO_SECOND_CONTINUOUS_VIDEO_VIEWS` em **OUTCOME_ENGAGEMENT** com `promoted_object` | `ON_POST` / `ON_PAGE` / `ON_VIDEO`; sem destino, "Performance goal isn't available" |
|
|
83
|
+
| `LANDING_PAGE_VIEWS`, `OFFSITE_CONVERSIONS`, `VALUE` | `WEBSITE`: **pareamento típico, não exigido** [schema] |
|
|
84
|
+
|
|
85
|
+
Com destino de mensagem, `promoted_object.page_id` é obrigatório (a ferramenta tenta inferir da Página promovida da conta, mas passe explícito).
|
|
86
|
+
|
|
87
|
+
⚠️ **WhatsApp** [schema, não medido]: o número de WhatsApp Business é configurado **na Página**, não no conjunto nem no criativo. O criativo de mensagem usa `call_to_action_type: "WHATSAPP_MESSAGE"` **sem `link_url`** (a ferramenta põe o link padrão; um `link_url` de outro site é recusado), e a saudação é a padrão da Página. Sem número verificado ligado à Página, o criativo e o anúncio são criados, mas a ativação falha com "Reconnect your WhatsApp number to your Facebook Page or Instagram account to run this ad"; aí o dono liga o número e você ativa de novo, sem recriar nada. Se a resposta do criativo não trouxer `click_to_messaging_destination: "WHATSAPP"`, a conta ainda não tem o botão de mensagem liberado: diga isso ao dono e não tente contornar com `link_url`. `ads_get_errors` **não** acusa essa falta.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 4. `promoted_object` — quando é obrigatório
|
|
92
|
+
|
|
93
|
+
Obrigatório quando `optimization_goal` é `OFFSITE_CONVERSIONS`, `VALUE`, `LEAD_GENERATION`, `QUALITY_LEAD`, `APP_INSTALLS`, `PROFILE_VISIT` ou `PROFILE_AND_PAGE_ENGAGEMENT` [schema].
|
|
94
|
+
|
|
95
|
+
- Conversão no site: `{"pixel_id":"123","custom_event_type":"PURCHASE"}`. Pixel sem `custom_event_type` costuma ser recusado em qualquer meta, inclusive `LANDING_PAGE_VIEWS`; use o evento que o objetivo pede (`PURCHASE` em vendas, `LEAD` em cadastro)
|
|
96
|
+
- Conversão personalizada: `{"custom_conversion_id":"123"}`
|
|
97
|
+
- Aplicativo: `{"application_id":"123","object_store_url":"..."}`
|
|
98
|
+
- Página (mensagem, perfil): `{"page_id":"123"}`
|
|
99
|
+
|
|
100
|
+
🔴 **Campanha `OUTCOME_SALES` com destino `WEBSITE` sem `promoted_object` com pixel é recusada** com "Performance goal isn't available", porque nenhuma otimização é válida nessa combinação. Sem pixel na conta, o caminho honesto é outro objetivo, não insistir.
|
|
101
|
+
|
|
102
|
+
🔴 **Anúncio de formulário de leads** (`LEAD_GENERATION` / `QUALITY_LEAD`) exige que a Página tenha aceitado os termos de geração de cadastros. O campo está em `ads_get_ad_account_pages`: `leadgen_tos_accepted`. Se vier `false`, o dono aceita em https://www.facebook.com/legal/leadgen/tos **antes** de você criar o conjunto.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 5. Orçamento: CBO ou ABO, nunca os dois
|
|
107
|
+
|
|
108
|
+
- **CBO (recomendado pelo Meta e o padrão desta skill):** `campaign_daily_budget` **ou** `campaign_lifetime_budget` no `ads_create_campaign`. O `campaign_bid_strategy` cai em `LOWEST_COST_WITHOUT_CAP` se você não passar nada, que é o "maior volume".
|
|
109
|
+
- **ABO (só se o dono pedir controle por conjunto):** campanha SEM nenhum campo de orçamento e SEM `campaign_bid_strategy`; o `daily_budget` ou `lifetime_budget` vai no `ads_create_ad_set`.
|
|
110
|
+
|
|
111
|
+
Regras que a API impõe:
|
|
112
|
+
- Qualquer campo de orçamento na campanha liga CBO implicitamente. `ads_create_ad_set` **rejeita** orçamento de conjunto sob campanha CBO.
|
|
113
|
+
- `bid_strategy` de conjunto é recusado sob CBO com a mensagem "Must Use Campaign Bid Strategy" [schema]. `bid_amount` e `bid_constraints` também não podem ir sob CBO, mas o schema não diz com que mensagem a API recusa — não espere esse texto.
|
|
114
|
+
- `lifetime_budget` exige `end_time`.
|
|
115
|
+
- **Valor em unidade menor da moeda da conta** (centavos): `5000` = 50,00 na moeda da conta. Conferir a moeda em `ads_get_ad_accounts` antes de converter, porque conta em dólar e conta em real leem o mesmo número de formas diferentes.
|
|
116
|
+
- `LOWEST_COST_WITH_BID_CAP` e `COST_CAP` exigem `bid_amount`; `LOWEST_COST_WITH_MIN_ROAS` exige `bid_constraints`.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 6. Público (`targeting`)
|
|
121
|
+
|
|
122
|
+
- **Advantage+ Audience vem ligado por padrão**: com `targeting` só de país, o conjunto voltou com `targeting_automation.advantage_audience: 1` sem ninguém pedir [medido em 11/11/2026]. Com ele, idade, gênero, interesses e públicos viram sugestão; localização, públicos excluídos, idioma e `age_min` até 25 continuam limite firme [schema].
|
|
123
|
+
- Faixa etária como sugestão: `"age_range":[30,50]` no topo do `targeting`, com `age_min` entre 18 e 25 e sem `age_max` [schema].
|
|
124
|
+
- **Desligar o Advantage+ (`targeting_automation.advantage_audience = 0`) exige motivo**, mandado em `advantage_audience_off_reason`: `ADVERTISER_REQUESTED_OFF` (o dono pediu), `HARD_AGE_REQUIREMENT` (o dono disse que fora de uma faixa NINGUÉM pode ver, com máximo abaixo de 65 ou mínimo acima de 25), `CUSTOM_AUDIENCE_ONLY` (só um público personalizado, como remarketing puro) ou `ADVANTAGE_AUDIENCE_UNAVAILABLE` (a API disse que não há). Persona, faixa de idade "ideal", interesse, posicionamento manual ou "igual ao conjunto anterior" **não são motivo** [schema, não medido]. Ao desligar, diga ao dono qual motivo valeu.
|
|
125
|
+
- ⛔ **Nunca invente ID de interesse.** ID real tem 13 a 16 dígitos e vem da busca de segmentação. Sem ID confirmado, use público amplo por localização: `{"geo_locations":{"countries":["BR"]}}`. Interesse inventado é recusado, e placeholder como `"123"` também.
|
|
126
|
+
- Raio em torno de um ponto: `custom_locations` com latitude, longitude e raio.
|
|
127
|
+
- **Europa (DSA):** se `geo_locations.countries` incluir país da União Europeia, `dsa_beneficiary` e `dsa_payor` são obrigatórios. Omitidos, são preenchidos com o nome do negócio da conta. Confirme com o dono qual nome deve aparecer.
|
|
128
|
+
- Menor recorte geográfico de relatório é estado, não cidade. Segmentar por cidade dá; ler resultado por cidade não.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## 7. Criativo (`ads_create_creative`)
|
|
133
|
+
|
|
134
|
+
Sempre: `ad_account_id` e `page_id`.
|
|
135
|
+
|
|
136
|
+
🔴 **A Página tem que ser uma em que o dono pode criar anúncio** [medido em 08/09/2026]. `ads_get_ad_account_pages` lista as páginas promovidas na conta e pode incluir uma que ele não acessa; nesse caso o create falha com `VALIDATION: Você não tem a permissão necessária para acessar este perfil`. Quem lista o que ele pode usar é `ads_get_user_pages`. A página boa aparece nas duas listas.
|
|
137
|
+
**`instagram_user_id`: sem ele o criativo não entrega em nenhuma superfície do Instagram.** Se o dono quer Instagram, esse campo é obrigatório na prática.
|
|
138
|
+
|
|
139
|
+
| Formato | Campos |
|
|
140
|
+
|---|---|
|
|
141
|
+
| Imagem | `link_url` + exatamente um de `image_hash` / `image_url` |
|
|
142
|
+
| Vídeo | `video_id` + **capa obrigatória** (`image_hash` da capa); `link_url` é opcional, mas obrigatório se houver `description` (fora do criativo de mensagem) |
|
|
143
|
+
| Mensagem (WhatsApp, Messenger, Direct) | imagem ou vídeo + `call_to_action_type` `WHATSAPP_MESSAGE` / `MESSAGE_PAGE` / `INSTAGRAM_MESSAGE`, **sem `link_url`**; o Direct exige `instagram_user_id` (seção 3) |
|
|
144
|
+
| Mídia por posicionamento | `placement_customizations` com 2 a 10 entradas; exatamente uma é a reserva, sem campo de posicionamento (`placement_videos` é o nome antigo, só vídeo) |
|
|
145
|
+
| Carrossel manual | `cards` com 2 a 10; cada card com imagem (ou `video_id`), `link`, `headline`, `description`, CTA |
|
|
146
|
+
| Carrossel de catálogo | `product_set_id` + `link_url`, sem mídia própria |
|
|
147
|
+
| Publicação existente | `object_story_id` no formato `pagina_post`, sozinho, sem copy nem mídia junto |
|
|
148
|
+
|
|
149
|
+
Campos de texto: `message` (texto principal), `headline` (título), `description` (descrição), `call_to_action_type` (padrão `LEARN_MORE`), `display_link` (só aparência, precisa ter cara de URL).
|
|
150
|
+
|
|
151
|
+
**`self_ai_disclosure`** (`OPT_IN` / `OPT_OUT`) — **esta é a fonte única desta regra; o `SKILL.md` só aponta para cá.** Declara mídia criada ou editada com ferramenta de IA generativa de terceiro. **Só existe na criação; nenhuma ferramenta muda depois** [schema] — errar significa apagar o criativo e refazer. A decisão é do anunciante: apresente o campo e use a resposta dele, nunca deduza.
|
|
152
|
+
Detalhe que muda a conversa com o dono: a declaração só produz efeito onde há regra de transparência de IA, hoje **Região Europeia, Índia, Taiwan, Califórnia e Nova York** [schema], e o rótulo "informações de IA" pode ou não aparecer conforme a região da entrega. Essa lista é do Meta e muda sem avisar: se o anúncio for entregar nessas praças, confirme antes.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 8. Anúncio (`ads_create_ad`)
|
|
157
|
+
|
|
158
|
+
Obrigatórios: `ad_account_id`, `ad_set_id`, `ad_name`. No modo ao vivo nasce PAUSED; no modo rascunho nasce `DRAFT` com `ACTIVE` preparado (seção 0).
|
|
159
|
+
|
|
160
|
+
O `creative` leva **exatamente uma** fonte:
|
|
161
|
+
- `{"creative_id":"..."}` — o caminho normal depois do `ads_create_creative`;
|
|
162
|
+
- `{"object_story_id":"pagina_post"}` — impulsionar publicação existente;
|
|
163
|
+
- `{"object_story_spec":{...}}` — criativo embutido. **`page_id` dentro do spec é sempre obrigatório**; omitir dá "Facebook Page is Missing".
|
|
164
|
+
|
|
165
|
+
🔴 **Não existe mais vídeo sem capa.** Em `object_story_spec.video_data` sem `image_hash` / `image_url`, o anúncio entra no rascunho com o erro `1443226 · Seu anúncio precisa de uma miniatura de vídeo: Especifique image_hash ou image_url no campo video_data`, e o publicar recusa a campanha inteira por causa dele [medido em 11/11/2026; o schema de `ads_create_ad` diz o mesmo]. Tire um quadro do vídeo (Fase 2 da skill), suba como imagem e use o `image_hash` como capa.
|
|
166
|
+
|
|
167
|
+
Em `link_data`, prefira `image_hash` a `image_url`.
|
|
168
|
+
|
|
169
|
+
`source_ad_id` duplica um anúncio existente e herda o criativo — útil para repetir a fórmula que já converteu.
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## 9. Subir mídia
|
|
174
|
+
|
|
175
|
+
Três passos, **uma mídia por vez** (paralelo falha):
|
|
176
|
+
|
|
177
|
+
1. `ads_creative_upload_local_image` com `ad_account_id`, `image_name`, `mime_type`, `file_size` (bytes exatos) e `image_sha256` (hex minúsculo). `media_kind` é `"image"` (padrão) ou `"video"`.
|
|
178
|
+
2. POST dos bytes na `upload_url` devolvida, com **cinco** headers [medido em 08/09/2026]:
|
|
179
|
+
|
|
180
|
+
| Header | Valor | Se faltar |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| `Authorization` | o `upload_authorization` da mesma resposta, inteiro | HTTP 400 `NotAuthorizedError: User not authorized to perform this request` |
|
|
183
|
+
| `X-Entity-Name` | nome do arquivo | validação |
|
|
184
|
+
| `X-Entity-Type` | o mesmo `mime_type` | validação |
|
|
185
|
+
| `X-Entity-Length` | tamanho em bytes | validação |
|
|
186
|
+
| `Offset` | `0` | HTTP 400 `ParameterValidationError: HeaderValuePredicate: Header Offset not convertable to unsigned long` |
|
|
187
|
+
|
|
188
|
+
O `Authorization` é o esquecido: não está no nome de nenhum parâmetro, vem no corpo da resposta ao lado da `upload_url`. Os dois 400 acima foram provocados de propósito, um de cada vez, para saber qual header responde por qual erro.
|
|
189
|
+
3. `ads_finalize_local_ad_image_upload` com o `completion_token` — que passa de 500 caracteres. Copiado pela metade, o erro é `The upload completion capability is invalid or expired`, que parece expiração e é truncamento [medido em 08/09/2026].
|
|
190
|
+
|
|
191
|
+
Limites: imagem até 30 MiB, vídeo até 100 MiB (`video/mp4` ou `video/quicktime`).
|
|
192
|
+
Imagem devolve `image_hash`; vídeo devolve `video_id` ainda processando — só entra em anúncio depois de aparecer pronto em `ads_get_ad_videos`.
|
|
193
|
+
|
|
194
|
+
⚠️ `ads_get_ad_videos` sem `video_ids` devolve **só `id` e `title`**. Campo faltando numa listagem não significa campo vazio: para pegar `picture`, `length` ou `status`, chame de novo com `video_ids` ou `fields`.
|
|
195
|
+
|
|
196
|
+
Reserva quando o upload falhar: o dono sobe em "Mídia da conta de anúncios" no Gerenciador (não em "Mídia da empresa", que o MCP não enxerga), com nome único, e você acha por `ads_get_ad_videos` / `ads_get_ad_images`.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 10. Editar, prever, ativar
|
|
201
|
+
|
|
202
|
+
**`ads_update_entity`** usa nomes de campo da API, **não** os argumentos dos `ads_create_*`:
|
|
203
|
+
|
|
204
|
+
| Nível | Certo | Errado |
|
|
205
|
+
|---|---|---|
|
|
206
|
+
| Campanha | `name`, `daily_budget`, `lifetime_budget`, `bid_strategy`, `spend_cap`, `start_time`, `stop_time`, `status` | `campaign_name`, `campaign_daily_budget`, ... |
|
|
207
|
+
| Conjunto | `name` | `ad_set_name` |
|
|
208
|
+
| Anúncio | `name` | `ad_name` |
|
|
209
|
+
|
|
210
|
+
- **Criativo é imutável.** Mídia, texto, título e botão não se editam: crie criativo novo e anúncio novo.
|
|
211
|
+
- Não dá para reparentar (mudar `campaign_id` de um conjunto, `adset_id` de um anúncio).
|
|
212
|
+
- 🔴 `updated_fields` **ecoa o pedido, não o estado gravado**. Olhe o `is_draft`: `true` = a edição ficou preparada no rascunho e ainda não vale no ar. Confirme lendo de volta.
|
|
213
|
+
- 🔴 **Apagar depende do modo da conta.**
|
|
214
|
+
- Modo rascunho: `{"status":"DELETED"}` fica preparado (`is_draft: true`); publicando esses objetos com `ads_activate_entity` + `object_ids`, anúncio, conjunto **e campanha** ficaram `DELETED` [medido em 11/11/2026]. Pause antes: enquanto o `DELETED` não é publicado, o objeto segue ativo.
|
|
215
|
+
- Modo ao vivo: `{"status":"DELETED"}` apaga anúncio e conjunto, mas na campanha o servidor grava `PAUSED`, responde `success: true` e denuncia em `status_forced_to_paused: true` [medido em 08/09/2026, duas tentativas]. Campanha se apaga à mão, no Gerenciador.
|
|
216
|
+
- `ads_creative_delete` apagou o criativo de teste em 11/11/2026 [medido em 11/11/2026]; em 08/09/2026 respondia que não estava liberado para a conta. Imagem usada por um criativo não sai (`IMAGE_IN_USE`): o criativo tem que sair antes.
|
|
217
|
+
|
|
218
|
+
**`ads_get_ad_preview`**: passe `ad_id` **ou** `creative_id`. **Não aceita `ad_account_id`** — passar rejeita a chamada. Se o `ad_id` falhar porque o rascunho é muito novo, tente uma vez com o `creative_id`. Se o erro for de acesso, é acesso: não fique alternando IDs. **Mostre o `preview_url` ao dono, literal, como link.**
|
|
219
|
+
|
|
220
|
+
**`ads_activate_entity`**: só com o "ativa" dele. Em objeto já publicado, ativa só aquele objeto e responde `ACTIVE` na hora: ativar o pai **não** ativa o filho, e campanha, conjunto e anúncio precisam estar ACTIVE [medido em 08/09 e 11/11/2026]. Em rascunho, publica (seção 0) e responde `PUBLISHING`, que é "em publicação", não "no ar". Recusa por validação lista os objetos com erro e **nada foi publicado**; `ignore_validation_errors: true` publica o resto e deixa os quebrados no rascunho, só com o dono ciente [schema, não medido].
|
|
221
|
+
|
|
222
|
+
**`ads_get_errors`**: recebe `entity_ids` (campanha, conjunto, anúncio ou conta). Pega bloqueio de entrega. O schema declara três exclusões: **não pega** rejeição de anúncio, conta desabilitada ou restrita, nem problema de performance e pacing [schema]. A falta de conta WhatsApp Business também não é acusada por ele, mas isso vem da operação da casa, não do schema [medido em campo, antes desta skill]. Em qualquer caso: vazio significa "sem bloqueio desses", nunca "está tudo certo".
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 11. Medir de verdade
|
|
227
|
+
|
|
228
|
+
**Nada nesta seção está em schema, e nada aqui foi medido no teste de 08/09/2026** — então não leva nenhuma das duas marcas. As afirmações abaixo vêm da operação de tráfego da casa, apuradas em incidentes anteriores a esta skill: são as mais estáveis do arquivo e também as que ninguém consegue conferir lendo a documentação do Meta. Confie nelas como regra de operação, não como contrato de API.
|
|
229
|
+
|
|
230
|
+
- ⛔ Nunca `date_preset: "last_7d"` ou `"last_3d"` para provar entrega: os dois **excluem o dia corrente**, e peça ativada ontem aparece com zero mesmo entregando agora. Use `time_range` explícito com o dia de hoje dentro.
|
|
231
|
+
- **Campo ausente é zero.** Anúncio sem gasto volta sem `amount_spent` e sem `impressions`, não com `0`.
|
|
232
|
+
- `status ACTIVE` não prova entrega. **Impressão maior que zero prova.**
|
|
233
|
+
- `updated_time` é a última edição de qualquer coisa, não a hora da ativação: renomear uma peça velha zera esse relógio.
|
|
234
|
+
- Campo fora do padrão em `ads_get_ad_entities` precisa ser confirmado uma vez por máquina com `ads_get_field_context`.
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 12. Categoria especial
|
|
239
|
+
|
|
240
|
+
Valores aceitos hoje [schema, conferido em 11/11/2026]: `NONE`, `EMPLOYMENT`, `HOUSING` (inclui financiamento imobiliário), `FINANCIAL_PRODUCTS_SERVICES` (crédito, empréstimo, seguro e produto financeiro em geral), `ISSUES_ELECTIONS_POLITICS`, `ONLINE_GAMBLING_AND_GAMING`. **`CREDIT` foi aposentado**: use `FINANCIAL_PRODUCTS_SERVICES`. Use o valor exato, nunca o nome de tela.
|
|
241
|
+
|
|
242
|
+
Em `HOUSING`, `EMPLOYMENT` e `FINANCIAL_PRODUCTS_SERVICES` a segmentação fica restrita: `age_min` 18 e `age_max` 65, sem interesse nem segmentação detalhada, raio mínimo de 25 km em cidade ou ponto, e todo país do conjunto tem que estar em `special_ad_category_country` [schema]. Declarar errado é problema de conformidade do anunciante.
|
|
243
|
+
|
|
244
|
+
**Pergunte, não classifique por conta própria.** Se o negócio é de crédito, emprego, imóvel, aposta ou tema social, leve a pergunta ao dono e registre a resposta dele no plano.
|