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.
Autenticação
Toda requisição precisa de uma API key da empresa. Envie a chave em um dos cabeçalhos abaixo:
X-API-Key: px_sua_chave
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
- Entre no Primux Omni com um usuário gestor.
- Abra Gestão → API Keys.
- No card API Keys, clique em + Nova.
- Dê um nome para identificar a integração (ex.: “ERP financeiro”).
- 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."
}'
Envie contato_id e a mensagem.
Envie telefone com DDD e código do país.
Campos do corpo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| contato_id | UUID | Não* | ID do contato no Omni. |
| telefone | string | Não* | Telefone com DDI e DDD. Aceita máscara. |
| nome_contato | string | Não | Nome usado ao criar um contato novo. |
| mensagem | string | Sim** | Texto da mensagem, até 8.000 caracteres. |
| tipo_midia | string | Não | texto (padrão), imagem, audio, arquivo, figurinha. |
| url_arquivo | string | Não** | URL pública da mídia. |
| canal_id | UUID | Condicional | Obrigatório quando há mais de um canal conectado. |
| fila_id | UUID | Não | Fila do novo atendimento. Usa a fila padrão do canal quando omitida. |
| usuario_id | UUID | Não | Responsável pelo novo atendimento. |
| metadados | objeto | Não | Dados auxiliares, templates e opções de mídia. |
| criar_atendimento | boolean | Não | Padrã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!", "...": "..." }
}
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 |
|---|---|---|
| 400 | Dados inválidos ou campo obrigatório ausente. | Revise o corpo e o formato do telefone. |
| 401 | Chave ausente, inválida ou revogada. | Gere uma nova chave em API Keys. |
| 403 | Operação não permitida no atendimento. | Verifique envio desabilitado ou permissões. |
| 404 | Contato ou atendimento não encontrado. | Confira os IDs ou use telefone. |
| 409 | Atendimento resolvido ou estado incompatível. | Abra um novo atendimento com criar_atendimento: true. |
| 503 | Canal 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.
OpenAPI
A especificação completa está disponível para importar no Postman, Insomnia ou gerar clientes: