Pular para o conteúdo
PluguiZap

Tutoriais

Do zero à primeira mensagem nas ferramentas mais usadas por software houses. Antes, crie uma instância no painel e copie o ID, o Token e o Client-Token.

DelphiUnit pronta para XE7 ou mais novo, com Indy. PHPClasse sem dependências e um bot de exemplo. n8nNó HTTP para enviar e Webhook para receber. Java, C#, Python e NodeBibliotecas de um arquivo só, sem dependências. Go e qualquer linguagemCada rota da documentação tem exemplo em 8 linguagens. Receber mensagensWebhook em PHP, Node, Python, Java, C#, Delphi e Go.

Delphi: instalar a unit

  1. Baixe a unit ZapApi.pas e coloque na pasta do projeto.
  2. Adicione ZapApi no uses do formulário.
  3. Copie libeay32.dll e ssleay32.dll (OpenSSL 1.0.2, mesma arquitetura do seu .exe, 32 ou 64 bits) para a pasta do executável. Sem elas, o Indy não abre conexões https.
Funciona do Delphi XE7 em diante. Não usa componentes de terceiros: só Indy, System.JSON e System.NetEncoding.

Enviar texto e o boleto em PDF

uses ZapApi;

procedure TFormVendas.EnviarBoleto(const Celular, CaminhoPdf: string);
var
  Zap: TZapApi;
  R: TZapResposta;
begin
  Zap := TZapApi.Create('SEU_ID', 'SEU_TOKEN', 'SEU_CLIENT_TOKEN', 'https://api.pluguizap.com.br');
  try
    R := Zap.EnviarTexto(Celular, 'Olá! Segue o boleto da sua compra.');
    if not R.Ok then
      raise Exception.Create('WhatsApp: ' + R.Erro);

    // Imagens vão como imagem; PDF, XML e outros, como documento
    R := Zap.EnviarArquivo(Celular, CaminhoPdf, 'Vence dia 10');
    if not R.Ok then
      raise Exception.Create('WhatsApp: ' + R.Erro);
  finally
    Zap.Free;
  end;
end;

O telefone pode ir só com DDD (79999998888): a unit coloca o 55. Para não travar a tela, chame dentro de uma thread:

uses System.Threading;

TTask.Run(
  procedure
  begin
    EnviarBoleto('79999998888', 'C:\Boletos\1042.pdf');
  end);

Mostrar o QR Code dentro do seu sistema

Para o seu cliente conectar o número sem sair do sistema, coloque um TImage e um TTimer (intervalo de 3 segundos) no formulário:

uses ZapApi, System.NetEncoding, Vcl.Imaging.pngimage;

procedure TFormConectar.Timer1Timer(Sender: TObject);
var
  B64: string;
  Bytes: TBytes;
  Stream: TBytesStream;
  Png: TPngImage;
begin
  if FZap.Conectado then
  begin
    Timer1.Enabled := False;
    LabelStatus.Caption := 'WhatsApp conectado!';
    Image1.Picture := nil;
    Exit;
  end;
  B64 := FZap.QRCodeBase64;   // muda a cada ~20 segundos
  if B64 = '' then Exit;
  Bytes := TNetEncoding.Base64.DecodeStringToBytes(B64);
  Stream := TBytesStream.Create(Bytes);
  Png := TPngImage.Create;
  try
    Png.LoadFromStream(Stream);
    Image1.Picture.Assign(Png);
  finally
    Png.Free;
    Stream.Free;
  end;
end;

Prefere não mexer na tela? No painel, cada instância tem um link de conexão: mande para o seu cliente e ele lê o QR pelo navegador.

Receber mensagens no sistema Delphi

As mensagens recebidas chegam por webhook, que precisa de um endereço público na internet. O caminho mais simples para quem tem sistema desktop:

  1. Um webhook.php no seu servidor grava cada mensagem numa tabela do banco que o sistema já usa (veja o exemplo em PHP abaixo).
  2. O sistema Delphi lê essa tabela com um TTimer ou a cada abertura da tela de atendimento.

Se o seu sistema já tem um servidor REST (Horse, DataSnap, RAD Server), aponte o webhook direto para ele: o corpo é um JSON com phone, text.message e fromMe.

PHP: enviar com a classe

Baixe a classe ZapApi.php. Não tem dependências: precisa só da extensão curl, que já vem no PHP.

require 'ZapApi.php';

$zap = new ZapApi('SEU_ID', 'SEU_TOKEN', 'SEU_CLIENT_TOKEN', 'https://api.pluguizap.com.br');

$zap->texto('79999998888', 'Seu pedido #1042 saiu para entrega');
$zap->documento('79999998888', 'https://seusite.com.br/boletos/1042.pdf', 'boleto-1042.pdf', 'Segue o boleto');
$zap->arquivoLocal('79999998888', __DIR__ . '/notas/1042.pdf');   // arquivo do disco do servidor
$zap->enquete('79999998888', 'Confirma a consulta de amanhã às 9h?', ['Confirmo', 'Preciso remarcar']);

if (!$zap->temWhatsapp('79999998888')) {
    // o número não tem WhatsApp: mande SMS ou e-mail
}

Webhook com um bot simples

Configure a URL deste arquivo no painel da instância. Ele confere o segredo, grava a mensagem e responde um menu.

<?php
// webhook.php
require 'ZapApi.php';

const SEGREDO = 'SEGREDO_DO_WEBHOOK'; // painel: Credenciais da API, "Segredo do webhook"
if (!hash_equals(SEGREDO, $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '')) { http_response_code(401); exit; }

$m = json_decode(file_get_contents('php://input'), true);
http_response_code(200); // responda rápido: a API reenvia se demorar mais de 15 segundos

if (($m['type'] ?? '') !== 'ReceivedCallback' || !empty($m['fromMe']) || !empty($m['isGroup'])) exit;

$tel   = $m['phone'];
$texto = trim($m['text']['message'] ?? '');
$opcao = $m['buttonsResponseMessage']['buttonId'] ?? null; // resposta do menu: "1", "2"...

// Exemplo: gravar no banco que o seu sistema (Delphi, Java, .NET...) lê
// $pdo->prepare('INSERT INTO whatsapp_recebidas (telefone, texto, recebido_em) VALUES (?, ?, NOW())')->execute([$tel, $texto]);

$zap = new ZapApi('SEU_ID', 'SEU_TOKEN', 'SEU_CLIENT_TOKEN', 'https://api.pluguizap.com.br');
if ($opcao === '1') {
    $zap->texto($tel, 'Seu último pedido está a caminho.');
} elseif ($opcao === '2') {
    $zap->documento($tel, 'https://seusite.com.br/boletos/ultimo.pdf', 'boleto.pdf');
} else {
    $zap->botoes($tel, 'Olá! Como posso ajudar?', ['Status do pedido', 'Segunda via do boleto', 'Falar com atendente']);
}
Botões e listas chegam ao cliente como menu numerado ("responda 1, 2 ou 3"). Quando ele responde, o webhook traz buttonsResponseMessage.buttonId, no formato padrão de botão, então o seu bot não precisa tratar o número digitado.

n8n: enviar mensagem

  1. Adicione um nó HTTP Request.
  2. Method: POST. URL: https://api.pluguizap.com.br/instances/SEU_ID/token/SEU_TOKEN/send-text
  3. Em Send Headers, adicione Client-Token com o seu Client-Token.
  4. Em Send Body, escolha JSON e use o corpo abaixo. Os campos entre chaves duplas vêm dos nós anteriores.
{
  "phone": "{{ $json.telefone }}",
  "message": "Olá {{ $json.nome }}, seu pedido {{ $json.pedido }} foi confirmado!"
}

Para PDF, troque a rota por send-document/pdf e o corpo por {"phone": "...", "document": "https://link-do-pdf", "fileName": "boleto.pdf"}.

Receber mensagens no n8n

  1. Crie um fluxo começando com o nó Webhook, método POST, e copie a Production URL.
  2. Cole essa URL no campo de webhook da instância, no painel.
  3. Adicione um nó IF com a condição {{ $json.body.fromMe }} é falso, para não responder às suas próprias mensagens.
  4. O texto chega em {{ $json.body.text.message }} e o número em {{ $json.body.phone }}. Daí em diante, ligue no que quiser: planilha, CRM, um modelo de IA, outro HTTP Request para responder.
Para conferir que o aviso veio daqui, compare o cabeçalho {{ $json.headers["x-webhook-secret"] }} com o segredo do webhook mostrado no painel.

Precisa de outra linguagem?

Na documentação, cada rota tem exemplo em cURL, PHP e JavaScript. Para Java, C#, Python ou outra, é a mesma requisição HTTP. Se travar, chame o suporte.

Fale com a gente