OmniWhatsAPI
API REST v1

API OmniWhats

Integre o WhatsApp ao seu sistema. Envie mensagens, gerencie contatos e acompanhe conversas de forma programatica atraves da nossa API REST.

Base URL

https://api.omniwhats.com

Formato

JSON (Content-Type: application/json)

Autenticacao

API Key via header X-API-Key

Versao atual: v1 — Todas as rotas estao prefixadas com /api/v1. Versoes futuras serao comunicadas com antecedencia.

Autenticacao

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.

Formato da API Key

As chaves seguem o formato omni_ seguido de 64 caracteres hexadecimais (total de 69 caracteres).

Como autenticar

Envie a API key em um dos seguintes headers:

Headers de Autenticacao
# 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/contacts

Gerando uma API Key

Acesse 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.

Scopes Disponiveis

ScopePermissao
contacts:readListar e visualizar contatos
contacts:writeCriar e atualizar contatos
conversations:readListar e visualizar conversas
conversations:writeAtualizar conversas (status, atribuição)
messages:readVisualizar histórico de mensagens
messages:sendEnviar mensagens de texto e mídia
Uma API key com scopes vazio ([]) tem acesso total (admin).

Rate Limiting

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.

Headers de Resposta

HeaderDescricao
X-RateLimit-LimitNumero maximo de requisições por minuto
X-RateLimit-RemainingRequisições restantes na janela atual
Retry-AfterSegundos até poder tentar novamente (apenas em 429)
Ao receber 429 Too Many Requests, aguarde o numero de segundos indicado no header Retry-After antes de tentar novamente.

Tratamento de Erros

Todas as respostas de erro seguem um formato padronizado:

Formato de Erro
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descricao legivel do erro"
  }
}

Codigos de Erro

CodigoStatusDescricao
MISSING_API_KEY401
INVALID_API_KEY401
API_KEY_DISABLED403
API_KEY_EXPIRED403
INSUFFICIENT_SCOPE403
RATE_LIMIT_EXCEEDED429
MISSING_FIELDS400
INVALID_PHONE400
INVALID_TYPE400
NOT_FOUND404
NO_SESSION422

Contatos

GET

Listar Contatos

https://api.omniwhats.com/contacts

Retorna uma lista paginada de contatos do tenant. Suporta busca por nome, telefone ou email.

Scope:contacts:read

Query Parameters

page
integer
Número da páginaPadrao: 1
limit
integer
Itens por página (max: 100)Padrao: 20
search
string
Busca por nome, telefone ou email

Resposta

200 OK
{
  "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
  }
}
POST

Criar Contato

https://api.omniwhats.com/contacts

Cria 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.

Scope:contacts:write

Request Body

phoneobrigatorio
string
Numero de telefone (mínimo 10 dígitos). Ex: "5511999887766"
name
string
Nome do contato
email
string
Email do contato
notes
string
Observações sobre o contato
customFields
object
Campos personalizados (chave-valor)

Resposta

201 Created / 200 OK
{
  "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
  }
}
GET

Detalhes do Contato

https://api.omniwhats.com/contacts/:id

Retorna os detalhes completos de um contato, incluindo a contagem de conversas associadas.

Scope:contacts:read

Resposta

200 OK
{
  "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"
  }
}
PATCH

Atualizar Contato

https://api.omniwhats.com/contacts/:id

Atualiza os dados de um contato existente. Apenas os campos enviados serão atualizados.

Scope:contacts:write

Request Body

name
string
Nome do contato
email
string | null
Email (envie null para limpar)
notes
string | null
Observações sobre o contato
customFields
object
Campos personalizados (merge com existentes)

Resposta

200 OK
{
  "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"
  }
}

Conversas

GET

Listar Conversas

https://api.omniwhats.com/conversations

Retorna uma lista paginada de conversas. Permite filtrar por status e contato.

Scope:conversations:read

Query Parameters

page
integer
Número da páginaPadrao: 1
limit
integer
Itens por página (max: 100)Padrao: 20
status
string
Filtrar por status: pending, open, closed
contactId
string
Filtrar por ID do contato

Resposta

200 OK
{
  "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
  }
}
GET

Detalhes da Conversa

https://api.omniwhats.com/conversations/:id

Retorna os detalhes completos de uma conversa, incluindo contato, atendente atribuido, departamento e contagem de mensagens.

Scope:conversations:read

Resposta

200 OK
{
  "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"
    }
  }
}
PATCH

Atualizar Conversa

https://api.omniwhats.com/conversations/:id

Atualiza o status, atendente ou departamento de uma conversa. Ao fechar (status: "closed"), o campo closedAt é automaticamente preenchido.

Scope:conversations:write

Request Body

status
string
Novo status: "pending", "open" ou "closed"
assignedUserId
string | null
ID do atendente (null para desatribuir)
departmentId
string | null
ID do departamento (null para remover)

Resposta

200 OK
{
  "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"
    }
  }
}

Mensagens

GET

Histórico de Mensagens

https://api.omniwhats.com/messages/:conversationId

Retorna o histórico de mensagens de uma conversa, ordenadas da mais recente para a mais antiga.

Scope:messages:read

Query Parameters

page
integer
Número da páginaPadrao: 1
limit
integer
Itens por página (max: 100)Padrao: 50

Resposta

200 OK
{
  "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
  }
}
POST

Enviar Mensagem de Texto

https://api.omniwhats.com/messages/send

Envia 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.

Scope:messages:send

Request Body

phoneobrigatorio
string
Número do destinatário (10-15 dígitos). Ex: "5511999887766"
messageobrigatorio
string
Conteúdo da mensagem de texto
sessionId
string
ID da sessão WhatsApp (usa a padrão se omitido)
name
string
Nome para o contato (caso seja criado)

Resposta

200 OK
{
  "success": true,
  "data": {
    "messageId": "m3456789-abcd-ef01-2345-6789abcdef01",
    "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contactId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "status": "sent"
  }
}
POST

Enviar Mensagem com Mídia

https://api.omniwhats.com/messages/send-media

Envia 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.

Scope:messages:send

Request Body

phoneobrigatorio
string
Número do destinatário (10-15 dígitos)
mediaUrlobrigatorio
string
URL pública do arquivo de mídia
typeobrigatorio
string
Tipo da mídia: "image", "video", "audio" ou "document"
caption
string
Legenda da mídia
sessionId
string
ID da sessão WhatsApp (usa a padrão se omitido)
name
string
Nome para o contato (caso seja criado)

Resposta

200 OK
{
  "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

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.

Como configurar: No painel OmniWhats, va em Configurações > Integrações > Outbound Webhooks > Novo. Informe a URL de destino, selecione os eventos e salve. Um secret sera gerado para validacao HMAC.

Eventos Disponiveis

Selecione quais eventos o webhook deve disparar. Voce pode filtrar por canal especifico ou receber de todos.

EventoDescricao
message.receivedCliente envia uma mensagem
message.sentAtendente envia uma mensagem
message.updatedStatus da mensagem muda (entregue, lida)
message.transcribedÁudio é transcrito automaticamente
conversation.createdNova conversa é iniciada
conversation.updatedConversa é modificada
conversation.assignedConversa atribuída a atendente/departamento
conversation.closedConversa é encerrada
contact.createdNovo contato é criado
contact.updatedContato é atualizado
channel.status_changedCanal conecta ou desconecta
deal.movedNegócio muda de etapa no funil
deal.wonNegócio marcado como ganho

Formato do Payload

Todos os webhooks enviam um POST com JSON no seguinte formato:

Exemplo: message.received
{
  "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.

Seguranca (HMAC-SHA256)

Cada entrega inclui uma assinatura HMAC-SHA256 para que você possa validar a autenticidade da requisição.

HeaderDescricao
X-OmniWhats-SignatureAssinatura HMAC-SHA256 para validação (sha256=...)
X-OmniWhats-TimestampTimestamp Unix em segundos da requisição
X-OmniWhats-DeliveryUUID único desta entrega (para deduplicação)
Content-TypeSempre application/json
Verificacao HMAC
// 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');
}
Retry automatico: Se a entrega falhar, o OmniWhats tenta novamente em 30s, 5min e 30min. Apos 10 falhas consecutivas o webhook e marcado como "failing". Apos 50 falhas e desativado automaticamente.

Integracao com n8n

n8n

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.

1. Configuração (Cole a URL e pronto)

Basta colar a URL do webhook do n8n no OmniWhats. Com um único link, o n8n recebe eventos e pode responder automaticamente.

1

Criar Webhook Trigger no n8n

No n8n, adicione um nó "Webhook" como trigger do workflow. Copie a URL de produção gerada (ex: https://seu-n8n.com/webhook/abc123).

2

Colar a URL no OmniWhats

No painel OmniWhats, vá em Configurações > Integrações > Outbound Webhooks > Novo. Cole a URL do n8n e selecione os eventos.

Colar a URL no OmniWhats
Nome:     Meu n8n
URL:      https://seu-n8n.com/webhook/abc123
Eventos:  message.received
Canal:    Todos (ou selecione um específico)
3

Testar e salvar

Clique em "Testar URL" para verificar a conexão. Pronto! O n8n já está integrado.

2. Recebendo mensagens no n8n

Quando um cliente envia uma mensagem no WhatsApp, o OmniWhats dispara o webhook para o n8n com todos os dados.

1

Dados recebidos no n8n

O nó Webhook recebe um JSON com o evento, contato, mensagem e conversa:

Dados recebidos no n8n
# 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 conversa

3. Respondendo pelo mesmo webhook

Para 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.

1

Configurar o Webhook Trigger

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.

2

Adicionar nó "Respond to Webhook"

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:

Adicionar nó "Respond to Webhook"
{
  "reply": "Olá! Recebi sua mensagem e já estou verificando."
}
3

Enviar mídia (opcional)

Para enviar arquivos junto com a resposta, adicione mediaUrl e mediaType (image, video, audio ou document):

Enviar mídia (opcional)
{
  "reply": "Segue o comprovante em anexo.",
  "mediaUrl": "https://exemplo.com/comprovante.pdf",
  "mediaType": "document"
}

4. Exemplo: Agente de IA completo

Workflow completo com 5 nós: recebe mensagem, processa com AI Agent + GPT e responde automaticamente pelo mesmo webhook.

1

Fluxo do workflow

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:

Fluxo do workflow
# 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!

5. Templates para importar no n8n

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.

1

Template 1: Resposta automática simples (sem IA)

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.json
2

Template 2: Agente de IA com GPT

Recebe 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

© 2026 OmniWhats. Todos os direitos reservados.

Precisa de ajuda? Entre em contato pelo painel em app.omniwhats.com

Requisicao

GET /contacts

Listar Contatos
curl -X GET "https://api.omniwhats.com/contacts?page=1&limit=20&search=Maria" \
  -H "X-API-Key: omni_sua_api_key_aqui"

Resposta

200 OK
{
  "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": {
  ...
}