PrimuxDocs

Referência da API

API de WhatsApp

Envie mensagens pelo seu número de WhatsApp com chamadas HTTP simples. Cada sessão é uma conexão independente, com plano, validade, chave e limites próprios.

Basehttps://dev-api.primux.cloud AuthBearer FormatoJSON · UTF-8
URL base
https://dev-api.primux.cloud/v1/whatsapp

Visão geral

A API conecta um número de WhatsApp (a sessão) à sua aplicação. Você contrata a sessão no console, conecta o número lendo um QR code ou digitando um código no celular e passa a enviar mensagens com uma chave de API.

  • Envio de texto para contatos e para grupos.
  • Envio de link com prévia (título, imagem e descrição da página).
  • Consulta da situação da sessão, dos grupos e do uso do dia e do mês.
Atenção: esta API usa a conexão de dispositivo vinculado do WhatsApp e não é a API oficial da Meta. O WhatsApp pode restringir números que enviam mensagens não solicitadas. Envie só para quem autorizou e leia os termos de uso.
Exemplo · situação da sessão
{
  "nome": "Atendimento",
  "plano": "WhatsApp 1.000",
  "estado": "conectada",
  "numero": "5577999999999",
  "valido_ate": "2026-12-03T14:30:00Z",
  "limite_diario": 1000,
  "limite_por_minuto": 20
}

Início rápido

  1. Contrate uma sessão em Console › APIs e aguarde a confirmação do pagamento.
  2. Conecte o número: no celular, abra WhatsApp › Aparelhos conectados e leia o QR code, ou escolha conectar por código de 8 caracteres.
  3. Gere a chave de API na página da sessão (ela aparece uma única vez; guarde como uma senha).
  4. Faça a primeira chamada, trocando SUA_CHAVE pela chave gerada:
Primeira chamada
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'

Autenticação

Envie a chave da sessão no cabeçalho Authorization, no formato Bearer. A chave é gerada no painel e mostrada uma única vez; gerar outra invalida a anterior. Guarde-a como uma senha e nunca a coloque em páginas ou aplicativos públicos.

Nunca coloque a chave em código de navegador, aplicativos distribuídos ou repositórios públicos. Use variáveis de ambiente no servidor. Se a chave vazar, gere outra na página da sessão: a anterior deixa de valer na hora.
Cabeçalho HTTP
Authorization: Bearer pxa_0123456789abcdef0123456789abcdef0123456789abcdef

Endereço e formato

Endereço da API: https://dev-api.primux.cloud

  • Todas as chamadas usam JSON em UTF-8 (cabeçalho Content-Type: application/json nos POST).
  • Campos que a API não conhece são recusados com o erro corpo_invalido.
  • Números aceitam máscara e símbolos; sem o código do país, o Brasil (+55) é assumido. Exemplos válidos: 77999999999, (77) 99999-9999, +55 77 99999-9999.
  • Datas e horas vêm em UTC, no formato ISO 8601 (2026-11-03T14:30:00Z).
Exemplo · resposta de envio
{
  "id": "3EB01931ACD50366D198B8",
  "estado": "enviada",
  "enviada_em": "2026-11-03T14:30:00Z"
}

Referência da API

Consultar a sessão

GET/v1/whatsapp/sessao

Situação da sessão: estado, número conectado, plano e validade. Use para saber se a sessão está conectada antes de enviar, e para ver o plano, a validade e os limites.

Esta rota não recebe corpo: só o cabeçalho de autenticação.

Requisição
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/sessao \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta 200
{
  "nome": "Atendimento",
  "plano": "WhatsApp 1.000",
  "estado": "conectada",
  "numero": "5577999999999",
  "valido_ate": "2026-12-03T14:30:00Z",
  "limite_diario": 1000,
  "limite_por_minuto": 20
}

Referência da API

Enviar mensagem

POST/v1/whatsapp/mensagens

Envia um texto para um contato (campos para e texto). Envia um texto para um contato. O campo para é o número do destinatário.

Parâmetros do corpo

para texto obrigatório
Número do contato (com ou sem máscara e código do país).
texto texto obrigatório
Texto da mensagem, até 4096 caracteres.
Requisição
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'
Resposta 200
{
  "id": "3EB01931ACD50366D198B8",
  "estado": "enviada",
  "enviada_em": "2026-11-03T14:30:00Z"
}

Referência da API

Enviar mensagem a um grupo

POST/v1/whatsapp/grupos/mensagens

Envia um texto para um grupo (campos grupo e texto). Envia um texto para um grupo. Pegue o identificador do grupo na rota de grupos.

Parâmetros do corpo

grupo texto obrigatório
Identificador do grupo (use a rota de grupos para listar).
texto texto obrigatório
Texto da mensagem, até 4096 caracteres.
Requisição
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/grupos/mensagens \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"grupo":"120363025246125486","texto":"Reunião às 15h."}'
Resposta 200
{
  "id": "3EB0A7C1D2E3F40516",
  "estado": "enviada",
  "enviada_em": "2026-11-03T14:31:10Z"
}

Referência da API

Enviar imagem

POST/v1/whatsapp/mensagens/imagem

Envia uma imagem PNG ou JPEG (em base64, até 5 MB) para um contato ou grupo, com legenda opcional. O campo imagem leva o arquivo codificado em base64 (sem o prefixo data:). Aceita PNG e JPEG de até 5 MB. Informe para (contato) ou grupo, nunca os dois. A legenda aparece junto da imagem.

Como gerar o base64: no Linux, base64 -w0 arquivo.pdf; em PHP, base64_encode(file_get_contents($arquivo)); em Node.js, fs.readFileSync(arquivo).toString('base64'); em Python, base64.b64encode(open(arquivo,'rb').read()).decode().

Parâmetros do corpo

para texto Um dos dois
Número do contato (com ou sem máscara e código do país).
grupo texto Um dos dois
Identificador do grupo (use a rota de grupos para listar).
imagem texto (base64) obrigatório
Imagem PNG ou JPEG em base64, até 5 MB (o corpo da requisição pode ter até 8 MB).
legenda texto opcional
Texto que acompanha a imagem ou o documento, até 4096 caracteres. Opcional.
Requisição
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens/imagem \\
  -H "Authorization: Bearer SUA_CHAVE" \\
  -H "Content-Type: application/json" \\
  -d "{\\"para\\":\\"77999999999\\",\\"imagem\\":\\"$(base64 -w0 comprovante.png)\\",\\"legenda\\":\\"Seu comprovante\\"}"
Resposta 200
{
  "id": "3EB0D1E2F3A4B5C6D7",
  "estado": "enviada",
  "enviada_em": "2026-11-03T14:33:10Z"
}

Referência da API

Enviar PDF

POST/v1/whatsapp/mensagens/documento

Envia um documento PDF (em base64, até 5 MB) para um contato ou grupo, com nome de arquivo e legenda opcionais. O campo documento leva o PDF codificado em base64 (sem prefixo), de até 5 MB. O campo arquivo define o nome que aparece no WhatsApp (a extensão .pdf é garantida). Informe para (contato) ou grupo, nunca os dois.

Como gerar o base64: no Linux, base64 -w0 arquivo.pdf; em PHP, base64_encode(file_get_contents($arquivo)); em Node.js, fs.readFileSync(arquivo).toString('base64'); em Python, base64.b64encode(open(arquivo,'rb').read()).decode().

Parâmetros do corpo

para texto Um dos dois
Número do contato (com ou sem máscara e código do país).
grupo texto Um dos dois
Identificador do grupo (use a rota de grupos para listar).
documento texto (base64) obrigatório
PDF em base64, até 5 MB (o corpo da requisição pode ter até 8 MB).
arquivo texto opcional
Nome do arquivo que o destinatário vê, ex.: fatura-128.pdf. Opcional.
legenda texto opcional
Texto que acompanha a imagem ou o documento, até 4096 caracteres. Opcional.
Requisição
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens/documento \\
  -H "Authorization: Bearer SUA_CHAVE" \\
  -H "Content-Type: application/json" \\
  -d "{\\"para\\":\\"77999999999\\",\\"documento\\":\\"$(base64 -w0 fatura-128.pdf)\\",\\"arquivo\\":\\"fatura-128.pdf\\",\\"legenda\\":\\"Sua fatura de novembro\\"}"
Resposta 200
{
  "id": "3EB0E2F3A4B5C6D7E8",
  "estado": "enviada",
  "enviada_em": "2026-11-03T14:34:20Z"
}

Referência da API

Listar grupos

GET/v1/whatsapp/grupos

Lista os grupos em que o número participa. Lista os grupos em que o número conectado participa, com identificador, nome e quantidade de participantes.

Esta rota não recebe corpo: só o cabeçalho de autenticação.

Requisição
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/grupos \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta 200
{
  "grupos": [
    { "id": "120363025246125486", "nome": "Equipe", "participantes": 12 }
  ]
}

Referência da API

Consultar o uso

GET/v1/whatsapp/uso

Uso do dia e do mês, por tipo, e o que resta do limite diário. Mostra quantas mensagens foram enviadas hoje e no mês, por tipo, e quanto resta do limite diário do plano.

Esta rota não recebe corpo: só o cabeçalho de autenticação.

Requisição
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/uso \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta 200
{
  "data": "2026-11-03",
  "hoje": { "mensagens": 41, "mensagens_em_grupo": 3, "links": 6, "imagens": 2, "documentos": 1, "total": 53 },
  "mes": { "mensagens": 812, "mensagens_em_grupo": 40, "links": 77, "imagens": 25, "documentos": 9, "total": 963 },
  "limite_diario": 1000,
  "restante_hoje": 947
}

Erros

Todo erro traz um código estável (campo erro) e uma mensagem em português (campo mensagem).

StatusCódigoQuando acontece
401chave_invalidaChave ausente, errada ou mal formatada.
403chave_de_outra_apiA chave pertence a outro tipo de API.
403sessao_suspensaA sessão foi suspensa por falta de pagamento.
403sessao_canceladaA sessão foi cancelada.
409sessao_nao_conectadaA sessão ainda não foi conectada ao WhatsApp ou foi desconectada.
422numero_invalidoO número informado não tem formato válido.
422numero_sem_whatsappO número não tem WhatsApp.
422grupo_invalidoIdentificador de grupo inválido.
422destino_invalidoCampo de destino na rota errada: contato em /mensagens, grupo em /grupos/mensagens.
422texto_vazioO texto é obrigatório.
422texto_grandeO texto passa de 4096 caracteres.
422url_invalidaLink inválido ou não público.
422imagem_invalidaImagem inválida: envie PNG ou JPEG de até 5 MB, em base64.
422documento_invalidoDocumento inválido: envie um PDF de até 5 MB, em base64.
400corpo_invalidoJSON inválido ou com campos desconhecidos.
429limite_por_minutoLimite de envios por minuto do plano atingido.
429limite_diarioLimite diário de envios do plano atingido.
502falha_no_envioO WhatsApp não aceitou a mensagem; tente de novo.
503servico_indisponivelO serviço não respondeu agora; tente de novo.
Resposta de erro
{
  "erro": "numero_sem_whatsapp",
  "mensagem": "Este número não tem WhatsApp."
}

Limites e boas práticas

  • O plano define o limite de envios por dia (zera à meia-noite) e por minuto; acima dele a API responde 429.
  • Números aceitam máscara; sem o código do país, o Brasil (+55) é assumido.
  • Textos têm até 4096 caracteres; links precisam ser http ou https públicos.
  • Envie só para quem autorizou receber mensagens. Spam é proibido e pode bloquear o seu número.
  • Imagens e PDFs têm até 5 MB (base64 no corpo, até 8 MB); só PNG, JPEG e PDF são aceitos.

Boas práticas

  • Consulte a rota de sessão antes de grandes envios: se o estado não for conectada, reconecte o número no console.
  • Espalhe os envios no tempo em vez de disparar tudo de uma vez; respeite o limite por minuto do plano.
  • Guarde o id devolvido em cada envio para rastrear a mensagem no seu sistema.
  • Trate os códigos de erro (campo erro), nunca o texto da mensagem, que pode mudar.
  • Mantenha o celular da sessão com internet e o WhatsApp atualizado.

Tentar de novo com segurança

Os erros 429 (limite), 502 (falha no envio) e 503 (serviço indisponível) podem ser repetidos com espera crescente. Os demais erros não melhoram sozinhos: corrija a requisição.

Tentar de novo com segurança
import time, requests

def enviar(url, chave, corpo, tentativas=4):
    espera = 1
    for _ in range(tentativas):
        r = requests.post(url, headers={"Authorization": f"Bearer {chave}"}, json=corpo, timeout=15)
        if r.status_code not in (429, 502, 503):
            return r
        time.sleep(espera)   # limite por minuto, falha no envio ou serviço indisponível
        espera *= 2
    return r

Estados da sessão

criada
A sessão foi criada e ainda não foi conectada ao WhatsApp.
aguardando_conexao
Aguardando a leitura do QR code ou a digitação do código no celular.
conectada
Pronta para enviar mensagens.
desconectada
O WhatsApp desconectou o aparelho (ou o celular ficou sem internet por muito tempo). Reconecte no console.
suspensa
Suspensa por falta de pagamento. Pague a renovação para a sessão voltar.

Perguntas frequentes

Posso usar o meu número pessoal?

Pode, mas recomendamos um número dedicado ao negócio: se o WhatsApp restringir o número por envio indevido, você não perde o seu contato pessoal.

A API recebe mensagens dos clientes?

Ainda não. A versão atual envia mensagens e consulta situação, grupos e uso. O recebimento (webhooks) entra em uma versão futura.

O que acontece se o celular ficar sem internet?

A sessão continua por um tempo, mas depois de muitos dias offline o WhatsApp pode desconectar o aparelho. Nesse caso o estado vira desconectada e basta reconectar.

Posso enviar imagens, áudios ou documentos?

Nesta versão, só texto e links com prévia.

Como troco a chave?

Na página da sessão, gere uma nova chave. A anterior deixa de valer imediatamente.