Documentação PliVant

Começando com a PliVant API

A PliVant API fornece uma camada REST simplificada, padronizada e de altíssimo desempenho para a Meta WhatsApp Business Cloud API. Todas as requisições autenticadas devem enviar o header Authorization: Bearer plv_live_.... A chave já nasce vinculada a um projeto: não envie X-Project-Id. Em todo envio, use também Idempotency-Key (UUID ou ID do pedido). Para conciliar com CRM, ERP ou automações, envie opcionalmente metadata (até 20 chaves) e tags (até 20). Esses campos voltam nos webhooks messages.status e não são enviados à Meta. A API devolve headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

Se você não quer ler documentação técnica, use este mapa. Clique na tarefa que quer fazer e vá direto para a tela certa.

Envia uma mensagem de texto simples para um número de WhatsApp dentro da janela de 24 horas ou como resposta ativa.

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999998888",
    "type": "text",
    "text": "Pedido confirmado.",
    "metadata": { "order_id": "ord_123", "customer_id": "crm_42" },
    "tags": ["ecommerce", "checkout"]
  }'

{
  "id": "c3f1a8e2-7b14-4d90-9c2a-1f6e8b0d4a21",
  "status": "queued",
  "recipient": "5511999998888",
  "type": "text",
  "metadata": {
    "order_id": "ord_123",
    "customer_id": "crm_42"
  },
  "tags": [
    "ecommerce",
    "checkout"
  ],
  "created_at": "2026-09-20T01:30:00.000Z"
}

O POST responde 202 com status: "queued" assim que a mensagem entra na fila. Use este GET (escopo messages:read) ou o webhook messages.status para sent, delivered, read ou failed.

curl https://api.plivant.com.br/v1/messages/<MESSAGE_ID> \
  -H "Authorization: Bearer plv_live_SUA_CHAVE"

Envie arquivos diretamente via URL pública HTTPS acessível pela Cloud API da Meta. O sistema realiza o download seguro e o repasse transparente para o cliente.

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999998888",
    "type": "image",
    "mediaUrl": "https://meusite.com.br/uploads/recibo-pix.png",
    "caption": "Segue o comprovante oficial de pagamento da sua fatura."
  }'

Templates são obrigatórios para iniciar conversas ativas com clientes fora da janela de 24 horas (notificações de envio, alertas de segurança, cobranças Pix e recuperação de carrinho).

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999998888",
    "type": "template",
    "templateName": "notificacao_pedido_v1",
    "languageCode": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Carlos Alves" },
          { "type": "text", "text": "#4821" }
        ]
      }
    ]
  }'

Aumente as taxas de conversão e simplifique o fluxo de atendimento com botões clicáveis (Quick Reply) e listas suspensas (List Messages).

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999998888",
    "type": "interactive_buttons",
    "bodyText": "Deseja confirmar o agendamento da sua consulta para amanhã às 14h?",
    "headerText": "Confirmação de Consulta",
    "footerText": "Responda clicando em um dos botões abaixo",
    "buttons": [
      { "id": "btn_sim", "title": "Confirmar Sim" },
      { "id": "btn_nao", "title": "Reagendar" },
      { "id": "btn_falar", "title": "Falar com Humano" }
    ]
  }'

A Send API também aceita mensagens comerciais de catálogo e solicitação de contato. No Template Studio, você cria de forma guiada Carousel de mídia ou produtos, SPM/MPM, cupom Copy Code, oferta por tempo limitado, Authentication Template com OTP/COPY_CODE e o botão oficial REQUEST_CONTACT_INFO.

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: produto-42" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999998888",
    "type": "interactive_product",
    "catalogId": "catalog_123",
    "productRetailerId": "sku_42",
    "bodyText": "Confira este produto"
  }'

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Idempotency-Key: contato-lead-55" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "BR.2178496185888133",
    "type": "request_contact",
    "bodyText": "Compartilhe seu telefone para continuar."
  }'

curl -X POST https://api.plivant.com.br/v1/messages \
  -H "Authorization: Bearer plv_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "read_receipt",
    "messageId": "wamid.HBg...",
    "showTypingIndicator": true
  }'

Recursos avançados para desenvolvimento e migração. Todos continuam passando pela autenticação, isolamento de projeto, scopes, rate limit, logs e auditoria da PliVant.

A PliVant despacha requisições HTTP POST em tempo real para o seu servidor. Cada requisição acompanha o header criptográfico X-PliVant-Signature: t=<timestamp>,v1=<hmac> para validação inviolável de autenticidade.

import crypto from 'crypto';

// Express.js middleware para validar o header X-PliVant-Signature
export function verifyPliVantSignature(req, res, next) {
  const header = req.headers['x-plivant-signature'];
  const secret = process.env.PLIVANT_WEBHOOK_SECRET;

  if (!header || !secret) {
    return res.status(401).json({ error: 'Assinatura ausente ou webhook secret não configurado.' });
  }

  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const timestamp = parts['t'];
  const receivedHmac = parts['v1'];

  // Tolerância de tolerância a replay attack (5 minutos)
  const toleranceSeconds = 300;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > toleranceSeconds) {
    return res.status(401).json({ error: 'Timestamp expirado (replay attack detectado).' });
  }

  const payloadToSign = `${timestamp}.${req.rawBody || JSON.stringify(req.body)}`;
  const expectedHmac = crypto.createHmac('sha256', secret).update(payloadToSign).digest('hex');

  const isValid = crypto.timingSafeEqual(Buffer.from(receivedHmac, 'hex'), Buffer.from(expectedHmac, 'hex'));
  if (!isValid) {
    return res.status(403).json({ error: 'Assinatura HMAC inválida.' });
  }

  next();
}

Template é a mensagem aprovada pela Meta que você pode usar para iniciar ou retomar uma conversa. A PliVant centraliza criação, aprovação, sincronização, teste e exemplos de integração.

Use este caminho quando você quer que o próprio número oficial responda clientes automaticamente. O computador pode ficar desligado: a fila da PliVant executa o agente no servidor.

MCP é para quando você quer usar Codex, Claude, Cursor ou outro cliente compatível para operar a PliVant. Para atendimento automático do WhatsApp sem aplicativo aberto, prefira o Agente de IA nativo.

A PliVant utiliza códigos HTTP padronizados e códigos de erro específicos da Meta Graph API para que sua aplicação trate contingências de forma determinística.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Acesso bloqueado: a organização não possui uma assinatura ativa (Status atual: sem assinatura). Acesse o painel para regularizar."
}