> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Gerenciar modelos do WhatsApp > Crie, versione, revise, publique e desative modelos de mensagem do WhatsApp com segurança. ## O que é Os modelos do WhatsApp são estruturas de mensagens pré-aprovadas usadas para iniciar ou continuar conversas fora da janela de atendimento ao cliente. Um modelo é identificado por WABA, nome e idioma. Use este guia para gerenciar o ciclo de vida da API e manter os recursos de modelos de produção estáveis entre equipes, versões e localidades. ## Antes de começar * Conecte a WABA proprietária do modelo. * Escolha a categoria do modelo, o [idioma compatível](/pt/api-reference/guides/whatsapp-platform/supported-whatsapp-template-languages), o nome e os componentes. * Prepare exemplos representativos de variáveis e mídias necessários para a análise. * Siga as políticas da Meta para conteúdos de autenticação, utilidade e marketing. * Configure um endpoint de webhook capaz de receber eventos de `whatsapp.template.reviewed`. ## Como funciona 1. Crie o modelo em uma WABA. 2. Armazene seu nome, idioma, categoria e o `status` atual. 3. Aguarde a aprovação quando a análise for necessária. 4. Recupere ou liste modelos para acompanhar as mudanças de status. 5. Envie apenas modelos válidos para o caso de uso de destino e que estejam em um estado apto para envio. 6. Edite ou exclua o modelo quando o conteúdo ou o ciclo de vida mudar. A edição substitui o conteúdo do modelo existente. Inclua todos os componentes que devem permanecer após a edição. ## Requisição `POST /whatsapp/templates` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/whatsapp/templates \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup.", "example": { "body_text": [["A-10001"]] } } ] }' ``` Os nomes dos modelos devem ser identificadores de aplicativo estáveis. Use variáveis apenas nas posições aceitas pelo componente selecionado. ## Resposta ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "status": "PENDING", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup." } ] } ``` A resposta confirma a criação do modelo e seu estado atual. `PENDING` não significa que o modelo já possa ser enviado. ## Defina uma identidade de recurso estável Trate cada combinação de WABA, nome de modelo e idioma como um único recurso. Mantenha um registro de recursos com o `wabaId` proprietário, nome estável, código de localidade exato, finalidade, responsável, contrato de variáveis, status atual da API, estado de implantação e versão de substituição. Use um nome previsível, como `__v`: * `auth_login_otp_v1` * `orders_pickup_ready_v2` * `growth_summer_offer_v3` Incremente a versão principal quando uma alteração afetar as posições das variáveis, tipos de componentes, botões, categoria ou o significado da mensagem. Mantenha os nomes independentes de nomes de equipes e datas. ## Escolha a categoria antes de escrever o conteúdo Escolha a categoria com base no motivo pelo qual o cliente receberá a mensagem. | Categoria | Use quando | | - | - | | `AUTHENTICATION` | Você autenticar um usuário com uma senha descartável para verificação, recuperação ou um desafio de integridade. | | `UTILITY` | Você atender a uma solicitação específica do usuário ou fornecer uma atualização sobre uma transação acordada. | | `MARKETING` | Você enviar uma oferta, promoção, convite ou outro conteúdo que não se qualifique como autenticação ou utilidade. | Se um modelo mesclar informações transacionais com uma promoção, crie-o como marketing ou divida as finalidades em modelos separados. ## Defina e congele o contrato de variáveis Defina as variáveis como um contrato de API antes que redatores ou tradutores comecem. Para cada variável, registre sua posição, significado semântico, formato, origem, exemplo representativo e comportamento de fallback. Por exemplo, `Order {{0}} is ready at {{1}}.` pode usar este contrato: | Posição | Significado | Formato | Exemplo de revisão | | - | - | - | - | | `{{0}}` | `order_reference` | String curta visível ao cliente | `A-10001` | | `{{1}}` | `pickup_location` | Nome da loja localizado | `Central Store` | Mantenha o significado de cada posição estável entre versões e localidades. Crie uma nova versão se precisar reordenar ou alterar a finalidade das variáveis. Antes do envio para análise: * Forneça um exemplo seguro e representativo para cada variável do corpo ou do cabeçalho de texto. * Valide URLs de cabeçalho de mídia, formatos e tamanhos de arquivo. * Limite o cabeçalho de texto a no máximo uma variável e inclua sua amostra. * Confirme que as variáveis de botão de URL apareçam apenas onde a API permitir e inclua um URL de exemplo completo. * Nunca use credenciais, códigos de uso único, dados pessoais ou mídias privadas em exemplos de análise. ## Organize localidades como um único lançamento Reutilize o mesmo nome versionado para cada localidade em um lançamento, mas gerencie cada par de `name` e `language` como um recurso separado. Mantenha os significados das variáveis e as ações dos botões consistentes, mesmo quando a ordem das palavras mudar. Aprove e lance cada localidade de forma independente. Nunca redirecione um usuário para outro idioma apenas porque essa localidade foi aprovada. Use o código exato da localidade (diferenciando maiúsculas de minúsculas) em solicitações de criação, recuperação, edição, exclusão e envio. ## Condicione os envios ao status do modelo Use consultas ou webhooks de `whatsapp.template.reviewed` para processar aprovação, rejeição, pausa, desativação, arquivamento e outras alterações de ciclo de vida. Mantenha o nome e o idioma exatos usados pelas solicitações de mensagens. Armazene o `status` da API separadamente do seu estado de implantação. Apenas encaminhe envios de produção para um modelo cujo status atual seja `APPROVED` e cujo estado de implantação esteja ativo. | Status | Ação de produção | | - | - | | `PENDING` | Bloqueie envios enquanto a análise estiver em andamento. | | `APPROVED` | Permita envios após aprovação nos testes de contrato e no rollout. | | `REJECTED` | Bloqueie envios, inspecione o motivo e corrija o conteúdo ou o contrato. | | `PAUSED` ou `DISABLED` | Interrompa novos envios e use um fallback aprovado quando disponível. | | `IN_APPEAL` | Mantenha os envios bloqueados até que o status mude para `APPROVED`. | | `ARCHIVED` ou `DELETED` | Remova o modelo de mensagem do roteamento. | Uma resposta de criação ou edição bem-sucedida não autoriza envios em produção. ## Sincronizar estado Use Webhooks para atualizações rápidas e APIs de recuperação ou listagem para reconciliação: 1. Verifique a assinatura de cada evento `whatsapp.template.reviewed`. 2. Elimine entregas duplicadas pelo `id` do evento. 3. Resolva o recurso por `wabaId`, `name` e `language`. 4. Armazene tanto o evento de atualização quanto o `status` atual. 5. Interrompa o roteamento imediatamente quando o status atual não for `APPROVED`. 6. Recupere o modelo de mensagem quando um evento estiver ausente, atrasado ou em conflito com um estado de registro mais recente. 7. Execute uma reconciliação agendada e paginada de listagem para detectar divergências. Não use Webhooks como seu único inventário e não faça polling antes de cada mensagem. ## Comportamento de edição e exclusão * Edite apenas modelos de mensagem em um estado suportado pelo endpoint. * Inclua o conjunto completo de componentes desejados na solicitação de edição. * A exclusão por nome remove todos os idiomas com esse nome. * A exclusão por nome e idioma remove apenas aquele modelo de mensagem localizado. * Modelos de mensagem arquivados ainda podem aparecer nos resultados de listagem e recuperação. ## Lançar, reverter e desativar versões Prefira uma versão paralela para alterações significativas: 1. Crie um novo nome com versão para cada localidade necessária. Mantenha a versão atual aprovada inalterada. 2. Aguarde até que cada localidade de destino esteja `APPROVED` e, em seguida, valide suas variáveis, mídias, botões, categoria e conteúdo renderizado. 3. Direcione uma parcela controlada de envios qualificados para a nova versão e monitore a entrega, a qualidade, as respostas e as atualizações de status. 4. Migre o tráfego restante somente depois que a nova versão atender aos seus critérios de rollout. Reverta alternando o roteamento para o nome e idioma aprovados anteriormente. Não use uma edição de emergência como rollback. Desative a versão anterior somente quando filas, campanhas, configurações, testes e janelas de rollback não fizerem mais referência a ela. ## Limites e solução de problemas * Uma solicitação de envio falha quando o modelo de mensagem não está aprovado ou seus componentes não correspondem aos parâmetros da mensagem. * Modelos de mensagem de autenticação usam estruturas predefinidas e restritas. * A categoria e o conteúdo do modelo de mensagem devem estar alinhados com as políticas da Meta. * Revise os detalhes da rejeição antes de recriar o mesmo conteúdo. * Use um novo nome quando um modelo de mensagem excluído ou significativamente alterado não puder ser restaurado com segurança. ## Checklist para entrada em produção * [ ] O nome, finalidade, proprietário, categoria e versão estão registrados. * [ ] Cada variável possui apenas um significado, formato, exemplo seguro e regra de fallback. * [ ] Mídias e botões passaram nas verificações de formato, destino e exemplo. * [ ] Cada localidade necessária está independentemente `APPROVED`. * [ ] O fluxo de envio rejeita qualquer status diferente de `APPROVED`. * [ ] O processamento de Webhook é verificado, idempotente e reconciliado com a recuperação. * [ ] O rollout pode restaurar uma versão aprovada anteriormente. * [ ] Filas, campanhas, configurações, testes e runbooks utilizam a versão pretendida. Selecione o idioma exato e o código de localidade regional para um modelo de mensagem. Adapte modelos de mensagem de autenticação, marketing, utilidade, comércio, Flow e chamadas. Inspecione o esquema completo de componentes. Processe alterações de análise e de ciclo de vida. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.