Integre o WhatsApp ao seu sistema. Envie mensagens, gerencie contatos e acompanhe conversas de forma programatica atraves da nossa API REST.
https://api.omniwhats.comJSON (Content-Type: application/json)
API Key via header X-API-Key
/api/v1. Versoes futuras serao comunicadas com antecedencia.A API usa API Keys para autenticação. Cada chave está vinculada a um tenant e possui scopes que limitam quais operações podem ser realizadas.
As chaves seguem o formato omni_ seguido de 64 caracteres hexadecimais (total de 69 caracteres).
Envie a API key em um dos seguintes headers:
# Opcao 1: Header X-API-Key
curl -H "X-API-Key: omni_sua_api_key_aqui" https://api.omniwhats.com/contacts
# Opcao 2: Header Authorization Bearer
curl -H "Authorization: Bearer omni_sua_api_key_aqui" https://api.omniwhats.com/contactsAcesse o painel OmniWhats em Configurações > Integrações > API Keys para criar e gerenciar suas chaves. A chave completa só é exibida uma vez no momento da criação.
| Scope | Permissao |
|---|---|
contacts:read | Listar e visualizar contatos |
contacts:write | Criar e atualizar contatos |
conversations:read | Listar e visualizar conversas |
conversations:write | Atualizar conversas (status, atribuição) |
messages:read | Visualizar histórico de mensagens |
messages:send | Enviar mensagens de texto e mídia |
[]) tem acesso total (admin).A API utiliza um sistema de janela deslizante (sliding window) por minuto, por API Key. O limite padrão é de 60 requisições por minuto, configurável por chave.
| Header | Descricao |
|---|---|
X-RateLimit-Limit | Numero maximo de requisições por minuto |
X-RateLimit-Remaining | Requisições restantes na janela atual |
Retry-After | Segundos até poder tentar novamente (apenas em 429) |
429 Too Many Requests, aguarde o numero de segundos indicado no header Retry-After antes de tentar novamente.Todas as respostas de erro seguem um formato padronizado:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descricao legivel do erro"
}
}| Codigo | Status | Descricao |
|---|---|---|
MISSING_API_KEY | 401 | |
INVALID_API_KEY | 401 | |
API_KEY_DISABLED | 403 | |
API_KEY_EXPIRED | 403 | |
INSUFFICIENT_SCOPE | 403 | |
RATE_LIMIT_EXCEEDED | 429 | |
MISSING_FIELDS | 400 | |
INVALID_PHONE | 400 | |
INVALID_TYPE | 400 | |
NOT_FOUND | 404 | |
NO_SESSION | 422 |
https://api.omniwhats.com/contactsRetorna uma lista paginada de contatos do tenant. Suporta busca por nome, telefone ou email.
contacts:readpage1limit20search{
"success": true,
"data": [
{
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"phone": "5511999887766",
"email": "maria@email.com",
"whatsappId": "5511999887766@s.whatsapp.net",
"avatarUrl": null,
"notes": "Cliente VIP",
"tags": [],
"customFields": {},
"lastSeenAt": "2026-04-07T14:30:00.000Z",
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-04-07T14:30:00.000Z"
}
],
"meta": {
"total": 150,
"page": 1,
"limit": 20,
"hasMore": true
}
}https://api.omniwhats.com/contactsCria um novo contato ou retorna o existente se o telefone já estiver cadastrado. O telefone é automaticamente normalizado (apenas dígitos) e convertido para o formato WhatsApp. Retorna 201 Created quando um novo contato e criado, ou 200 OK quando o contato ja existe.
contacts:writephoneobrigatorionameemailnotescustomFields{
"success": true,
"data": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Joao Santos",
"phone": "5511988776655",
"email": "joao@email.com",
"whatsappId": "5511988776655@s.whatsapp.net",
"avatarUrl": null,
"notes": null,
"tags": [],
"customFields": {},
"lastSeenAt": null,
"createdAt": "2026-04-07T15:00:00.000Z",
"updatedAt": "2026-04-07T15:00:00.000Z"
},
"meta": {
"created": true
}
}https://api.omniwhats.com/contacts/:idRetorna os detalhes completos de um contato, incluindo a contagem de conversas associadas.
contacts:read{
"success": true,
"data": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"phone": "5511999887766",
"email": "maria@email.com",
"whatsappId": "5511999887766@s.whatsapp.net",
"avatarUrl": null,
"notes": "Cliente VIP",
"tags": [],
"customFields": {},
"conversationsCount": 5,
"lastSeenAt": "2026-04-07T14:30:00.000Z",
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-04-07T14:30:00.000Z"
}
}https://api.omniwhats.com/contacts/:idAtualiza os dados de um contato existente. Apenas os campos enviados serão atualizados.
contacts:writenameemailnotescustomFields{
"success": true,
"data": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva Santos",
"phone": "5511999887766",
"email": "maria.nova@email.com",
"whatsappId": "5511999887766@s.whatsapp.net",
"avatarUrl": null,
"notes": "Cliente VIP - Plano Enterprise",
"tags": [],
"customFields": {
"empresa": "Acme Corp"
},
"lastSeenAt": "2026-04-07T14:30:00.000Z",
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-04-07T16:00:00.000Z"
}
}https://api.omniwhats.com/conversationsRetorna uma lista paginada de conversas. Permite filtrar por status e contato.
conversations:readpage1limit20statuscontactId{
"success": true,
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"sessionId": "s1234567-89ab-cdef-0123-456789abcdef",
"assignedUserId": "u1234567-89ab-cdef-0123-456789abcdef",
"departmentId": null,
"status": "open",
"protocol": "ATD-2026-0001",
"lastMessage": "Obrigado pelo atendimento!",
"lastMessageAt": "2026-04-07T15:30:00.000Z",
"unreadCount": 0,
"isGroup": false,
"tags": [],
"createdAt": "2026-04-07T10:00:00.000Z",
"updatedAt": "2026-04-07T15:30:00.000Z",
"contact": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"phone": "5511999887766",
"avatarUrl": null
},
"assignedUser": {
"id": "u1234567-89ab-cdef-0123-456789abcdef",
"name": "Carlos Atendente"
}
}
],
"meta": {
"total": 45,
"page": 1,
"limit": 20,
"hasMore": true
}
}https://api.omniwhats.com/conversations/:idRetorna os detalhes completos de uma conversa, incluindo contato, atendente atribuido, departamento e contagem de mensagens.
conversations:read{
"success": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"sessionId": "s1234567-89ab-cdef-0123-456789abcdef",
"assignedUserId": "u1234567-89ab-cdef-0123-456789abcdef",
"departmentId": "d1234567-89ab-cdef-0123-456789abcdef",
"status": "open",
"protocol": "ATD-2026-0001",
"lastMessage": "Obrigado pelo atendimento!",
"lastMessageAt": "2026-04-07T15:30:00.000Z",
"unreadCount": 0,
"isGroup": false,
"tags": [],
"createdAt": "2026-04-07T10:00:00.000Z",
"updatedAt": "2026-04-07T15:30:00.000Z",
"messagesCount": 23,
"contact": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"phone": "5511999887766",
"email": "maria@email.com",
"avatarUrl": null
},
"assignedUser": {
"id": "u1234567-89ab-cdef-0123-456789abcdef",
"name": "Carlos Atendente",
"email": "carlos@empresa.com"
},
"department": {
"id": "d1234567-89ab-cdef-0123-456789abcdef",
"name": "Suporte"
}
}
}https://api.omniwhats.com/conversations/:idAtualiza o status, atendente ou departamento de uma conversa. Ao fechar (status: "closed"), o campo closedAt é automaticamente preenchido.
conversations:writestatusassignedUserIddepartmentId{
"success": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"sessionId": "s1234567-89ab-cdef-0123-456789abcdef",
"assignedUserId": "u1234567-89ab-cdef-0123-456789abcdef",
"departmentId": null,
"status": "closed",
"protocol": "ATD-2026-0001",
"lastMessage": "Obrigado pelo atendimento!",
"lastMessageAt": "2026-04-07T15:30:00.000Z",
"unreadCount": 0,
"isGroup": false,
"tags": [],
"closedAt": "2026-04-07T16:00:00.000Z",
"createdAt": "2026-04-07T10:00:00.000Z",
"updatedAt": "2026-04-07T16:00:00.000Z",
"contact": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"phone": "5511999887766"
},
"assignedUser": {
"id": "u1234567-89ab-cdef-0123-456789abcdef",
"name": "Carlos Atendente"
}
}
}https://api.omniwhats.com/messages/:conversationIdRetorna o histórico de mensagens de uma conversa, ordenadas da mais recente para a mais antiga.
messages:readpage1limit50{
"success": true,
"data": [
{
"id": "m1234567-89ab-cdef-0123-456789abcdef",
"senderType": "contact",
"senderId": null,
"type": "text",
"content": "Ola, preciso de ajuda com meu pedido",
"mediaUrl": null,
"mediaMimeType": null,
"mediaFilename": null,
"status": "read",
"isFromMe": false,
"whatsappMsgId": "3EB0A1B2C3D4E5F6",
"createdAt": "2026-04-07T14:00:00.000Z"
},
{
"id": "m2345678-9abc-def0-1234-567890abcdef",
"senderType": "user",
"senderId": "u1234567-89ab-cdef-0123-456789abcdef",
"type": "text",
"content": "Claro! Qual o número do seu pedido?",
"mediaUrl": null,
"mediaMimeType": null,
"mediaFilename": null,
"status": "delivered",
"isFromMe": true,
"whatsappMsgId": "3EB0B2C3D4E5F6A7",
"createdAt": "2026-04-07T14:01:00.000Z"
}
],
"meta": {
"total": 23,
"page": 1,
"limit": 50,
"hasMore": false
}
}https://api.omniwhats.com/messages/sendEnvia uma mensagem de texto via WhatsApp. Cria automaticamente o contato e a conversa se não existirem. Usa a sessão WhatsApp padrão do tenant ou a especificada.
messages:sendphoneobrigatoriomessageobrigatoriosessionIdname{
"success": true,
"data": {
"messageId": "m3456789-abcd-ef01-2345-6789abcdef01",
"conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"status": "sent"
}
}https://api.omniwhats.com/messages/send-mediaEnvia uma mensagem com arquivo de mídia (imagem, vídeo, áudio ou documento) via WhatsApp. A URL da mídia deve ser acessível publicamente.
messages:sendphoneobrigatoriomediaUrlobrigatoriotypeobrigatoriocaptionsessionIdname{
"success": true,
"data": {
"messageId": "m4567890-bcde-f012-3456-789abcdef012",
"conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"status": "sent"
}
}Outbound Webhooks permitem que o OmniWhats envie eventos em tempo real para sistemas externos (n8n, Make, Zapier, seu backend, etc.) sempre que algo acontece — como uma mensagem recebida, conversa criada ou negocio fechado.
Selecione quais eventos o webhook deve disparar. Voce pode filtrar por canal especifico ou receber de todos.
| Evento | Descricao |
|---|---|
message.received | Cliente envia uma mensagem |
message.sent | Atendente envia uma mensagem |
message.updated | Status da mensagem muda (entregue, lida) |
message.transcribed | Áudio é transcrito automaticamente |
conversation.created | Nova conversa é iniciada |
conversation.updated | Conversa é modificada |
conversation.assigned | Conversa atribuída a atendente/departamento |
conversation.closed | Conversa é encerrada |
contact.created | Novo contato é criado |
contact.updated | Contato é atualizado |
channel.status_changed | Canal conecta ou desconecta |
deal.moved | Negócio muda de etapa no funil |
deal.won | Negócio marcado como ganho |
Todos os webhooks enviam um POST com JSON no seguinte formato:
{
"event": "message.received",
"timestamp": "2026-04-07T10:30:00.000Z",
"delivery_id": "dlv_a1b2c3d4-e5f6-7890",
"tenant": {
"id": "tenant-uuid",
"name": "Minha Empresa"
},
"data": {
"message": {
"id": "msg-uuid",
"type": "text",
"content": "Olá, preciso de ajuda!",
"senderType": "contact",
"status": "received",
"isFromMe": false,
"createdAt": "2026-04-07T10:30:00.000Z"
},
"contact": {
"id": "contact-uuid",
"name": "Maria Silva",
"phone": "5511999887766",
"email": "maria@email.com"
},
"conversation": {
"id": "conv-uuid",
"status": "open",
"channelType": "whatsapp",
"assignedUserId": null
},
"channel": {
"id": "channel-uuid",
"name": "WhatsApp Principal",
"type": "whatsapp",
"status": "connected"
}
}
}O campo data varia conforme o evento. Eventos de mensagem incluem message, contact, conversation e channel. Eventos de contato incluem apenas contact.
Cada entrega inclui uma assinatura HMAC-SHA256 para que você possa validar a autenticidade da requisição.
| Header | Descricao |
|---|---|
X-OmniWhats-Signature | Assinatura HMAC-SHA256 para validação (sha256=...) |
X-OmniWhats-Timestamp | Timestamp Unix em segundos da requisição |
X-OmniWhats-Delivery | UUID único desta entrega (para deduplicação) |
Content-Type | Sempre application/json |
// Validacao da assinatura (Node.js)
const crypto = require('crypto');
const timestamp = req.headers['x-omniwhats-timestamp'];
const signature = req.headers['x-omniwhats-signature'];
const body = JSON.stringify(req.body);
const expected = 'sha256=' + crypto
.createHmac('sha256', SEU_SECRET)
.update(timestamp + '.' + body)
.digest('hex');
if (signature !== expected) {
throw new Error('Assinatura invalida');
}O n8n e uma plataforma de automacao que permite conectar centenas de servicos. A integração funciona via webhooks: o OmniWhats envia eventos para o n8n, e o n8n envia mensagens de volta para o WhatsApp.
Basta colar a URL do webhook do n8n no OmniWhats. Com um único link, o n8n recebe eventos e pode responder automaticamente.
No n8n, adicione um nó "Webhook" como trigger do workflow. Copie a URL de produção gerada (ex: https://seu-n8n.com/webhook/abc123).
No painel OmniWhats, vá em Configurações > Integrações > Outbound Webhooks > Novo. Cole a URL do n8n e selecione os eventos.
Nome: Meu n8n
URL: https://seu-n8n.com/webhook/abc123
Eventos: message.received
Canal: Todos (ou selecione um específico)Clique em "Testar URL" para verificar a conexão. Pronto! O n8n já está integrado.
Quando um cliente envia uma mensagem no WhatsApp, o OmniWhats dispara o webhook para o n8n com todos os dados.
O nó Webhook recebe um JSON com o evento, contato, mensagem e conversa:
# Dados disponíveis no n8n:
{{ $json.event }} # "message.received"
{{ $json.data.message.content }} # "Olá, preciso de ajuda!"
{{ $json.data.contact.name }} # "Maria Silva"
{{ $json.data.contact.phone }} # "5511999887766"
{{ $json.data.conversation.id }} # ID da conversaPara enviar uma resposta, basta o n8n retornar um JSON com o campo "reply" na resposta do webhook. O OmniWhats lê essa resposta e envia automaticamente no WhatsApp — sem precisar de API key ou segundo webhook.
No nó Webhook (trigger), configure responseMode como "Response Node". Isso permite que o workflow controle a resposta HTTP via um nó "Respond to Webhook" no final do fluxo.
No n8n, adicione um nó "Respond to Webhook" ao final do fluxo. Use respondWith: "All Incoming Items" e status 200. O body da resposta deve conter o campo reply:
{
"reply": "Olá! Recebi sua mensagem e já estou verificando."
}Para enviar arquivos junto com a resposta, adicione mediaUrl e mediaType (image, video, audio ou document):
{
"reply": "Segue o comprovante em anexo.",
"mediaUrl": "https://exemplo.com/comprovante.pdf",
"mediaType": "document"
}Workflow completo com 5 nós: recebe mensagem, processa com AI Agent + GPT e responde automaticamente pelo mesmo webhook.
O AI Agent recebe o texto da mensagem, usa o nome do contato e status da conversa como contexto, e retorna a resposta via reply-on-response:
# Workflow n8n: Agente de IA via WhatsApp
#
# 1. [Webhook Trigger] ← OmniWhats envia "message.received"
# ↓ (responseMode: responseNode)
# 2. [AI Agent] → Processa com GPT-4o Mini
# ↑ [OpenAI Chat Model] (conectado como ai_languageModel)
# - Prompt: {{ $json.body.data.message.content }}
# - System: contexto com nome, canal, status
# ↓
# 3. [Set] → Monta { "reply": "{{ $json.output }}" }
# ↓
# 4. [Respond to Webhook] → Retorna JSON (status 200)
#
# O OmniWhats recebe a resposta e envia no WhatsApp!Copie o JSON abaixo e importe no seu n8n: Menu > Import from URL ou Import from File. Após importar, configure sua credencial OpenAI e ative o workflow.
Recebe mensagem e responde com texto fixo. Ideal para testar a integração. Após importar, basta ativar o workflow e colar a URL do webhook no OmniWhats.
Baixar omniwhats-resposta-automatica.jsonRecebe mensagem, processa com AI Agent + GPT-4o Mini e responde. Após importar, crie uma credencial "OpenAI API" com sua API key e conecte ao nó "GPT-4o Mini".
Baixar omniwhats-agente-ia-gpt.json