> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar menu interativo (botões, carrossel, lista ou enquete) > Este endpoint oferece uma interface unificada para envio de quatro tipos principais de mensagens interativas: - Botões: Para ações rápidas e diretas - Carrossel de botões: Para uma lista horizontal de botões com imagens - Listas: Para menus organizados em seções - Enquetes: Para coleta de opiniões e votações **Suporte a campos de rastreamento**: Este endpoint também suporta `track_source` e `track_id` documentados na tag **"Enviar Mensagem"**. ## Estrutura Base do Payload Todas as requisições seguem esta estrutura base: ```json { "number": "5511999999999", "type": "button|button_legacy|list|poll|carousel", "text": "Texto principal da mensagem", "choices": ["opções baseadas no tipo escolhido"], "footerText": "Texto do rodapé (opcional para botões e listas)", "listButton": "Texto do botão (para listas)", "selectableCount": "Número de opções selecionáveis (apenas para enquetes)" } ``` ## Tipos de Mensagens Interativas ### 1. Botões (type: "button") Cria botões interativos com diferentes funcionalidades de ação. #### Campos Específicos - `footerText`: Texto opcional exibido abaixo da mensagem principal - `choices`: Array de opções que serão convertidas em botões #### Formatos de Botões Cada botão pode ser configurado usando `|` (pipe) ou `\n` (quebra de linha) como separadores: - **Botão de Resposta**: - `"texto|id"` ou - `"texto\nid"` ou - `"texto"` (ID será igual ao texto) - **Botão de Cópia**: - `"texto|copy:código"` ou - `"texto\ncopy:código"` - **Botão de Chamada**: - `"texto|call:+5511999999999"` ou - `"texto\ncall:+5511999999999"` - **Botão de URL**: - `"texto|https://exemplo.com"` ou - `"texto|url:https://exemplo.com"` #### Botões com imagem, vídeo ou documento O cabeçalho do botão pode levar uma imagem, um vídeo ou um documento em `file`, por URL ou base64, como no `/send/media`. O tipo sai do próprio arquivo; para forçar, mande `mimetype`: `image`, `video`, `document` ou o MIME type do arquivo (por exemplo, `video/mp4`). O documento usa o nome de `docName`; sem ele, o nome do arquivo. Áudio não vai no botão: o WhatsApp não tem áudio no cabeçalho, e a API responde `400`. Envie o áudio antes, com o `/send/media`. Sem `mimetype`, a API reconhece o áudio pela extensão da URL ou pelo início do base64; numa URL sem extensão, informe o `mimetype`. ```json { "number": "5511999999999", "type": "button", "text": "Escolha um produto:", "file": "https://exemplo.com/produto1.jpg", "choices": [ "Produto A|prod_a", "Mais Info|https://exemplo.com/produto-a", "Produto B|prod_b", "Ligar|call:+5511999999999" ], "footerText": "Produtos em destaque" } ``` ```json { "number": "5511999999999", "type": "button", "text": "Tabela de preços de outubro", "file": "https://exemplo.com/tabela.pdf", "docName": "Tabela de preços.pdf", "choices": ["Quero comprar|comprar", "Falar com vendedor|vendedor"] } ``` Se a mídia não baixar ou não subir para o WhatsApp, o botão sai sem ela. #### Botões no formato legado (type: "button_legacy") Use `button_legacy` somente quando precisar enviar os botões de resposta do formato anterior. O formato de `choices` é: - `"texto|id"` - `"texto\nid"` - `"texto|reply:id"` - `"texto"` — o próprio texto será usado como ID Este modo cria apenas botões de resposta. Ações de URL, chamada e cópia e o a mídia em `file` continuam disponíveis no formato atual `type: "button"`. ```json { "number": "5511999999999", "type": "button_legacy", "text": "Deseja continuar?", "choices": [ "Sim|confirmar", "Não|reply:cancelar" ], "footerText": "Escolha uma opção" } ``` #### Exemplo Completo ```json { "number": "5511999999999", "type": "button", "text": "Como podemos ajudar?", "choices": [ "Suporte Técnico|suporte", "Fazer Pedido|pedido", "Nosso Site|https://exemplo.com", "Falar Conosco|call:+5511999999999" ], "footerText": "Escolha uma das opções abaixo" } ``` #### Limitações e Compatibilidade > **Importante**: Ao combinar botões de resposta com outros tipos (call, url, copy) na mesma mensagem, será exibido o aviso: "Não é possível exibir esta mensagem no WhatsApp Web. Abra o WhatsApp no seu celular para visualizá-la." ### 2. Listas (type: "list") Cria menus organizados em seções com itens selecionáveis. #### Campos Específicos - `listButton`: Texto do botão que abre a lista - `footerText`: Texto opcional do rodapé - `choices`: Array com seções e itens da lista #### Formato das Choices - `"[Título da Seção]"`: Inicia uma nova seção - `"texto|id|descrição"`: Item da lista com: - texto: Label do item - id: Identificador único, opcional - descrição: Texto descritivo adicional e opcional #### Exemplo Completo ```json { "number": "5511999999999", "type": "list", "text": "Catálogo de Produtos", "choices": [ "[Eletrônicos]", "Smartphones|phones|Últimos lançamentos", "Notebooks|notes|Modelos 2024", "[Acessórios]", "Fones|fones|Bluetooth e com fio", "Capas|cases|Proteção para seu device" ], "listButton": "Ver Catálogo", "footerText": "Preços sujeitos a alteração" } ``` ### 3. Enquetes (type: "poll") Cria enquetes interativas para votação. #### Campos Específicos - `selectableCount`: Número de opções que podem ser selecionadas (padrão: 1) - `choices`: Array simples com as opções de voto #### Exemplo Completo ```json { "number": "5511999999999", "type": "poll", "text": "Qual horário prefere para atendimento?", "choices": [ "Manhã (8h-12h)", "Tarde (13h-17h)", "Noite (18h-22h)" ], "selectableCount": 1 } ``` ### 4. Carousel (type: "carousel") Cria um carrossel de cartões com imagens e botões interativos. #### Campos Específicos - `choices`: Array com elementos do carrossel na seguinte ordem: - `[Texto do cartão]`: Texto do cartão entre colchetes - `{URL ou base64 da imagem}`: Imagem entre chaves - Botões do cartão (um por linha): - `"texto|copy:código"` para botão de copiar - `"texto|https://url"` para botão de link - `"texto|call:+número"` para botão de ligação #### Exemplo Completo ```json { "number": "5511999999999", "type": "carousel", "text": "Conheça nossos produtos", "choices": [ "[Smartphone XYZ\nO mais avançado smartphone da linha]", "{https://exemplo.com/produto1.jpg}", "Copiar Código|copy:PROD123", "Ver no Site|https://exemplo.com/xyz", "Fale Conosco|call:+5511999999999", "[Notebook ABC\nO notebook ideal para profissionais]", "{https://exemplo.com/produto2.jpg}", "Copiar Código|copy:NOTE456", "Comprar Online|https://exemplo.com/abc", "Suporte|call:+5511988888888" ] } ``` > **Nota**: Criamos outro endpoint para carrossel: `/send/carousel`, funciona da mesma forma, mas com outro formato de payload. Veja o que é mais fácil para você. ## Termos de uso Os recursos de botões interativos e listas podem ser descontinuados a qualquer momento sem aviso prévio. Não nos responsabilizamos por quaisquer alterações ou indisponibilidade destes recursos. ### Alternativas e Compatibilidade Considerando a natureza dinâmica destes recursos, nosso endpoint foi projetado para facilitar a migração entre diferentes tipos de mensagens (botões, listas e enquetes). Recomendamos criar seus fluxos de forma flexível, preparados para alternar entre os diferentes tipos. Em caso de descontinuidade de algum recurso, você poderá facilmente migrar para outro tipo de mensagem apenas alterando o campo "type" no payload, mantendo a mesma estrutura de choices. ## OpenAPI ````yaml /openapi-pt-BR.json post /send/menu openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para gerenciamento de instâncias do WhatsApp e comunicações. ## Recomendação Importante: WhatsApp Business **É ALTAMENTE RECOMENDADO usar contas do WhatsApp Business** em vez do WhatsApp normal para integração, o WhatsApp normal pode apresentar inconsistências, desconexões, limitações e instabilidades durante o uso com a nossa API. ## Autenticação - Endpoints regulares requerem um header 'token' com o token da instância ## Estados da Instância As instâncias podem estar nos seguintes estados: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado com sucesso servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: | Operações relacionadas ao ciclo de vida de uma instância, como conectar, desconectar e verificar o status. - name: Proxy description: > A WppFy opera com um proxy interno como padrão. Você pode manter esse padrão, configurar um proxy próprio via `proxy_url` ou usar seu celular android como proxy instalando o app em https://github.com/WppFy/silver_proxy_apk (APK direto: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Se nada for enviado, seguimos no proxy interno. IPs são brasileiros; para clientes internacionais, considere um proxy da região do cliente. - name: Perfil description: | Operações relacionadas ao perfil da instância do WhatsApp, como alterar nome e imagem de perfil. - name: Business description: | ⚠️ **EXPERIMENTAL** - Endpoints ainda não testados completamente. Operações relacionadas ao perfil comercial do WhatsApp Business. Permite consultar e atualizar dados do perfil comercial como descrição, endereço, email, categorias e gerenciar o catálogo de produtos. **Requisitos:** - A conta atualmente conectada deve ser uma conta **WhatsApp Business** - Contas pessoais do WhatsApp não possuem perfil comercial **Nota:** Estes endpoints podem não funcionar como esperado. Reporte problemas encontrados. - name: Chamadas description: | Operações relacionadas a chamadas peloWhatsApp. Permite realizar e rejeitar chamadas programaticamente. - name: Enviar Mensagem description: > Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo. ## Campos Opcionais Comuns Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais: - **`delay`** *(integer)*: Atraso em milissegundos antes do envio - Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo - Exemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar chat como lido após envio - Remove o contador de mensagens não lidas do chat - Exemplo: `true` - **`readmessages`** *(boolean)*: Marcar últimas mensagens recebidas como lidas - Marca as últimas 10 mensagens **recebidas** (não enviadas por você) como lidas - Útil para confirmar leitura de mensagens pendentes antes de responder - Diferente do `readchat` que apenas remove contador de não lidas - Exemplo: `true` - **`replyid`** *(string)*: ID da mensagem para responder - Cria uma resposta vinculada à mensagem original - Suporte varia por tipo de mensagem - Exemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números para mencionar (apenas para envio em grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar todos: `"all"` - **`forward`** *(boolean)*: Marca a mensagem como encaminhada no WhatsApp - Adiciona o indicador "Encaminhada" na mensagem - Exemplo: `true` - **`track_source`** *(string)*: Origem do rastreamento da mensagem - Identifica o sistema ou fonte que está enviando a mensagem - Útil para integrações (ex: "chatwoot", "crm", "chatbot") - Exemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para rastreamento da mensagem - Identificador livre para acompanhar a mensagem em sistemas externos - Permite correlacionar mensagens entre diferentes plataformas - **Nota**: O sistema aceita valores duplicados - não há validação de unicidade - Use o mesmo ID em várias mensagens se fizer sentido para sua integração - Exemplo: `"msg_123456789"` ### Envio para Grupos - **`number`** *(string)*: Para enviar mensagem para grupo, use o ID do grupo que termina com `@g.us` - Exemplo: `"120363012345678901@g.us"` - **Como obter o ID do grupo:** - Use o `chatid` do webhook recebido quando alguém envia mensagem no grupo - Use o endpoint `GET /group/list` para listar todos os grupos e seus IDs ## Placeholders Disponíveis Todos os endpoints de envio de mensagem suportam placeholders dinâmicos para personalização automática: ### Campos de Nome - **`{{name}}`**: Nome consolidado do chat, usando a primeira opção disponível: 1. Nome do lead (`lead_name`) 2. Nome completo do lead (`lead_fullName`) 3. Nome do contato no WhatsApp (`wa_contactName`) 4. Nome do perfil do WhatsApp (`wa_name`) - **`{{first_name}}`**: Primeira palavra válida do nome consolidado (mínimo 2 caracteres) ### Campos do WhatsApp - **`{{wa_name}}`**: Nome do perfil do WhatsApp - **`{{wa_contactName}}`**: Nome do contato como salvo no WhatsApp ### Campos do Lead - **`{{lead_name}}`**: Nome do lead - **`{{lead_fullName}}`**: Nome completo do lead - **`{{lead_personalid}}`**: ID pessoal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email do lead - **`{{lead_status}}`**: Status atual do lead - **`{{lead_notes}}`**: Anotações do lead - **`{{lead_assignedAttendant_id}}`**: ID do atendente designado ### Campos Personalizados Campos adicionados via custom fields são acessíveis usando `{{lead_field01}}` à `{{lead_field20}}` ou usar `{{nomedocampo}}` definido em `/instance/updateFieldsMap`. ### Exemplo de Uso ``` Olá {{name}}! Vi que você trabalha na {{company}}. Seu email {{lead_email}} está correto? ``` **💡 Dica**: Use `/chat/find` para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders. - name: Mensagem Async description: > Controles operacionais da fila interna de envio assíncrono usada quando um endpoint de envio recebe `async=true`. Esta seção serve para: - consultar o estado atual da fila async - configurar o delay entre mensagens enviadas com `async=true` - limpar backlog pendente e cancelar mensagens ainda não concluídas Escopo: - cobre apenas a fila interna de mensagens diretas async - não altera mensagens já enviadas com sucesso - name: Ações na mensagem e Buscar - name: Chats - name: Contatos - name: Bloqueios - name: Etiquetas - name: Grupos e Comunidades - name: Newsletters e Canais description: > Operações para leitura e acompanhamento de canais do WhatsApp (newsletters). Casos de uso principais: - listar posts já publicados em um canal - editar posts recentes de um canal - deletar posts recentes de um canal - consultar views e reações dos posts - integrar canais sem necessidade de persistir as mensagens localmente Observações: - `/newsletter/messages` retorna o conteúdo dos posts - `/newsletter/messages/edit` edita o conteúdo de posts recentes - `/newsletter/messages/delete` apaga posts recentes - views (`viewsCount`) e reactions (`reactionCounts`) vêm em cada post de `/newsletter/messages`, não por evento de webhook - `/newsletter/updates` está obsoleta: o WhatsApp não responde e a API devolve 504 - newsletters usam rotas próprias e não devem usar `/message/edit` ou `/message/delete` - name: Respostas Rápidas description: > Gerenciamento de respostas rápidas para agilizar o atendimento. **⚠️ Importante**: Este recurso tem serventia apenas se você utilizar um sistema frontend/interface personalizada para registrar e utilizar as respostas. A API apenas armazena as respostas, mas não as aplica automaticamente. ### Como funciona: - **Criar**: Cadastre respostas pré-definidas com títulos e conteúdo - **Listar**: Recupere todas as respostas cadastradas para exibir na sua interface - **Usar**: Seu sistema frontend pode usar essas respostas para agilizar digitação ### Casos de uso: - Interfaces web personalizadas de atendimento - Apps mobile com sugestões de resposta - Sistemas CRM com templates de mensagem - Ferramentas de produtividade para atendentes **Não é um chatbot**: Para respostas automáticas, use os recursos de Chatbot. - name: CRM description: > Sistema completo de gestão de relacionamento com clientes integrado à API. **💾 Armazenamento interno**: Todos os dados dos leads ficam salvos diretamente na API, eliminando a necessidade de bancos de dados externos. Sua aplicação pode focar apenas na interface e lógica de negócio. ### Recursos disponíveis: - **📋 20+ campos personalizáveis**: Nome, telefone, email, empresa, observações, etc. - **🏷️ Sistema de etiquetas**: Organize e categorize seus contatos - **🔍 Busca avançada**: Filtre por qualquer campo ou etiqueta - **📊 Histórico completo**: Todas as interações ficam registradas automaticamente ### 🎯 Placeholders em mensagens: Use variáveis dinâmicas nas mensagens para personalização automática: ``` Olá {{nome}}! Vi que você trabalha na {{empresa}}. Seu email {{email}} está correto? Observações: {{observacoes}} ``` ### Fluxo típico: 1. **Captura**: Leads chegam via WhatsApp ou formulários 2. **Enriquecimento**: Adicione dados usando `/chat/editLead` 3. **Segmentação**: Organize com etiquetas 4. **Comunicação**: Envie mensagens personalizadas com placeholders 5. **Acompanhamento**: Histórico fica salvo automaticamente **Ideal para**: Vendas, marketing, atendimento, qualificação de leads - name: Integração Chatwoot description: > **🚧 INTEGRAÇÃO BETA - Sistema de integração com Chatwoot para atendimento unificado** **⚠️ AVISO**: Esta integração está em fase BETA. Use por sua conta e risco. Recomendamos testes em ambiente não-produtivo antes do uso em produção. Esta categoria contém recursos para configurar e gerenciar a integração com o Chatwoot, uma plataforma de atendimento ao cliente open-source. A integração permite centralizar conversas do WhatsApp no Chatwoot. ### Recursos disponíveis: - 🔧 **Configuração Completa**: Configure URL, tokens e credenciais do Chatwoot - 📬 **Sincronização Bidirecional**: Mensagens novas entre WhatsApp e Chatwoot são sincronizadas automaticamente - 📱 **Gerenciamento de Contatos**: Sincronização automática de nomes e telefones - 🔄 **Atualização LID→PN**: Migração automática de Local ID para Phone Number - 🏷️ **Nomes Inteligentes**: Sistema de nomes com til (~) para atualização automática - 🚫 **Separação de Grupos**: Opção para ignorar grupos na sincronização - 👤 **Assinatura de Mensagens**: Identificação do agente nas mensagens enviadas - 🔗 **Webhook Automático**: URL gerada automaticamente para configurar no Chatwoot ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: Atualizados automaticamente quando contato modifica nome no WhatsApp - **Nomes específicos**: Para nome fixo, remover til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" = automático, "João Silva" = fixo - **Migração LID→PN**: Sem duplicação de conversas durante a transição - **Respostas nativas**: Aparecem diretamente no Chatwoot sem marcações externas ### ⚠️ Limitações conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas ### Casos de uso: - Atendimento centralizado no Chatwoot - Equipes de suporte com múltiplos agentes - Integração com CRM via Chatwoot - Centralização de canais de comunicação - Gestão automática de contatos e nomes **Ideal para**: Empresas com equipes de atendimento, call centers, suporte técnico (em ambiente de testes) **Requer**: Instância do Chatwoot configurada, tokens de API e ambiente de testes **🚧 Lembre-se**: Integração em BETA - funcionalidades podem mudar sem aviso prévio - name: Server-Sent Events (SSE) paths: /send/menu: post: tags: - Enviar Mensagem summary: Enviar menu interativo (botões, carrossel, lista ou enquete) description: > Este endpoint oferece uma interface unificada para envio de quatro tipos principais de mensagens interativas: - Botões: Para ações rápidas e diretas - Carrossel de botões: Para uma lista horizontal de botões com imagens - Listas: Para menus organizados em seções - Enquetes: Para coleta de opiniões e votações **Suporte a campos de rastreamento**: Este endpoint também suporta `track_source` e `track_id` documentados na tag **"Enviar Mensagem"**. ## Estrutura Base do Payload Todas as requisições seguem esta estrutura base: ```json { "number": "5511999999999", "type": "button|button_legacy|list|poll|carousel", "text": "Texto principal da mensagem", "choices": ["opções baseadas no tipo escolhido"], "footerText": "Texto do rodapé (opcional para botões e listas)", "listButton": "Texto do botão (para listas)", "selectableCount": "Número de opções selecionáveis (apenas para enquetes)" } ``` ## Tipos de Mensagens Interativas ### 1. Botões (type: "button") Cria botões interativos com diferentes funcionalidades de ação. #### Campos Específicos - `footerText`: Texto opcional exibido abaixo da mensagem principal - `choices`: Array de opções que serão convertidas em botões #### Formatos de Botões Cada botão pode ser configurado usando `|` (pipe) ou `\n` (quebra de linha) como separadores: - **Botão de Resposta**: - `"texto|id"` ou - `"texto\nid"` ou - `"texto"` (ID será igual ao texto) - **Botão de Cópia**: - `"texto|copy:código"` ou - `"texto\ncopy:código"` - **Botão de Chamada**: - `"texto|call:+5511999999999"` ou - `"texto\ncall:+5511999999999"` - **Botão de URL**: - `"texto|https://exemplo.com"` ou - `"texto|url:https://exemplo.com"` #### Botões com imagem, vídeo ou documento O cabeçalho do botão pode levar uma imagem, um vídeo ou um documento em `file`, por URL ou base64, como no `/send/media`. O tipo sai do próprio arquivo; para forçar, mande `mimetype`: `image`, `video`, `document` ou o MIME type do arquivo (por exemplo, `video/mp4`). O documento usa o nome de `docName`; sem ele, o nome do arquivo. Áudio não vai no botão: o WhatsApp não tem áudio no cabeçalho, e a API responde `400`. Envie o áudio antes, com o `/send/media`. Sem `mimetype`, a API reconhece o áudio pela extensão da URL ou pelo início do base64; numa URL sem extensão, informe o `mimetype`. ```json { "number": "5511999999999", "type": "button", "text": "Escolha um produto:", "file": "https://exemplo.com/produto1.jpg", "choices": [ "Produto A|prod_a", "Mais Info|https://exemplo.com/produto-a", "Produto B|prod_b", "Ligar|call:+5511999999999" ], "footerText": "Produtos em destaque" } ``` ```json { "number": "5511999999999", "type": "button", "text": "Tabela de preços de outubro", "file": "https://exemplo.com/tabela.pdf", "docName": "Tabela de preços.pdf", "choices": ["Quero comprar|comprar", "Falar com vendedor|vendedor"] } ``` Se a mídia não baixar ou não subir para o WhatsApp, o botão sai sem ela. #### Botões no formato legado (type: "button_legacy") Use `button_legacy` somente quando precisar enviar os botões de resposta do formato anterior. O formato de `choices` é: - `"texto|id"` - `"texto\nid"` - `"texto|reply:id"` - `"texto"` — o próprio texto será usado como ID Este modo cria apenas botões de resposta. Ações de URL, chamada e cópia e o a mídia em `file` continuam disponíveis no formato atual `type: "button"`. ```json { "number": "5511999999999", "type": "button_legacy", "text": "Deseja continuar?", "choices": [ "Sim|confirmar", "Não|reply:cancelar" ], "footerText": "Escolha uma opção" } ``` #### Exemplo Completo ```json { "number": "5511999999999", "type": "button", "text": "Como podemos ajudar?", "choices": [ "Suporte Técnico|suporte", "Fazer Pedido|pedido", "Nosso Site|https://exemplo.com", "Falar Conosco|call:+5511999999999" ], "footerText": "Escolha uma das opções abaixo" } ``` #### Limitações e Compatibilidade > **Importante**: Ao combinar botões de resposta com outros tipos (call, url, copy) na mesma mensagem, será exibido o aviso: "Não é possível exibir esta mensagem no WhatsApp Web. Abra o WhatsApp no seu celular para visualizá-la." ### 2. Listas (type: "list") Cria menus organizados em seções com itens selecionáveis. #### Campos Específicos - `listButton`: Texto do botão que abre a lista - `footerText`: Texto opcional do rodapé - `choices`: Array com seções e itens da lista #### Formato das Choices - `"[Título da Seção]"`: Inicia uma nova seção - `"texto|id|descrição"`: Item da lista com: - texto: Label do item - id: Identificador único, opcional - descrição: Texto descritivo adicional e opcional #### Exemplo Completo ```json { "number": "5511999999999", "type": "list", "text": "Catálogo de Produtos", "choices": [ "[Eletrônicos]", "Smartphones|phones|Últimos lançamentos", "Notebooks|notes|Modelos 2024", "[Acessórios]", "Fones|fones|Bluetooth e com fio", "Capas|cases|Proteção para seu device" ], "listButton": "Ver Catálogo", "footerText": "Preços sujeitos a alteração" } ``` ### 3. Enquetes (type: "poll") Cria enquetes interativas para votação. #### Campos Específicos - `selectableCount`: Número de opções que podem ser selecionadas (padrão: 1) - `choices`: Array simples com as opções de voto #### Exemplo Completo ```json { "number": "5511999999999", "type": "poll", "text": "Qual horário prefere para atendimento?", "choices": [ "Manhã (8h-12h)", "Tarde (13h-17h)", "Noite (18h-22h)" ], "selectableCount": 1 } ``` ### 4. Carousel (type: "carousel") Cria um carrossel de cartões com imagens e botões interativos. #### Campos Específicos - `choices`: Array com elementos do carrossel na seguinte ordem: - `[Texto do cartão]`: Texto do cartão entre colchetes - `{URL ou base64 da imagem}`: Imagem entre chaves - Botões do cartão (um por linha): - `"texto|copy:código"` para botão de copiar - `"texto|https://url"` para botão de link - `"texto|call:+número"` para botão de ligação #### Exemplo Completo ```json { "number": "5511999999999", "type": "carousel", "text": "Conheça nossos produtos", "choices": [ "[Smartphone XYZ\nO mais avançado smartphone da linha]", "{https://exemplo.com/produto1.jpg}", "Copiar Código|copy:PROD123", "Ver no Site|https://exemplo.com/xyz", "Fale Conosco|call:+5511999999999", "[Notebook ABC\nO notebook ideal para profissionais]", "{https://exemplo.com/produto2.jpg}", "Copiar Código|copy:NOTE456", "Comprar Online|https://exemplo.com/abc", "Suporte|call:+5511988888888" ] } ``` > **Nota**: Criamos outro endpoint para carrossel: `/send/carousel`, funciona da mesma forma, mas com outro formato de payload. Veja o que é mais fácil para você. ## Termos de uso Os recursos de botões interativos e listas podem ser descontinuados a qualquer momento sem aviso prévio. Não nos responsabilizamos por quaisquer alterações ou indisponibilidade destes recursos. ### Alternativas e Compatibilidade Considerando a natureza dinâmica destes recursos, nosso endpoint foi projetado para facilitar a migração entre diferentes tipos de mensagens (botões, listas e enquetes). Recomendamos criar seus fluxos de forma flexível, preparados para alternar entre os diferentes tipos. Em caso de descontinuidade de algum recurso, você poderá facilmente migrar para outro tipo de mensagem apenas alterando o campo "type" no payload, mantendo a mesma estrutura de choices. requestBody: required: true content: application/json: schema: type: object properties: number: type: string description: >- ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: '5511999999999' type: type: string description: >- Tipo do menu. Use button para o formato atual e button_legacy apenas para botões de resposta no formato anterior. enum: - button - button_legacy - list - poll - carousel example: list text: type: string description: Texto principal (aceita placeholders) example: 'Escolha uma opção:' footerText: type: string description: Texto do rodapé (opcional) example: Menu de serviços listButton: type: string description: Texto do botão principal example: Ver opções selectableCount: type: integer description: Número máximo de opções selecionáveis (para enquetes) example: 1 choices: type: array description: Lista de opções. Use [Título] para seções em listas items: type: string example: - '[Eletrônicos]' - Smartphones|phones|Últimos lançamentos - Notebooks|notes|Modelos 2024 - '[Acessórios]' - Fones|fones|Bluetooth e com fio - Capas|cases|Proteção para seu device file: type: string description: >- Mídia do cabeçalho (type: button): imagem, vídeo ou documento, por URL ou base64, como no `/send/media`. Áudio retorna `400`. example: https://exemplo.com/produto1.jpg mimetype: type: string description: >- Força o tipo do `file` (opcional): `image`, `video`, `document` ou o MIME type do arquivo, como `video/mp4`. Sem ele, o tipo sai do arquivo; outro valor responde `400`. example: video/mp4 docName: type: string description: >- Nome do arquivo quando o `file` é documento. Sem ele, o nome do arquivo. example: Tabela de preços.pdf replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 readchat: type: boolean description: Marca conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true delay: type: integer description: >- Atraso em milissegundos antes do envio, durante o atraso apacerá 'Digitando...' example: 1000 track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 async: type: boolean description: >- Se true, envia a mensagem de forma assíncrona via fila interna example: false required: - number - type - text - choices examples: button: summary: Botões de resposta value: number: '5511999999999' type: button text: Como podemos ajudar? choices: - Suporte|suporte - Fazer pedido|pedido list: summary: Lista de opções value: number: '5511999999999' type: list text: Escolha uma categoria listButton: Ver opções choices: - '[Atendimento]' - Suporte|suporte|Falar com o suporte - Financeiro|financeiro|Falar com o financeiro poll: summary: Enquete com uma escolha value: number: '5511999999999' type: poll text: Qual horário prefere? selectableCount: 1 choices: - Manhã - Tarde responses: '200': description: Menu enviado com sucesso content: application/json: schema: allOf: - $ref: '#/components/schemas/Message' - type: object properties: response: type: object properties: status: type: string example: success message: type: string example: Menu sent successfully '400': description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: Missing required fields or invalid menu type '401': description: Não autorizado content: application/json: schema: type: object properties: error: type: string example: Invalid token '429': description: Limite de requisições excedido content: application/json: schema: type: object properties: error: type: string example: Rate limit exceeded '500': description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to send menu components: schemas: Message: type: object description: Representa uma mensagem trocada no sistema properties: id: type: string format: uuid description: >- ID único interno da mensagem (formato r + 7 caracteres hex aleatórios) messageid: type: string description: ID original da mensagem no provedor chatid: type: string description: ID da conversa relacionada sender: type: string description: ID do remetente da mensagem senderName: type: string description: Nome exibido do remetente isGroup: type: boolean description: Indica se é uma mensagem de grupo default: false fromMe: type: boolean description: Indica se a mensagem foi enviada pelo usuário default: false messageType: type: string description: Tipo de conteúdo da mensagem source: type: string description: Plataforma de origem da mensagem messageTimestamp: type: integer description: Timestamp original da mensagem em milissegundos default: 0 status: type: string description: > Status do ciclo de vida da mensagem. Exemplos comuns: `Queued`, `Canceled`, `Failed`, `Sent`, `Delivered`, `Read`. Em mensagem de grupo, segue o participante mais adiantado: `Delivered` quando pelo menos um recebeu, `Read` quando pelo menos um leu e `Played` quando pelo menos um ouviu. text: type: string description: Texto original da mensagem default: '' quoted: type: string description: ID da mensagem citada/respondida default: '' edited: type: string description: Histórico de edições da mensagem default: '' reaction: type: string description: ID da mensagem reagida default: '' vote: type: string description: Dados de votação de enquete e listas default: '' convertOptions: type: string description: Conversão de opções da mensagem, lista, enquete e botões default: '' buttonOrListid: type: string description: ID do botão ou item de lista selecionado default: '' owner: type: string description: Dono da mensagem default: '' error: type: string description: Mensagem de erro caso o envio tenha falhado default: '' content: description: Conteúdo bruto da mensagem (JSON serializado ou texto) oneOf: - type: object additionalProperties: true - type: string description: Texto bruto quando não for JSON wasSentByApi: type: boolean description: Indica se a mensagem foi enviada via API pinned: type: boolean description: >- Mensagem fixada na conversa (fixar e desafixar chegam também em `messages_update`, tipos `Pinned` e `Unpinned`) sendFunction: type: string description: Função usada para enviar a mensagem (quando enviada via API) sendPayload: description: >- Payload usado no envio quando disponível. Dados de mídia em base64 são omitidos. oneOf: - type: object additionalProperties: true - type: string description: Texto bruto quando não for JSON fileURL: type: string description: URL ou referência de arquivo da mensagem callPeer: type: object description: >- Contato conhecido associado a uma ligação, quando disponível em `messageType: call`. properties: jid: type: string name: type: string imagePreviewUrl: type: string send_folder_id: type: string description: Pasta associada ao envio (quando aplicável) track_source: type: string description: Origem de rastreamento track_id: type: string description: ID de rastreamento (pode repetir) ai_metadata: type: object description: >- Registro de uma rodada da IA. O completo (pedido ao modelo, resposta e `outcome`) fica uma vez, na última mensagem do contato que a rodada respondeu, também quando nada saiu (erro, resposta descartada). Cada mensagem enviada pela IA leva só `agent_id` e `turn` (o `id` dessa mensagem do contato). properties: agent_id: type: string description: ID do agente de IA responsável turn: type: string description: >- Na mensagem enviada pela IA: o `id` da mensagem do contato onde está o registro completo da rodada. flow_id: type: string description: >- Mensagem enviada por um fluxo: o `id` do fluxo. A mensagem enviada pela IA traz o `agent_id`. request: type: object description: Dados da requisição à API de IA properties: messages: type: array description: Histórico de mensagens enviadas para a API tools: type: array description: Ferramentas disponíveis para o agente options: type: object description: Opções de configuração da API properties: model: type: string temperature: type: number maxTokens: type: integer topP: type: number frequencyPenalty: type: number presencePenalty: type: number response: type: object description: Resposta da API de IA properties: choices: type: array description: Resultados retornados pela API toolResults: type: array description: Resultados da execução de ferramentas error: type: string description: Mensagem de erro, se houver outcome: type: object description: O que a rodada fez de fato (só no registro completo). properties: status: type: string enum: - sent - cancelled - error - empty description: >- `sent`: enviou algo; `cancelled`: descartada (a conversa pausou, um fluxo começou ou bateu o limite de respostas por hora); `error`: o provedor falhou; `empty`: nada a enviar. texts: type: integer description: Mensagens de texto enviadas. audio: type: boolean description: Respondeu em áudio. menus: type: integer description: Menus enviados. files: type: integer description: Arquivos (mensagens cadastradas) enviados. handoff: type: string description: '`chamar_humano`: o resumo para quem atender.' lead: type: array items: type: string description: >- `atualizar_lead`: o que foi gravado no CRM (`lead_email = ana@exemplo.com; column = Agendado`). detail: type: string description: Por que foi descartada, ou o erro. sender_pn: description: JID PN resolvido do remetente (quando disponível) oneOf: - type: string - type: 'null' sender_lid: description: LID original do remetente (quando disponível) oneOf: - type: string - type: 'null' sender_image_preview_url: type: string format: uri description: >- URL temporária de preview do remetente, quando conhecida. A hidratação desta versão preenche mensagens recebidas em grupos; o campo pode ser omitido. Não provoca consulta de foto ao WhatsApp na listagem. securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.