> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # API de Mensagens de Marketing > A API dedicada da Meta para mensagens de template de marketing — desbloqueia Otimizações Criativas, rastreamento de conversão e TTL de mensagem. A API de Mensagens de Marketing (MM API) é o endpoint de envio avançado da Meta para templates de marketing do WhatsApp. Ela funciona ao lado da Cloud API padrão e ativa um conjunto de recursos — Otimizações Criativas, rastreamento de cliques, TTL de mensagem e métricas de conversão — que não estão disponíveis ao enviar pelo endpoint comum `POST //messages`. ## Cloud API vs API de Mensagens de Marketing | Recurso | Cloud API | API de Mensagens de Marketing | | -------------------------------- | --------------------------- | --------------------------------------------- | | Endpoint de envio | `POST //messages` | `POST //marketing_messages` | | TTL de mensagem | Não configurável | 12 horas – 30 dias | | Otimizações Criativas | Não | Sim (+13,9% de CTR médio) | | Rastreamento de cliques | Não | Sim | | Métricas de conversão | Não | Sim | | Benchmarks de taxa de leitura | Não | Sim | | Categoria de cobrança do webhook | `marketing` | `marketing_lite` | | Comportamento de fallback | — | `CLOUD_API_FALLBACK` ou `STRICT` | | Requisito de onboarding | Nenhum | Termos de Uso da WABA assinados + `ONBOARDED` | ## Como ativar Vá em **Meta Business Manager → Contas do WhatsApp → \[sua WABA] → Configurações**. Aceite os Termos de Uso de Mensagens de Marketing quando solicitado. Você não pode continuar sem essa etapa. No Switchbord, vá em **Configurações → Canal**. O campo `onboarding_status` deve exibir `ONBOARDED`. Se mostrar `NOT_ONBOARDED` ou estiver ausente, conclua primeiro o fluxo de onboarding da Meta. Vá em **Configurações → Canal → API de Mensagens de Marketing** e ative a opção. O Switchbord armazena essa preferência e roteia automaticamente os envios de templates de marketing elegíveis pelo endpoint da MM API. ## TTL de mensagem O TTL (time-to-live, tempo de vida) controla por quanto tempo o WhatsApp mantém uma mensagem aguardando entrega antes de descartá-la. O TTL padrão da Cloud API é de 30 dias para todas as mensagens. Com a MM API, você pode defini-lo por mensagem: * **12 horas**: ofertas relâmpago, lembretes de dia de evento — descartar se o usuário estiver offline por muito tempo * **7 dias**: newsletter semanal, campanha padrão * **30 dias**: reengajamento, winback (igual ao padrão da Cloud API) Defina `ttl` no corpo da requisição da MM API (em segundos). Um valor de `43200` = 12 horas, `604800` = 7 dias, `2592000` = 30 dias. ```json theme={null} POST //marketing_messages { "messaging_product": "whatsapp", "to": "+393289214993", "ttl": 43200, "product_policy": "CLOUD_API_FALLBACK", "template": { "name": "summer_flash_sale", "language": { "code": "it" } } } ``` ## Otimizações Criativas Quando `creative_optimizations` está habilitado nas configurações do seu canal, o sistema de entrega da Meta pode ajustar automaticamente o momento do envio, a seleção da variante de texto ou a ordem dos botões para maximizar o engajamento. Nos testes internos da Meta, isso aumentou o CTR médio em 13,9%. As otimizações são aplicadas no momento da entrega e são invisíveis no payload da API — você envia o mesmo template, e a Meta decide a renderização ideal para cada destinatário. ## Rastreamento de cliques e métricas de conversão A MM API rastreia automaticamente: * **Cliques em links**: toques em botões de URL no template * **Conversões**: eventos posteriores de compra ou reserva (requer integração com Meta Pixel ou CAPI) * **Taxa de leitura**: percentual de mensagens entregues que foram abertas dentro de 24 horas Essas métricas aparecem em **Meta Business Manager → WhatsApp Manager → Insights** e também estão disponíveis pelos endpoints de relatório da Graph API. O Switchbord exibe um resumo da taxa de leitura na página de detalhes da campanha. ## `product_policy` Controla o que acontece se o número de telefone não estiver totalmente habilitado (onboarded) para a MM API: | Valor | Comportamento | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLOUD_API_FALLBACK` | Se a entrega pela MM API falhar por falta de onboarding, a mensagem retorna automaticamente para o envio padrão pela Cloud API. Nenhum erro é retornado ao seu servidor. | | `STRICT` | Se a entrega pela MM API não estiver disponível, a mensagem falha com um erro. Use isso se você precisa garantir que os recursos da MM API (por exemplo, o TTL) sejam aplicados. | ## `message_activity_sharing` Controla se as confirmações de leitura dessa mensagem específica são compartilhadas com a Meta para otimização de entrega. O padrão é `true`. Defina como `false` se seu espaço de trabalho tiver uma política de privacidade que proíba o compartilhamento de sinais de engajamento. ## Limites de entrega por usuário O WhatsApp limita o número de mensagens de marketing entregues a usuários com baixo engajamento. Isso é independente da MM API — aplica-se a todos os templates de marketing, independentemente do caminho de envio. ### Códigos de erro | Código | Significado | Ação | | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `131049` | Limite de marketing por usuário atingido. Mensagem não entregue. | Espere pelo menos 24 horas antes de tentar novamente para esse usuário. | | `131050` | O usuário parou de receber mensagens de marketing dessa empresa. | Atualize `subscriber_status = unsubscribed`. **Não** tente novamente — este é um opt-out permanente. | | `131063` | Templates de marketing estão desativados na Cloud API para este número de telefone. | Mude para o endpoint da MM API. | ### Limites silenciosos Se uma mensagem não for entregue e nenhum código de erro for retornado, o usuário atingiu o limite silencioso por usuário do WhatsApp. Monitore as taxas de leitura das campanhas — uma queda súbita sem erros de entrega é o principal sinal. ### Isenções regionais As seguintes regiões são **isentas** dos limites de entrega de marketing por usuário: * Espaço Econômico Europeu (EEE) * Reino Unido * Japão * Coreia do Sul ### Números dos EUA A entrega de templates de marketing para números de telefone dos EUA (+1) está pausada desde abril de 2025. Os templates não serão entregues a números dos EUA nem pela Cloud API nem pela MM API até que a Meta suspenda essa restrição. ## Segmentação por tag de contato Para enviar apenas para segmentos engajados, filtre os destinatários da campanha por tag antes do envio. Padrões comuns de tag: | Tag | Significado | | ------------------ | --------------------------------- | | `import:list-name` | Importado de uma lista específica | | `confirmed-2026` | Reserva confirmada em 2026 | | `futura-agency` | Contato de agência | Veja [Importação de contatos](/features/contacts-import) para saber como as tags são atribuídas na importação em massa. ## Veja também * [Configurar mensagens de marketing](/getting-started/configure-marketing) — ative a MM API passo a passo * [Templates de marketing](/pt-BR/whatsapp/marketing-templates) — regras de categoria e requisitos de opt-out * [Regras de templates](/pt-BR/whatsapp/template-rules) — referência das regras de validação da Meta