P Primux Omni Documentação da API
API v1

Envie mensagens pelo Primux Omni

A API de integrações permite enviar mensagens WhatsApp a partir de sistemas externos, como ERPs, e-commerces, sistemas de cobrança e automações internas. Cada envio fica registrado no histórico do atendimento e aparece no painel em tempo real.

Método
POST
Endpoint
/api/v1/integracoes/mensagens
Formato
JSON · UTF-8
Importante: toda mensagem enviada por esta API pausa a automação do atendimento. O chatbot não responde no ticket criado ou utilizado pelo envio.

Autenticação

Toda requisição precisa de uma API key da empresa. Envie a chave em um dos cabeçalhos abaixo:

Recomendado
X-API-Key: px_sua_chave
Alternativa
Authorization: Bearer px_sua_chave
  • A chave é criada por empresa e pode ser revogada a qualquer momento.
  • O valor completo aparece apenas uma vez, no momento da criação.
  • Use sempre HTTPS e mantenha a chave em variável de ambiente, nunca no navegador.
  • Requisições sem chave válida recebem 401.

Criar uma chave

  1. Entre no Primux Omni com um usuário gestor.
  2. Abra Gestão → API Keys.
  3. No card API Keys, clique em + Nova.
  4. Dê um nome para identificar a integração (ex.: “ERP financeiro”).
  5. Copie a chave exibida e guarde-a em local seguro.

A mesma tela tem o botão Documentação da API, que abre esta página.

Enviar mensagem

Informe o contato por contato_id ou por telefone. Se o contato não existir, ele é criado. Se não houver atendimento aberto, um novo atendimento é criado automaticamente.

curl -X POST https://seu-dominio.com/api/v1/integracoes/mensagens \
  -H "X-API-Key: px_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "5511999999999",
    "nome_contato": "Maria Silva",
    "mensagem": "Olá, Maria! Sua fatura já está disponível."
  }'
Contato existente

Envie contato_id e a mensagem.

Contato novo

Envie telefone com DDD e código do país.

Campos do corpo

Campo Tipo Obrigatório Descrição
contato_idUUIDNão*ID do contato no Omni.
telefonestringNão*Telefone com DDI e DDD. Aceita máscara.
nome_contatostringNãoNome usado ao criar um contato novo.
mensagemstringSim**Texto da mensagem, até 8.000 caracteres.
tipo_midiastringNãotexto (padrão), imagem, audio, arquivo, figurinha.
url_arquivostringNão**URL pública da mídia.
canal_idUUIDCondicionalObrigatório quando há mais de um canal conectado.
fila_idUUIDNãoFila do novo atendimento. Usa a fila padrão do canal quando omitida.
usuario_idUUIDNãoResponsável pelo novo atendimento.
metadadosobjetoNãoDados auxiliares, templates e opções de mídia.
criar_atendimentobooleanNãoPadrão true. Com false, exige atendimento aberto.

* Informe ao menos um: contato_id ou telefone.
** Para mídia, informe url_arquivo ou uma legenda em mensagem.

Resposta

Status 201 Created:

{
  "mensagem_id": "4f6d1b3e-...",
  "atendimento_id": "b6f8a2c1-...",
  "contato_id": "1d9a7e42-...",
  "canal_id": "fa2c9e10-...",
  "protocolo": "OM-20261108-ABCD",
  "status": "enviada",
  "id_externo": "3EB0C1D2E3F4",
  "enviado_em": "2026-11-08T20:00:00Z",
  "criado": true,
  "mensagem": { "id": "4f6d1b3e-...", "conteudo": "Olá, Maria!", "...": "..." }
}
criado indica se um novo atendimento foi aberto nesta chamada.

Exemplos

Por telefone

curl -X POST https://seu-dominio.com/api/v1/integracoes/mensagens \
  -H "Authorization: Bearer px_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"+55 (11) 99999-9999","mensagem":"Olá!"}'

Por contato e canal

{
  "contato_id": "1d9a7e42-...",
  "canal_id": "fa2c9e10-...",
  "mensagem": "Seu pedido foi enviado.",
  "metadados": { "pedido_id": "PED-123" }
}

JavaScript

const resposta = await fetch('https://seu-dominio.com/api/v1/integracoes/mensagens', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.OMNI_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    telefone: '5511999999999',
    nome_contato: 'Maria Silva',
    mensagem: 'Olá, Maria!',
  }),
});

const dados = await resposta.json();
if (!resposta.ok) throw new Error(dados.erro);

Python

import os
import requests

resposta = requests.post(
    "https://seu-dominio.com/api/v1/integracoes/mensagens",
    headers={"X-API-Key": os.environ["OMNI_API_KEY"]},
    json={
        "telefone": "5511999999999",
        "nome_contato": "Maria Silva",
        "mensagem": "Olá, Maria!",
    },
    timeout=30,
)
resposta.raise_for_status()
print(resposta.json()["protocolo"])

Mídias

Para imagem, áudio, arquivo ou figurinha, informe tipo_midia e uma URL pública acessível pelo servidor do Omni:

{
  "telefone": "5511999999999",
  "tipo_midia": "imagem",
  "url_arquivo": "https://cdn.exemplo.com/faturas/123.pdf.png",
  "mensagem": "Segue sua fatura."
}
  • Prefira HTTPS e links sem autenticação por cookie.
  • O tamanho máximo depende do canal; mantenha arquivos abaixo de 16 MB.
  • No WhatsApp oficial (WABA), mídias e mensagens livres exigem janela de 24 horas ou template aprovado.

Erros

O formato de erro é sempre:

{ "erro": "descrição do problema" }
Status Quando ocorre Como resolver
400Dados inválidos ou campo obrigatório ausente.Revise o corpo e o formato do telefone.
401Chave ausente, inválida ou revogada.Gere uma nova chave em API Keys.
403Operação não permitida no atendimento.Verifique envio desabilitado ou permissões.
404Contato ou atendimento não encontrado.Confira os IDs ou use telefone.
409Atendimento resolvido ou estado incompatível.Abra um novo atendimento com criar_atendimento: true.
503Canal desconectado ou indisponível.Reconecte o WhatsApp no painel.

Boas práticas

  • Guarde a API key em variável de ambiente e nunca a exponha em código frontend.
  • Use telefone com DDI (ex.: 55) e DDD.
  • Não envie a mesma mensagem em loop; use campanhas para lotes.
  • Trate respostas 429 com espera progressiva quando houver limite do provedor.
  • Registre o mensagem_id e o protocolo retornados para auditoria.
  • Mensagens enviadas pela API pausam a automação do atendimento; para retomá-la, resolva o ticket e aguarde um novo contato.
WABA: mensagens livres só podem ser enviadas dentro da janela de 24 horas após a última mensagem do cliente. Fora da janela, use um template aprovado pela Meta.

OpenAPI

A especificação completa está disponível para importar no Postman, Insomnia ou gerar clientes: