> ## 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. # Componentes e formatos de modelo > Configure componentes, variáveis, botões e formatos especializados de modelos. Crie seu modelo com corpo, cabeçalho e rodapé opcionais e botões. Adicione variáveis para conteúdo que muda entre destinatários. Formatos de autenticação e especializados têm restrições adicionais. ## Estrutura padrão do modelo | Componente | O que contém | Principais limites e verificações | | - | - | - | | Cabeçalho | Texto curto opcional ou um cabeçalho de mídia/localização compatível. | Cabeçalhos de texto: 60 caracteres e no máximo uma variável. Um único cabeçalho usa um formato, não vários tipos de mídia juntos. | | Corpo | A explicação principal da mensagem. | Obrigatório; até 1.024 caracteres para o corpo de um modelo padrão. Mantenha texto fixo suficiente para estabelecer o objetivo. | | Rodapé | Texto de apoio opcional. | Até 60 caracteres para um rodapé padrão. Não o trate como outro corpo rico em variáveis. | | Botões | Respostas ou ações opcionais. | Até 10 no total para combinações padrão suportadas, com limites separados por tipo de botão. | | Exemplos | Valores de variáveis e mídias de exemplo para análise. | Forneça os exemplos exigidos pelos componentes selecionados. Exemplos não são os dados de envio específicos do destinatário. | Esses limites não são uma garantia de que todo modelo especializado aceitará qualquer combinação. A autenticação usa texto predefinido; cartões de carrossel, ofertas por tempo limitado, modelos de comércio e componentes de chamada possuem estruturas próprias. Um layout padrão útil é: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} HEADER: Appointment update BODY: Your booking {{1}} is confirmed for {{2}} at {{3}}. FOOTER: Reply if you need help. BUTTON: View booking ``` O exemplo ilustra apenas a estrutura; ele não é pré-aprovado pela Meta.
Estrutura do modelo da Meta com cabeçalho, corpo, rodapé, URL, telefone e botões de resposta rápida rotulados.
Fonte: [Exemplo oficial da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/custom-marketing-templates/). ## Escolha a ação de botão correta | Botão | O que o cliente faz | Restrição ou dependência padrão | | - | - | - | | Resposta rápida | Envia uma resposta predefinida de volta para a empresa. | Até 10; mantenha as respostas rápidas agrupadas quando misturadas com outros tipos de botão. | | URL do site | Abre uma página da web. | Até 2 botões de URL. Rótulo: 25 caracteres. URL: 2.000 caracteres, com no máximo uma variável no final. | | Número de telefone | Inicia uma chamada telefônica para o número configurado. | Até 1. Rótulo: 25 caracteres; valor do telefone: 20 caracteres. Esta não é uma chamada de voz do WhatsApp. | | Copiar código de oferta | Copia um código de cupom para a área de transferência. | Um botão de copiar código; destinado ao formato de marketing correspondente. O rótulo do botão é predefinido. | | OTP | Copia ou preenche automaticamente um código de verificação. | Apenas modelos de autenticação; use a configuração de botão específica para autenticação. | | Catálogo ou vários produtos | Abre o catálogo correspondente ou os produtos selecionados. | Requer o catálogo correto e identificadores de produto válidos. | | Flow | Abre um formulário estruturado no WhatsApp. | Requer o Flow correto, a ação de entrada e uma versão publicada válida para produção. | | Chamada do WhatsApp | Inicia uma interação de chamada compatível do WhatsApp. | Requer qualificação para Calling. Não substitua por um botão de número de telefone ou solicitação de permissão de chamada ativa. | Um botão de resposta rápida rotulado como **Parar promoções** não é uma implementação automática de cancelamento de inscrição. Seu fluxo de trabalho deve reconhecer a resposta e atualizar as preferências do cliente. Consulte [Opt-out do cliente](/pt/documentation/whatsapp-business-platform/consent-policies-and-account-health/customer-opt-out). ### A ordem dos botões afeta a usabilidade e a compatibilidade Coloque as ações mais importantes primeiro. Com mais de três botões, o WhatsApp exibe os dois primeiros e um controle **Ver todas as opções** para os demais. Um modelo do WhatsApp com dois botões de ação visíveis e Ver todas as opções, ao lado da lista expandida contendo ações de URL, telefone e resposta rápida. Fonte: [Componentes de modelos da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/components). Mantenha as respostas rápidas e outros tipos de botão em grupos separados: * Agrupamento válido: URL → Telefone → Resposta rápida → Resposta rápida. * Agrupamento inválido: Resposta rápida → URL → Resposta rápida. Atualmente, a Meta documenta uma limitação no desktop para modelos com quatro ou mais botões, ou uma resposta rápida misturada com outro tipo de botão: os destinatários são solicitados a visualizar essas mensagens em um celular. Teste isso caso o uso no desktop seja importante para seu público. ## Variáveis: criação, análise e envio são etapas separadas Para este corpo: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Your booking {{1}} is confirmed for {{2}} at {{3}}. ``` Use um mapeamento que sua equipe e integração possam manter: | Posição | Significado | Exemplo de análise | Envio real | | - | - | - | - | | Corpo 1 | Código da reserva | BOOKING-123 | O código de reserva do destinatário. | | Corpo 2 | Data | 12 de outubro de 2026 | A data confirmada do agendamento. | | Corpo 3 | Horário e fuso horário | 10:30 AM UTC | O horário confirmado com contexto local suficiente. | Os exemplos de análise demonstram o significado de uma variável. Eles não configuram uma fonte de dados nem preenchem automaticamente mensagens futuras. O **cabeçalho, o corpo e cada botão dinâmico têm posições de parâmetros separadas**. O corpo `{{1}}` e o botão de URL `{{1}}` não precisam conter o mesmo valor. O botão `index` identifica a posição do botão no modelo, começando em `0`; não é um número de variável do corpo. ### Exemplo: valores do corpo e uma URL dinâmica Suponha que o modelo analisado tenha: * Corpo: `Your booking {{1}} is confirmed for {{2}}.` * Botão no índice `0`: `https://example.com/bookings/{{1}}` O objeto de modelo da mensagem da YCloud pode mapeá-los da seguinte forma: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "booking_confirmation", "language": { "code": "en_US" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "BOOKING-123" }, { "type": "text", "text": "12 October 2026, 10:30 AM UTC" } ] }, { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "BOOKING-123" } ] } ] } ``` Este é um **fragmento do objeto de modelo**, não uma solicitação de envio completa. Ele pressupõe que o modelo indicado e a variante exata de idioma estejam aprovados na WABA do remetente. O parâmetro do botão fornece o sufixo, não a URL completa. Mantenha um domínio de destino estável no modelo analisado. Codifique os valores de URL corretamente e evite incluir informações privadas ou credenciais de acesso de longa duração nos links. Não use uma variável para ocultar a categoria real da mensagem. ## Cabeçalhos de mídia: arquivos de amostra não são anexos ativos Para um cabeçalho de imagem, vídeo ou documento: 1. Selecione o formato de cabeçalho pretendido ao criar o modelo. 2. Forneça uma amostra representativa para análise. 3. No momento do envio, forneça a mídia real usando o ID de mídia ou campo de link compatível da YCloud. 4. Confirme se o arquivo pode ser recuperado, se seu formato corresponde ao modelo e se ele atende aos limites de mídia. 5. Teste a mensagem entregue, incluindo a legibilidade do arquivo em um telefone celular. Não envie um parâmetro de imagem para um modelo com cabeçalho de vídeo. Uma URL privada que só funciona após o login não é um link de mídia confiável para o serviço de mensagens. Cabeçalhos de GIF aparecem nos contratos atuais, mas a Meta restringe esse recurso à rota aplicável da **Marketing Messages API for WhatsApp** . Não presuma que ele esteja disponível em todos os fluxos de trabalho comuns de modelo apenas porque o campo existe. ## Selecionar um formato especializado | Você precisa... | Escolha | Prepare antes da criação | | - | - | - | | Exibir várias opções visuais com ações separadas | [Carrossel de mídia](/pt/documentation/whatsapp-business-platform/messaging/message-templates/carousel-templates) | Mídia de cartão e estrutura de botões consistentes; valores de envio de cada cartão. | | Permitir que os clientes copiem um código promocional | [Modelo de código de cupom](/pt/documentation/whatsapp-business-platform/messaging/message-templates/coupon-code-templates) | Um código resgatável real e condições de oferta claras. | | Exibir uma promoção por tempo limitado | [Oferta por tempo limitado](/pt/documentation/whatsapp-business-platform/messaging/message-templates/limited-time-offer-templates) | O valor de expiração e as regras de checkout correspondentes. | | Abrir toda a coleção de produtos | [Modelo de catálogo](/pt/documentation/whatsapp-business-platform/messaging/message-templates/catalog-templates) | Um catálogo vinculado e produto de miniatura válido, se especificado. | | Exibir um conjunto selecionado de produtos do catálogo | [Modelo de multiprodutos](/pt/documentation/whatsapp-business-platform/messaging/message-templates/multi-product-templates) | IDs de produtos, seções e disponibilidade atual. | | Coletar respostas estruturadas | [Flow](/pt/documentation/whatsapp-business-platform/more-whatsapp-features/whatsapp-flows/index) | ID do Flow, telas, manipulação de dados e fluxo de conclusão. | | Verificar uma ação solicitada de login ou recuperação | [Modelo de autenticação](/pt/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) | Geração, validação, expiração do código e tratamento de fallback. | ## Diagnosticar um erro de componente | Sintoma | Verifique primeiro | | - | - | | Erro de formato ou contagem de parâmetros | Compare as variáveis esperadas de cada componente com o payload de envio. Não conte todas as variáveis como uma lista única e compartilhada. | | O botão incorreto é aberto ou falha | Verifique o índice do botão, subtipo, sufixo de URL e ordem dos botões analisados. | | A mídia não pode ser entregue | Verifique a mídia real no envio, acessibilidade, tipo MIME, tamanho e formato de cabeçalho do modelo. | | O modelo não foi encontrado | Verifique a WABA, o nome e a variante exata de idioma. | | Combinação de botões inválida | Verifique a contagem total, contagem por tipo e agrupamento de respostas rápidas. | | Funciona apenas em um dispositivo | Teste em clientes atuais de Android, iOS e desktop; verifique a compatibilidade específica do formato. | O [guia da API de modelos da YCloud](/pt/api-reference/guides/whatsapp-platform/manage-whatsapp-templates) e o [contrato OpenAPI](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml) definem os campos da YCloud. O suporte a componentes da Meta não garante que todos os editores, Inbox, Campanhas ou rotas da API da YCloud disponibilizem o mesmo recurso. Continue com [Criar um modelo](/pt/documentation/channels/whatsapp-accounts-management/template-management/create-template/index) e [Análise e ciclo de vida do modelo](/pt/documentation/whatsapp-business-platform/messaging/message-templates/template-review-and-lifecycle). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.