Guia rápido para integração de envio de mensagens WhatsApp
📡 Endpoint
POSThttps://plugsend.uazapi.com/send/text
📋 Headers
Header
Valor
Content-Type
application/json
token
Seu token da API
📦 Body (JSON)
Campo
Descrição
Status
number
Número formato internacional, apenas números (5511999999999)
Obrigatório
text
Mensagem a ser enviada
Obrigatório
linkPreview
Mostrar preview de links (true/false)
Opcional
⚠️ Importante sobre o número:
• Use apenas números, sem espaços, traços, parênteses ou caracteres especiais
• NÃO use o símbolo + no início
• Formato correto: 5511999999999
• Formato errado: +55 (11) 99999-9999
curl -X POST https://plugsend.uazapi.com/send/text \
-H "Content-Type: application/json" \
-H "token: SEU_TOKEN_AQUI" \
-d '{
"number": "5511999999999",
"text": "Olá, esta é uma mensagem de teste!",
"linkPreview": true
}'
🚀 Prompt para Lovable (Projeto Novo)
Copie este prompt simples para criar uma integração no Lovable:
Crie um formulário simples para enviar mensagens WhatsApp via API.
CAMPOS DO FORMULÁRIO:
• Token da API (campo de texto)
• Número do WhatsApp
• Mensagem (textarea)
FUNCIONALIDADE DE SALVAR TOKEN (para facilitar testes):
• Adicione um botão "Salvar Token" ao lado do campo de token
• Ao clicar, salve o token no localStorage do navegador
• Ao carregar a página, verifique se existe token salvo e preencha automaticamente
• Adicione também um botão "Limpar Token" para remover o token salvo
• Mostre uma indicação visual (ex: "✓ Token salvo") quando houver token armazenado
AO ENVIAR O FORMULÁRIO:
Faça um POST para: https://plugsend.uazapi.com/send/text
Headers:
- Content-Type: application/json
- token: (valor do campo token)
Body JSON:
{
"number": (número limpo),
"text": (mensagem),
"linkPreview": true
}
TRATAMENTO DO NÚMERO (IMPORTANTE):
Antes de enviar, remova TODOS os caracteres que não são números:
• Use: numero.replace(/\D/g, "")
• Formato final: apenas dígitos (ex: 5511999999999)
• NÃO inclua o símbolo + no início
• Remova espaços, traços, parênteses e qualquer caractere especial
FEEDBACK:
• Mostre loading enquanto envia
• Mostre mensagem de SUCESSO verde se a API retornar ok
• Mostre mensagem de ERRO vermelha se falhar
• Exiba o retorno da API para debug
Para Projetos Existentes
🔧 Integrando em um Projeto Lovable Existente
Se você já tem um sistema no Lovable e quer adicionar a funcionalidade de envio de WhatsApp, siga este passo a passo:
1Entenda a Estrutura da Chamada
A API do PlugSend recebe uma requisição POST com token no header e os dados no body.
2Crie a Função de Envio
Peça ao Lovable para criar uma função utilitária que você pode chamar de qualquer lugar do sistema.
3Integre no Fluxo Desejado
Use a função criada nos eventos do seu sistema (ex: após salvar pedido, confirmar agendamento, etc).
📝 Função Utilitária para Copiar
Peça ao Lovable para adicionar esta função ao seu projeto:
Se resultado.success for true, a mensagem foi enviada!
🎯 Prompt para Integrar em Projeto Existente
Copie o prompt abaixo e preencha os campos em destaque com as informações do seu projeto:
Preciso integrar envio de mensagens WhatsApp no meu projeto existente usando a API PlugSend.
═══════════════════════════════════════════
📌 ESPECIFICAÇÕES DA API:
═══════════════════════════════════════════
Endpoint: POST https://plugsend.uazapi.com/send/text
Headers:
- Content-Type: application/json
- token: (token da API - vou informar onde armazenar)
Body JSON:
{
"number": (número limpo, apenas dígitos, formato: 5511999999999),
"text": (mensagem a enviar),
"linkPreview": true
}
IMPORTANTE sobre o número:
- Remover TODOS os caracteres não numéricos antes de enviar
- Usar regex: numero.replace(/\D/g, "")
- NÃO incluir o símbolo + no início
- Formato final: apenas números (ex: 5511999999999)
═══════════════════════════════════════════
🎯 O QUE EU PRECISO:
═══════════════════════════════════════════
[DESCREVA AQUI O QUE VOCÊ PRECISA]
Exemplos do que escrever:
• "Quando um pedido for confirmado, enviar mensagem para o cliente"
• "Adicionar botão na tela de clientes para enviar WhatsApp"
• "Após agendar consulta, notificar paciente via WhatsApp"
• "Criar página de disparo em massa para lista de contatos"
• "Integrar com formulário de contato existente"
═══════════════════════════════════════════
📋 INFORMAÇÕES DO MEU PROJETO:
═══════════════════════════════════════════
• Onde está o número do telefone: [ex: campo "telefone" na tabela "clientes"]
• Onde guardar o token: [ex: variável de ambiente, tabela de config, fixo no código]
• Mensagem a enviar: [ex: "Seu pedido #123 foi confirmado!" ou template dinâmico]
═══════════════════════════════════════════
⚠️ Antes de usar o prompt:
1. Substitua [DESCREVA AQUI O QUE VOCÊ PRECISA] pela sua necessidade específica
2. Preencha as [informações do seu projeto] na seção final
3. Quanto mais detalhes você der, melhor será a implementação!
📚 Exemplos Práticos de Integração
Exemplo 1: Notificação de Pedido
🎯 O QUE EU PRECISO:
Quando o status de um pedido mudar para "confirmado", enviar automaticamente uma mensagem WhatsApp para o cliente com os detalhes do pedido.
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "phone" na tabela "customers"
• Onde guardar o token: variável de ambiente PLUGSEND_TOKEN
• Mensagem: "Olá {nome}! Seu pedido #{numero_pedido} foi confirmado. Valor: R$ {valor}. Previsão de entrega: {data_entrega}"
Exemplo 2: Confirmação de Agendamento
🎯 O QUE EU PRECISO:
Adicionar um botão "Enviar Confirmação" na tela de detalhes do agendamento que envia uma mensagem WhatsApp para o paciente confirmando data e hora.
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "celular" no objeto "paciente" relacionado ao agendamento
• Onde guardar o token: tabela "configuracoes" campo "whatsapp_token"
• Mensagem: "Olá! Confirmamos seu agendamento para {data} às {hora} com {profissional}. Endereço: {endereco}. Responda SIM para confirmar."
Exemplo 3: Lembrete Automático
🎯 O QUE EU PRECISO:
Criar uma função que roda todo dia às 8h e envia lembrete para clientes que têm agendamento no dia seguinte.
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "whatsapp" na tabela "agendamentos" junto com dados do cliente
• Onde guardar o token: variável de ambiente WHATSAPP_API_TOKEN
• Mensagem: "Lembrete: Você tem um compromisso amanhã ({data}) às {hora}. Caso precise reagendar, entre em contato."
💡 Dicas
Limpeza do número: Use regex para remover caracteres: numero.replace(/\D/g, "")
Formato internacional: Código do país + DDD + número
Brasil: 55 + 11 + 999999999 = 5511999999999
Armazenamento do Token: Prefira usar variáveis de ambiente ou tabela de configurações. Nunca deixe o token exposto no código frontend!
Tratamento de Erros: Sempre verifique o retorno da API e informe o usuário se houve sucesso ou falha no envio.
Envio de Mídia
📎 Enviar Documentos, Imagens e Mídias
Além de mensagens de texto, a API PlugSend permite enviar arquivos como PDFs, imagens, vídeos, áudios e mais.
Use o endpoint /send/media para isso.
POSThttps://plugsend.uazapi.com/send/media
📂 Tipos de Mídia Suportados
image
Imagens (JPG preferencialmente)
video
Vídeos (apenas MP4)
document
PDF, DOCX, XLSX, etc.
audio
Áudio comum (MP3 ou OGG)
ptt
Mensagem de voz (Push-to-Talk)
sticker
Figurinha/Sticker
videoplay
Vídeo com autoplay/loop
ptv
Mensagem de vídeo (Push-to-Video)
📦 Body — /send/media (JSON)
Campo
Descrição
Status
number
Número formato internacional, apenas números (5511999999999)
Obrigatório
type
Tipo de mídia: image, video, videoplay, document, audio, myaudio, ptt, ptv, sticker
Obrigatório
file
URL pública do arquivo ou string base64
Obrigatório
text
Legenda/caption do arquivo (aceita placeholders)
Opcional
docName
Nome exibido para o documento (ex: "Contrato.pdf") — apenas para type "document"
Opcional
mimetype
MIME type do arquivo (detectado automaticamente se omitido)
Opcional
thumbnail
URL ou base64 de thumbnail personalizado (para vídeos e documentos)
Opcional
viewOnce
Visualização única (funciona com image, video, videoplay, ptv, audio, myaudio, ptt)
Opcional
delay
Atraso em ms antes do envio (aparece "Digitando..." ou "Gravando áudio...")
Opcional
📄 Sobre o docName: Quando enviar um document, use o campo docName para definir o nome que aparecerá no WhatsApp do destinatário (ex: "Contrato.pdf", "Relatorio-Mensal.xlsx"). Sem ele, o arquivo aparecerá com um nome genérico.
Copie este prompt para criar um formulário de envio de documentos/mídias via WhatsApp no Lovable:
Crie um formulário para enviar documentos e mídias via WhatsApp usando a API PlugSend.
═══════════════════════════════════════════
📌 ESPECIFICAÇÕES DA API:
═══════════════════════════════════════════
Endpoint: POST https://plugsend.uazapi.com/send/media
Headers:
- Content-Type: application/json
- token: (valor do campo token)
Body JSON:
{
"number": (número limpo, apenas dígitos, formato: 5511999999999),
"type": (tipo de mídia),
"file": (URL pública do arquivo),
"text": (legenda opcional),
"docName": (nome do arquivo, apenas para documents)
}
═══════════════════════════════════════════
📎 CAMPOS DO FORMULÁRIO:
═══════════════════════════════════════════
• Token da API (campo de texto com botão "Salvar Token" — salvar no localStorage)
• Número do WhatsApp
• Tipo de mídia (select/dropdown com opções: document, image, video, audio, ptt, sticker)
• URL do arquivo (campo de texto para colar a URL pública do arquivo)
• Legenda (textarea, opcional)
• Nome do documento (campo de texto, só aparece quando tipo = "document")
═══════════════════════════════════════════
⚙️ COMPORTAMENTO:
═══════════════════════════════════════════
• Quando o tipo selecionado for "document", mostrar o campo "Nome do documento" (docName). Para os demais tipos, ocultar.
• Limpar o número antes de enviar: numero.replace(/\D/g, "")
• NÃO incluir o símbolo + no número
• Mostrar loading enquanto envia
• Mostrar mensagem de SUCESSO verde se a API retornar ok
• Mostrar mensagem de ERRO vermelha se falhar
• Exibir o JSON de retorno da API para debug
═══════════════════════════════════════════
📄 EXEMPLO DE BODY PARA DOCUMENTO PDF:
═══════════════════════════════════════════
{
"number": "5511999999999",
"type": "document",
"file": "https://exemplo.com/contrato.pdf",
"docName": "Contrato.pdf",
"text": "Segue o documento solicitado"
}
═══════════════════════════════════════════
📸 EXEMPLO DE BODY PARA IMAGEM:
═══════════════════════════════════════════
{
"number": "5511999999999",
"type": "image",
"file": "https://exemplo.com/foto.jpg",
"text": "Veja esta foto!"
}
🎯 Prompt — Integrar Envio de Documento em Projeto Existente
Copie e preencha os campos em destaque para integrar envio de documentos no seu projeto Lovable:
Preciso integrar envio de documentos/mídias via WhatsApp no meu projeto existente usando a API PlugSend.
═══════════════════════════════════════════
📌 ESPECIFICAÇÕES DA API (ENVIO DE MÍDIA):
═══════════════════════════════════════════
Endpoint: POST https://plugsend.uazapi.com/send/media
Headers:
- Content-Type: application/json
- token: (token da API)
Body JSON:
{
"number": (número limpo, apenas dígitos, formato: 5511999999999),
"type": "document",
"file": (URL pública do PDF ou base64 do arquivo),
"docName": (nome que aparecerá no WhatsApp, ex: "Contrato.pdf"),
"text": (legenda/caption opcional)
}
Tipos de mídia suportados: image, video, videoplay, document, audio, myaudio, ptt, ptv, sticker
IMPORTANTE sobre o número:
- Remover TODOS os caracteres não numéricos: numero.replace(/\D/g, "")
- NÃO incluir o símbolo + no início
- Formato final: apenas números (ex: 5511999999999)
IMPORTANTE sobre o arquivo:
- O campo "file" aceita URL pública ou string base64
- Para documentos, use "docName" para definir o nome exibido ao destinatário
- Se o mimetype não for detectado automaticamente, informe via campo "mimetype" (ex: "application/pdf")
═══════════════════════════════════════════
🎯 O QUE EU PRECISO:
═══════════════════════════════════════════
[DESCREVA AQUI O QUE VOCÊ PRECISA]
Exemplos:
• "Após gerar um orçamento em PDF, enviar automaticamente para o cliente via WhatsApp"
• "Adicionar botão 'Enviar PDF' na tela de detalhes do pedido"
• "Quando um contrato for assinado, enviar cópia em PDF para o cliente"
• "Permitir que o usuário selecione documentos da lista e envie em massa"
• "Enviar comprovante de pagamento (imagem ou PDF) para o cliente"
═══════════════════════════════════════════
📋 INFORMAÇÕES DO MEU PROJETO:
═══════════════════════════════════════════
• Onde está o número do telefone: [ex: campo "telefone" na tabela "clientes"]
• Onde está a URL do arquivo: [ex: campo "pdf_url" na tabela "orcamentos", ou gerado dinamicamente]
• Onde guardar o token: [ex: variável de ambiente, tabela de config]
• Nome do documento: [ex: "Orcamento-{id}.pdf" ou fixo "Documento.pdf"]
• Legenda a enviar: [ex: "Olá {nome}, segue seu orçamento em anexo."]
═══════════════════════════════════════════
⚠️ Antes de usar o prompt:
1. Substitua [DESCREVA AQUI O QUE VOCÊ PRECISA] pela sua necessidade
2. Preencha as [informações do projeto] na seção final
3. Certifique-se de que a URL do arquivo é pública e acessível (URLs privadas ou locais não funcionam)
📚 Exemplos Práticos — Envio de Documentos
Exemplo 1: Enviar Orçamento em PDF
🎯 O QUE EU PRECISO:
Quando o usuário clicar em "Enviar Orçamento" na tela de detalhes do orçamento, enviar o PDF gerado para o cliente via WhatsApp com uma mensagem personalizada.
📌 API DE MÍDIA:
Endpoint: POST https://plugsend.uazapi.com/send/media
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "phone" na tabela "customers"
• Onde está o PDF: campo "pdf_url" na tabela "quotes" (URL pública do Supabase Storage)
• Onde guardar o token: variável de ambiente PLUGSEND_TOKEN
• Nome do documento: "Orcamento-{quote_number}.pdf"
• Legenda: "Olá {nome}! Segue o orçamento #{numero} no valor de R$ {valor}. Qualquer dúvida estamos à disposição!"
Body de exemplo:
{
"number": "5511999999999",
"type": "document",
"file": "https://supabase.co/storage/orcamento-001.pdf",
"docName": "Orcamento-001.pdf",
"text": "Olá João! Segue o orçamento #001 no valor de R$ 1.500,00."
}
Exemplo 2: Enviar Comprovante de Pagamento (Imagem)
🎯 O QUE EU PRECISO:
Após registrar um pagamento no sistema, enviar automaticamente o comprovante (imagem PNG/JPG) para o cliente via WhatsApp.
📌 API DE MÍDIA:
Endpoint: POST https://plugsend.uazapi.com/send/media
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "whatsapp" na tabela "clients"
• Onde está a imagem: campo "receipt_url" na tabela "payments" (URL pública)
• Onde guardar o token: tabela "settings" campo "plugsend_token"
• Legenda: "Pagamento de R$ {valor} confirmado! Segue o comprovante."
Body de exemplo:
{
"number": "5511999999999",
"type": "image",
"file": "https://storage.exemplo.com/comprovante-12345.png",
"text": "Pagamento de R$ 350,00 confirmado! Segue o comprovante."
}
Exemplo 3: Enviar Contrato PDF após Assinatura
🎯 O QUE EU PRECISO:
Quando o campo "status" do contrato mudar para "assinado", disparar automaticamente o PDF do contrato para o cliente via WhatsApp.
📌 API DE MÍDIA:
Endpoint: POST https://plugsend.uazapi.com/send/media
📋 INFORMAÇÕES DO MEU PROJETO:
• Onde está o número: campo "celular" na tabela "clientes", vinculado via "cliente_id" no contrato
• Onde está o PDF: campo "contract_pdf_url" na tabela "contratos"
• Onde guardar o token: variável de ambiente WHATSAPP_API_TOKEN
• Nome do documento: "Contrato-{contract_id}.pdf"
• Legenda: "Olá {nome}! Seu contrato #{id} foi assinado com sucesso. Segue a cópia em anexo para seus registros."
Body de exemplo:
{
"number": "5511999999999",
"type": "document",
"file": "https://storage.exemplo.com/contrato-789.pdf",
"docName": "Contrato-789.pdf",
"text": "Olá Maria! Seu contrato #789 foi assinado com sucesso. Segue a cópia em anexo."
}
💡 Dicas — Envio de Mídia
URL pública obrigatória: O campo file deve ser uma URL acessível publicamente (ex: Supabase Storage, S3, Cloudflare R2). URLs internas ou protegidas por autenticação não funcionam.
Alternativa com base64: Se não tiver URL pública, converta o arquivo para base64 e envie no campo file. Útil para arquivos gerados dinamicamente no backend.
Nome do documento: Sempre use docName ao enviar type "document". Sem ele, o destinatário verá um nome genérico. Inclua a extensão (ex: .pdf, .xlsx).
Tamanho do arquivo: Respeite os limites do WhatsApp — documentos até 100 MB, imagens até 16 MB, vídeos até 16 MB. A API retorna erro 413 se exceder.
Visualização única: Use "viewOnce": true para enviar imagens, vídeos ou áudios que só podem ser vistos uma vez. Não funciona com document ou sticker.