PlugSend API - Guia de Integração

PlugSend API

Guia rápido para integração de envio de mensagens WhatsApp

📡 Endpoint

POST https://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

💻 Exemplo JavaScript

async function enviarMensagem(token, numero, mensagem) {
  // Remove tudo que não for número
  const numeroLimpo = numero.replace(/\D/g, "");
  
  const response = await fetch("https://plugsend.uazapi.com/send/text", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "token": token
    },
    body: JSON.stringify({
      number: numeroLimpo,
      text: mensagem,
      linkPreview: true
    })
  });
  
  return response.json();
}

// Uso:
enviarMensagem("SEU_TOKEN", "5511999999999", "Olá!");

🖥️ Exemplo cURL

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

🔧 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:

// Função utilitária para enviar WhatsApp via PlugSend
export async function enviarWhatsApp(
  token: string,
  numero: string,
  mensagem: string
): Promise<{ success: boolean; data?: any; error?: string }> {
  try {
    // Remove tudo que não for número
    const numeroLimpo = numero.replace(/\D/g, "");
    
    const response = await fetch("https://plugsend.uazapi.com/send/text", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "token": token
      },
      body: JSON.stringify({
        number: numeroLimpo,
        text: mensagem,
        linkPreview: true
      })
    });
    
    const data = await response.json();
    return { success: true, data };
  } catch (error) {
    return { 
      success: false, 
      error: error instanceof Error ? error.message : "Erro desconhecido"
    };
  }
}
💡 Como usar a função:
Após criar a função, você pode chamá-la assim:

const resultado = await enviarWhatsApp("SEU_TOKEN", "5511999999999", "Sua mensagem aqui");

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.

📎 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.

POST https://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.

📄 Exemplo: Enviar PDF por URL

{
  "number": "5511999999999",
  "type": "document",
  "file": "https://exemplo.com/contrato.pdf",
  "docName": "Contrato.pdf",
  "text": "Segue o documento solicitado"
}

📸 Exemplo: Enviar Imagem

{
  "number": "5511999999999",
  "type": "image",
  "file": "https://exemplo.com/foto.jpg",
  "text": "Veja esta foto!"
}

🖥️ cURL — Enviar Documento PDF

curl -X POST https://plugsend.uazapi.com/send/media \
  -H "Content-Type: application/json" \
  -H "token: SEU_TOKEN_AQUI" \
  -d '{
    "number": "5511999999999",
    "type": "document",
    "file": "https://exemplo.com/contrato.pdf",
    "docName": "Contrato.pdf",
    "text": "Segue o documento solicitado"
  }'

💻 Função JavaScript — Enviar Mídia

// Função utilitária para enviar mídia via PlugSend
export async function enviarMidia(
  token: string,
  numero: string,
  tipo: "image" | "video" | "document" | "audio" | "ptt" | "sticker",
  arquivoUrl: string,
  legenda?: string,
  nomeDocumento?: string
): Promise<{ success: boolean; data?: any; error?: string }> {
  try {
    const numeroLimpo = numero.replace(/\D/g, "");

    const body: any = {
      number: numeroLimpo,
      type: tipo,
      file: arquivoUrl,
    };

    // Adiciona legenda se informada
    if (legenda) body.text = legenda;

    // Adiciona nome do documento (só faz sentido para type "document")
    if (nomeDocumento && tipo === "document") {
      body.docName = nomeDocumento;
    }

    const response = await fetch("https://plugsend.uazapi.com/send/media", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "token": token
      },
      body: JSON.stringify(body)
    });

    const data = await response.json();
    return { success: true, data };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : "Erro desconhecido"
    };
  }
}
📎 Como usar a função:

Enviar PDF:
await enviarMidia("TOKEN", "5511999999999", "document", "https://site.com/arquivo.pdf", "Segue o contrato", "Contrato.pdf");

Enviar imagem:
await enviarMidia("TOKEN", "5511999999999", "image", "https://site.com/foto.jpg", "Confira a imagem!");

Enviar vídeo:
await enviarMidia("TOKEN", "5511999999999", "video", "https://site.com/video.mp4");

🚀 Prompt para Lovable — Envio de Documentos

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.

PlugSend API