Referência da API
API do Primux Omni
Integre o seu sistema ao Omni: envie mensagens de WhatsApp, cadastre contatos e leia os atendimentos e as respostas dos clientes. Tudo o que entra pela API aparece no Omni como uma conversa normal, e a sua equipe responde por lá.
https://dev-api.primux.cloud AuthBearer omn_… FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/omniVisão geral
A API fica no endereço central da Primux, em /v1/omni, e fala JSON em UTF-8. Você só precisa de uma chave: o resto (empresa, plano e servidor) a Primux resolve.
- Enviar mensagens de texto para qualquer número de WhatsApp pelo canal conectado da sua empresa.
- Cadastrar e consultar contatos, sem duplicar: o telefone identifica o contato.
- Listar os atendimentos e ler as mensagens, inclusive as respostas dos clientes.
- Consultar os canais (conexões de WhatsApp) e o estado de cada um.
{
"empresa": { "codigo": "minha-empresa" },
"chave": { "nome": "Sistema de pedidos", "acesso": "escrita" }
}Início rápido
- No console da Primux, abra Omni e, em API de integração, crie uma chave de leitura e escrita.
- Copie a chave (ela só aparece uma vez) e guarde em uma variável de ambiente, como PRIMUX_OMNI_CHAVE.
- Confira a chave em GET /v1/omni/eu e os canais em GET /v1/omni/canais.
- Envie uma mensagem com POST /v1/omni/mensagens e leia a conversa em GET /v1/omni/atendimentos/{id}/mensagens.
O exemplo envia uma mensagem e lê a conversa, tratando os erros da API.
# 1) envia a mensagem (cria o contato e o atendimento se não existirem)
curl -X POST "https://dev-api.primux.cloud/v1/omni/mensagens" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
-H "Content-Type: application/json" \
-d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'
# 2) lê a conversa (use o atendimento_id da resposta)
curl "https://dev-api.primux.cloud/v1/omni/atendimentos/ID_DO_ATENDIMENTO/mensagens" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$chave = getenv('PRIMUX_OMNI_CHAVE');
$base = 'https://dev-api.primux.cloud/v1/omni';
function chamar(string $metodo, string $url, ?array $corpo = null): array {
global $chave;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $metodo,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $chave, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $corpo ? json_encode($corpo) : null,
]);
$dados = json_decode(curl_exec($ch), true) ?? [];
return [curl_getinfo($ch, CURLINFO_HTTP_CODE), $dados];
}
[$status, $r] = chamar('POST', $base . '/mensagens', [
'para' => '77999999999',
'texto' => 'Olá! Seu pedido saiu para entrega.',
]);
if ($status >= 400) { exit("Erro {$status}: {$r['erro']} - {$r['mensagem']}\n"); }
// a mensagem virou um atendimento no Omni: a equipe responde por lá e você lê as respostas aqui
[$status, $c] = chamar('GET', "{$base}/atendimentos/{$r['atendimento_id']}/mensagens");
foreach ($c['mensagens'] as $m) { echo "[{$m['origem']}] {$m['texto']}\n"; }const chave = process.env.PRIMUX_OMNI_CHAVE;
const base = 'https://dev-api.primux.cloud/v1/omni';
async function chamar(metodo, url, corpo) {
const r = await fetch(url, {
method: metodo,
headers: { Authorization: `Bearer ${chave}`, 'Content-Type': 'application/json' },
body: corpo ? JSON.stringify(corpo) : undefined,
});
return { status: r.status, dados: await r.json() };
}
const envio = await chamar('POST', `${base}/mensagens`, {
para: '77999999999',
texto: 'Olá! Seu pedido saiu para entrega.',
});
if (envio.status >= 400) throw new Error(`${envio.status} ${envio.dados.erro}: ${envio.dados.mensagem}`);
// a mensagem virou um atendimento no Omni: a equipe responde por lá e você lê as respostas aqui
const conversa = await chamar('GET', `${base}/atendimentos/${envio.dados.atendimento_id}/mensagens`);
for (const m of conversa.dados.mensagens) console.log(`[${m.origem}] ${m.texto}`);import os, requests
BASE = "https://dev-api.primux.cloud/v1/omni"
sessao = requests.Session()
sessao.headers["Authorization"] = f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"
r = sessao.post(f"{BASE}/mensagens", json={
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega.",
}, timeout=15)
dados = r.json()
if r.status_code >= 400:
raise SystemExit(f"Erro {r.status_code}: {dados['erro']} - {dados['mensagem']}")
# a mensagem virou um atendimento no Omni: a equipe responde por lá e você lê as respostas aqui
conversa = sessao.get(f"{BASE}/atendimentos/{dados['atendimento_id']}/mensagens", timeout=15).json()
for m in conversa["mensagens"]:
print(f"[{m['origem']}] {m['texto']}")Chaves de API
Cada sistema que usa a API deve ter a sua chave, para você revogar uma sem afetar as outras.
- A chave aparece uma única vez, ao ser criada: copie na hora.
- Chaves de leitura só consultam; para enviar mensagens e cadastrar contatos use uma chave com escrita.
- Você pode ter até 10 chaves ativas e revogar qualquer uma na hora.
- Se a assinatura do Omni estiver suspensa ou cancelada, todas as chaves deixam de funcionar até a regularização.
export PRIMUX_OMNI_CHAVE="omn_COLE_AQUI_A_SUA_CHAVE"Autenticação
Envie a chave em todas as chamadas, no cabeçalho Authorization, no formato Bearer.
Authorization: Bearer omn_0123456789abcdefghijklmnopqrstuvwxyz0123456Referência da API
Empresa e chave
GET/v1/omni/eu
Devolve o código da empresa e o nome e o acesso da chave usada. Serve para conferir a chave.
curl -X GET "https://dev-api.primux.cloud/v1/omni/eu" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/eu');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/eu', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/eu",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"empresa": { "codigo": "minha-empresa" },
"chave": { "nome": "Sistema de pedidos", "acesso": "escrita" }
}Referência da API
Listar canais
GET/v1/omni/canais
Lista os canais (conexões de WhatsApp) da empresa e o estado de cada um: conectado, desconectado ou aguardando leitura do QR.
curl -X GET "https://dev-api.primux.cloud/v1/omni/canais" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/canais');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/canais', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/canais",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"canais": [
{
"id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
"nome": "Atendimento",
"tipo": "whatsapp",
"estado": "conectado",
"numero": "5577999999999"
}
]
}Referência da API
Enviar mensagem
POST/v1/omni/mensagens
Envia uma mensagem de texto. Se o número ainda não for contato, o contato é criado; a mensagem entra num atendimento aberto (ou abre um novo) que a equipe vê e responde no Omni. Sem canal_id usa o primeiro canal conectado; sem fila_id, a primeira fila. Exige chave com escrita.
Parâmetros do corpo
paratexto obrigatório- Telefone do destinatário, com DDD. Pode vir com máscara; o código do Brasil (55) é acrescentado se faltar.
textotexto obrigatório- Texto da mensagem, até 4096 caracteres.
Campos desconhecidos são ignorados.
curl -X POST "https://dev-api.primux.cloud/v1/omni/mensagens" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
-H "Content-Type: application/json" \
-d '{"nome":"Maria","para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/mensagens');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{"nome":"Maria","para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/mensagens', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega.",
"nome": "Maria"
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/omni/mensagens",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
json={
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega.",
"nome": "Maria"
},
timeout=15,
)
dados = resposta.json(){
"id": "b3c4d5e6-1111-4a2b-8c3d-9e0f1a2b3c4d",
"atendimento_id": "7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e",
"contato_id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
"canal_id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
"para": "5577999999999",
"estado": "enviada",
"enviada_em": "2026-11-11T14:30:00Z"
}Referência da API
Listar contatos
GET/v1/omni/contatos?busca=maria&limite=50
Lista os contatos da empresa, com busca por nome ou telefone e paginação (limite e deslocamento).
curl -X GET "https://dev-api.primux.cloud/v1/omni/contatos?busca=maria&limite=50" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/contatos?busca=maria&limite=50');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/contatos?busca=maria&limite=50', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/contatos?busca=maria&limite=50",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"contatos": [
{
"id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
"nome": "Maria",
"telefone": "5577999999999",
"etiquetas": ["cliente"],
"criado_em": "2026-11-11T14:30:00Z"
}
],
"total": 1
}Referência da API
Ver contato
GET/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f
Devolve um contato pelo id (UUID).
curl -X GET "https://dev-api.primux.cloud/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
"nome": "Maria",
"telefone": "5577999999999",
"etiquetas": ["cliente"],
"criado_em": "2026-11-11T14:30:00Z"
}Referência da API
Criar contato
POST/v1/omni/contatos
Cria um contato. Se o telefone já existir, devolve o contato existente com status 200, então a chamada pode ser repetida sem duplicar. Exige chave com escrita.
Parâmetros do corpo
telefonetexto obrigatório- Telefone do contato, com DDD.
nometexto obrigatório- Nome do contato (usado só ao criar um contato novo).
Campos desconhecidos são ignorados.
curl -X POST "https://dev-api.primux.cloud/v1/omni/contatos" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
-H "Content-Type: application/json" \
-d '{"etiquetas":["cliente"],"nome":"Maria","telefone":"(77) 99999-9999"}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/contatos');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{"etiquetas":["cliente"],"nome":"Maria","telefone":"(77) 99999-9999"}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/contatos', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"nome": "Maria",
"telefone": "(77) 99999-9999",
"etiquetas": ["cliente"]
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/omni/contatos",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
json={
"nome": "Maria",
"telefone": "(77) 99999-9999",
"etiquetas": ["cliente"]
},
timeout=15,
)
dados = resposta.json(){
"id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
"nome": "Maria",
"telefone": "5577999999999",
"etiquetas": ["cliente"],
"criado_em": "2026-11-11T14:30:00Z"
}Referência da API
Listar atendimentos
GET/v1/omni/atendimentos?estado=ativo&limite=50
Lista os atendimentos (conversas), do mais novo para o mais antigo, com filtro por estado e paginação.
curl -X GET "https://dev-api.primux.cloud/v1/omni/atendimentos?estado=ativo&limite=50" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/atendimentos?estado=ativo&limite=50');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/atendimentos?estado=ativo&limite=50', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/atendimentos?estado=ativo&limite=50",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"atendimentos": [
{
"id": "7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e",
"protocolo": "20261111-0001",
"contato_id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
"canal_id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
"fila_id": "5e6f7a8b-4444-4d5e-8f6a-2b3c4d5e6f7a",
"estado": "ativo",
"criado_em": "2026-11-11T14:30:00Z"
}
],
"total": 1
}Referência da API
Mensagens do atendimento
GET/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens
Lista as mensagens de um atendimento, com a origem de cada uma: cliente, equipe ou automacao. Notas internas da equipe nunca aparecem.
curl -X GET "https://dev-api.primux.cloud/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens" \
-H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_OMNI_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_OMNI_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"mensagens": [
{
"id": "b3c4d5e6-1111-4a2b-8c3d-9e0f1a2b3c4d",
"origem": "equipe",
"autor": "Primux",
"tipo": "texto",
"texto": "Olá! Seu pedido saiu para entrega.",
"enviada_em": "2026-11-11T14:30:00Z"
},
{
"id": "c4d5e6f7-5555-4e6f-9a7b-3c4d5e6f7a8b",
"origem": "cliente",
"autor": "Maria",
"tipo": "texto",
"texto": "Obrigada!",
"enviada_em": "2026-11-11T14:31:10Z"
}
],
"total": 2
}Campos e parâmetros
Parâmetros aceitos pela API, no corpo (JSON) ou na consulta (query string).
paratexto (telefone com DDD) obrigatório- Telefone do destinatário, com DDD. Pode vir com máscara; o código do Brasil (55) é acrescentado se faltar.
textotexto (até 4096) obrigatório- Texto da mensagem, até 4096 caracteres.
canal_idUUID (opcional: padrão, o primeiro canal conectado)- Canal usado no envio. Sem ele, vale o primeiro canal conectado.
fila_idUUID (opcional: padrão, a primeira fila)- Fila do atendimento quando ele for aberto. Sem ela, vale a primeira fila.
nometexto (opcional: nome do contato novo)- Nome do contato (usado só ao criar um contato novo).
telefonetexto (com DDD; o 55 do Brasil é acrescentado) obrigatório- Telefone do contato, com DDD.
etiquetaslista de textos- Etiquetas do contato.
estadoativo | espera | resolvido (filtro dos atendimentos)- Filtro dos atendimentos: ativo, espera ou resolvido.
buscatexto (nome ou telefone do contato)- Texto para procurar por nome ou telefone.
limiteinteiro (padrão 50, máximo 100)- Quantos itens devolver (padrão 50, máximo 100).
deslocamentointeiro (quantos itens pular)- Quantos itens pular, para paginar.
{
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega.",
"nome": "Maria"
}Erros
Os erros voltam em JSON com erro (código fixo, para o seu código tratar) e mensagem (texto para pessoas).
| Status | Código | Quando acontece |
|---|---|---|
| 400 | json_invalido | O corpo não é um JSON válido. |
| 401 | nao_autenticado | A chave não foi enviada no cabeçalho Authorization. |
| 401 | chave_invalida | Chave inválida ou revogada. |
| 402 | assinatura_bloqueada | A assinatura do Omni está suspensa ou cancelada. |
| 403 | empresa_inativa | A empresa está suspensa, cancelada ou com a cobrança em atraso. |
| 403 | sem_permissao | A chave é só de leitura e a rota exige escrita. |
| 404 | nao_encontrado | O contato ou o atendimento não existe. |
| 404 | rota_inexistente | A rota ou o método não existe. |
| 409 | canal_desconectado | Não há canal de WhatsApp conectado: conecte no Omni. |
| 409 | sem_fila | A empresa ainda não tem fila de atendimento. |
| 409 | envio_indisponivel | O atendimento não aceita envio agora (resolvido ou com envio desligado). |
| 413 | corpo_grande | O corpo passa de 64 KB. |
| 422 | telefone_invalido | Telefone inválido: informe DDD e número. |
| 422 | texto_invalido | O texto é obrigatório e vai até 4096 caracteres. |
| 422 | canal_invalido | O canal_id não existe nesta empresa. |
| 429 | limite_excedido | Passou do limite de 120 requisições por minuto da chave. |
| 502 | falha_envio | O WhatsApp não aceitou a mensagem agora: tente de novo. |
| 502 | servico_indisponivel | O Omni está indisponível no momento: tente de novo. |
{
"erro": "canal_desconectado",
"mensagem": "não há canal de WhatsApp conectado: conecte o WhatsApp no Omni"
}Limites e boas práticas
- 120 requisições por minuto por chave (429 limite_excedido, com o cabeçalho Retry-After).
- Corpo de até 64 KB por requisição.
- Texto de mensagem de até 4096 caracteres.
- Listas devolvem até 100 itens por chamada; use deslocamento para paginar.
- Os limites de atendentes e canais do seu plano valem dentro do Omni e também para a API.
Boas práticas
- Guarde a chave em variável de ambiente e use só no servidor.
- Dê um intervalo entre mensagens em lote: disparos em massa podem levar o WhatsApp a bloquear o número.
- Trate sempre o campo erro das respostas, não só o status.
- Repita só 429 e 502, com espera crescente.
Tentar de novo com segurança
Em 429 e 502 vale repetir a chamada depois de uma espera, respeitando o Retry-After quando existir.
import os, time, requests
def chamar(metodo, url, corpo=None, tentativas=4):
espera = 1
for _ in range(tentativas):
r = requests.request(metodo, url, json=corpo, timeout=15,
headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"})
if r.status_code not in (429, 502):
return r
time.sleep(float(r.headers.get("Retry-After", espera)))
espera *= 2
return rPerguntas frequentes
As mensagens enviadas pela API aparecem no Omni?
Sim. Cada mensagem vira parte de um atendimento do contato, que a equipe vê e responde normalmente no Omni.
Como recebo as respostas dos clientes?
Leia as mensagens do atendimento em GET /v1/omni/atendimentos/{id}/mensagens. As respostas vêm com origem cliente.
Posso enviar imagens e arquivos?
Nesta versão a API envia mensagens de texto. Imagens e arquivos podem ser enviados pela equipe no próprio Omni.
O que acontece se o WhatsApp estiver desconectado?
O envio falha com 409 canal_desconectado e nada é enviado. Conecte o canal no Omni e repita.
A API cobra por mensagem?
Não. O uso da API está incluído no plano do Omni, dentro dos limites de requisições.