API NimoChat Pro+

O que é a API NimoChat Pro+

A API NimoChat Pro+ é uma interface REST que permite integrar a plataforma de atendimento com qualquer sistema externo: CRM, ERP, sistema de RH, plataformas de automação como n8n, Make, Zapier, ou aplicações sob medida.

Com a API você pode automatizar tarefas repetitivas, sincronizar dados entre sistemas, criar fluxos personalizados e levar a inteligência do NimoChat Pro+ para fora dele. A API é organizada em torno de princípios REST: usa URLs previsíveis, recebe e devolve JSON, e usa códigos HTTP padrão.

Casos de uso comuns

• Disparo em massa segmentado — Buscar contatos com determinada tag e disparar campanha via n8n.
• Sincronização com CRM — Criar contatos automaticamente a partir de leads do seu CRM.
• Automação de RH — Cadastrar usuários (atendentes) automaticamente quando um colaborador é admitido no ERP.
• Integração com BI — Extrair dashboards de tickets, tempos de atendimento e evolução para Power BI / Looker.
• Humanização de bots — Mostrar status "digitando..." antes de uma resposta automática.

Começando

Para usar a API você precisa de 3 informações: a URL base do seu painel, uma chave de API (token) e o ID da sua conexão WhatsApp. Tudo pode ser obtido em poucos cliques no painel administrativo.

Passo 1 — Gerar sua chave de API

1. Faça login no seu painel NimoChat Pro+ como Administrador.
2. No menu lateral, acesse API.
3. Clique em Nova API, dê um nome e selecione a conexão WhatsApp.
4. Copie e guarde o Token e o API ID. O token só é exibido uma vez.

Passo 2 — Identificar sua URL base

Cada cliente NimoChat Pro+ tem sua própria URL de back-end. Ela aparece no painel administrativo e tem o formato:

https://seudominio.nimochat.com.br

Todas as chamadas à API são feitas a partir dessa URL. Se você não souber a sua, pergunte ao administrador da conta ou consulte o painel em Configurações > Domínios.

Autenticação

A API NimoChat Pro+ usa o padrão Bearer Token. Toda requisição precisa incluir o token no cabeçalho HTTP Authorization:

Authorization: Bearer SEU_TOKEN_AQUI

O sistema valida o token em todas as chamadas e isola os dados por empresa: você só consegue acessar e modificar dados da sua própria conta. Tentar usar um token inválido retorna HTTP 401 Unauthorized.

URL Base e formato dos endpoints

Todos os endpoints da API seguem o mesmo padrão de URL:

https://seudominio.nimochat.com.br/v2/api/external/{apiId}/{endpoint}

Onde:

• seudominio.nimochat.com.br — sua URL base (Passo 2 acima)
• {apiId} — o API ID gerado no Passo 1
• {endpoint} — o nome do endpoint que você quer chamar (ex: listChannels)

Códigos de resposta

Exemplo rápido — sua primeira chamada

Vamos listar todos os canais (conexões WhatsApp) da sua conta. Substitua SEU_TOKEN, SEU_DOMINIO e SEU_API_ID pelos valores reais:

cURL

curl --request GET \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/listChannels' \
  --header 'Authorization: Bearer SEU_TOKEN'

Resposta esperada

{
  "channels": [
    {
      "id": 1,
      "name": "WhatsApp Principal",
      "status": "CONNECTED",
      "number": "5511999999999"
    }
  ]
}

📊 Listagens (GET)

Endpoints de consulta. Use estas rotas para buscar informações da plataforma. Todas retornam JSON.

curl --request GET \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/listChannels' \
  --header 'Authorization: Bearer SEU_TOKEN'

curl --request GET \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/listTickets?status=open&queuesIds=3&pageNumber=1' \
  --header 'Authorization: Bearer SEU_TOKEN'

👤 Contatos (POST)

Endpoints para criar, atualizar e gerenciar contatos. Todos os métodos POST recebem o corpo em JSON com header Content-Type: application/json.

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/createContact' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "João Silva",
    "number": "5511999999999",
    "email": "joao@empresa.com.br"
  }'

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/contacts/search' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "tagId": 42,
    "page": 1,
    "limit": 100
  }'

📨 Mensagens (POST)

Endpoints para envio de mensagens via WhatsApp através das suas conexões. Suporta texto, arquivos, áudio, localização, e os tipos interativos da API oficial WhatsApp Business (WABA).

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/sendMessageAPIText' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "message": "Olá! Esta é uma mensagem de teste."
  }'

🎫 Tickets & Tags

👥 Usuários (Atendentes)

🪝 Webhooks

Webhooks são notificações que o NimoChat Pro+ envia automaticamente para uma URL do seu sistema sempre que algo acontece na plataforma — uma nova mensagem chega, um ticket é criado, um atendimento é finalizado.

Em vez de seu sistema ficar perguntando à API "tem mensagem nova?" a cada minuto (polling), o NimoChat avisa em tempo real quando algo acontece. Isso é mais eficiente, mais rápido e consome menos recursos.

Configurando o Webhook

A configuração é feita no painel administrativo do NimoChat Pro+ em poucos cliques:

1. Faça login como Administrador.
2. Acesse Integrações > Webhook no menu.
3. Ative a opção "Ativar webhook".
4. Informe a URL do seu sistema que vai receber as notificações (precisa ser HTTPS pública).
5. Opcionalmente, ative "Receber eventos de mensagem" para receber notificações também das mensagens individuais (não apenas dos tickets).
6. Salve as alterações.

Estrutura do payload

Toda notificação é enviada como POST para sua URL com Content-Type: application/json. O corpo da requisição segue esta estrutura:

{
  "method": "...",           // tipo do evento (opcional)
  "tenantId": 123,            // ID da sua conta
  "ticketId": 98765,          // ID do ticket relacionado

  "msg": {                       // dados da mensagem
    "body": "texto da mensagem",
    "fromMe": false,           // true = atendente enviou, false = contato enviou
    "from": "5511999999999@s.whatsapp.net"
  },

  "ticket": {                    // dados do ticket
    "id": 98765,
    "tenantId": 123,
    "userId": null,           // null = não atribuído
    "queueId": 5,             // ID da fila
    "createdAt": "2026-04-06T13:00:00.000Z",
    "contact": {
      "id": 456,
      "name": "João Silva",
      "number": "5511999999999",
      "wallets": [{ "id": 7 }]
    }
  }
}

Campos principais

Tipos de eventos

O campo method identifica o tipo do evento. Os principais valores são:

Exemplos de payloads reais

Mensagem de texto recebida

{
  "msg": {
    "fromMe": false,
    "body": "Olá, gostaria de saber sobre o produto X",
    "from": "5511999999999@s.whatsapp.net"
  },
  "ticket": {
    "id": 12345,
    "tenantId": 2,
    "userId": null,
    "queueId": 3,
    "createdAt": "2026-04-06T13:00:00.000Z",
    "contact": {
      "id": 456,
      "name": "João Silva",
      "number": "5511999999999",
      "wallets": []
    }
  }
}

Mídia recebida (áudio, imagem, documento)

{
  "msg": {
    "fromMe": false,
    "content": [
      { "type": "audio", "url": "https://media.../audio.ogg" }
    ]
  },
  "ticket": {
    "id": 12346,
    "tenantId": 2,
    "contact": { "id": 456, "number": "5511999999999" }
  }
}

Mensagem enviada pelo atendente (filtrar)

{
  "method": "message_send_uazapi",
  "msg": { "fromMe": true, "body": "Olá! Em que posso ajudar?" },
  "ticket": { "id": 12345, "tenantId": 2 }
}

Confirmação de leitura (filtrar)

{
  "method": "ack",
  "ticketId": 12345
}

Exemplo de receiver (Node.js)

Receiver simples em Node.js + Express que processa apenas mensagens recebidas:

const express = require('express');
const app = express();
app.use(express.json());

// Métodos a ignorar (saída + ruído)
const IGNORE = ['message_send', 'message_send_uazapi',
                'message_send_waba', 'message_sent_waba',
                'ack', 'presence'];

app.post('/webhook/nimochat', (req, res) => {
  const payload = req.body;

  // 1. Filtrar eventos que não interessam
  if (IGNORE.includes(payload.method)) return res.sendStatus(200);

  // 2. Validar tenant (segurança)
  if (payload.ticket?.tenantId !== SEU_TENANT_ID) return res.sendStatus(403);

  // 3. Processar apenas mensagens recebidas
  if (payload.msg?.fromMe === false) {
    const contact = payload.ticket?.contact;
    const body = typeof payload.msg.body === 'string' ? payload.msg.body : '';

    console.log(`Nova mensagem de ${contact?.name}: ${body}`);

    // Aqui você integra com seu CRM, dispara alerta, etc.
  }

  res.sendStatus(200);
});

app.listen(3000);

Segurança e boas práticas

• HTTPS obrigatório — sempre use URLs com SSL válido. Webhooks com HTTP simples podem não funcionar.
• Valide o tenantId — confira se o ID da conta no payload bate com o seu. Se não bater, rejeite com HTTP 403.
• Responda rápido (HTTP 200) — o webhook tem timeout. Se sua lógica é demorada, responda 200 imediatamente e processe em background (fila).
• Idempotência — use ticket.id + msg.from + timestamp para evitar processar a mesma mensagem 2x se houver retentativa.
• Type checking — sempre verifique o tipo dos campos antes de usar (especialmente msg.body que pode ser string ou ausente).
• Logue tudo no início — durante a integração, logue payloads completos. Eles são sua única fonte de verdade sobre o que chega.
• IP whitelist (opcional) — se possível, restrinja o endpoint apenas a IPs conhecidos do servidor NimoChat.

💡 Casos de uso reais

1. Disparo em massa segmentado por tag

Você quer enviar uma promoção para todos os contatos com a tag "Lead Quente". Em vez de exportar a lista manualmente, busque os contatos via API e dispare via n8n / Make.

Passo 1 — Buscar contatos com a tag

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/contacts/search' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "tagId": 42, "limit": 500 }'

Passo 2 — Para cada contato, enviar a mensagem

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/sendMessageAPIText' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "message": "Oferta especial só para você! 30% OFF até hoje."
  }'

2. Distribuição automática de leads para vendedores

Quando um novo lead chega, atribua automaticamente para um vendedor disponível usando a função de carteirização (wallet).

Atribuir contato à carteira do vendedor

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/updateContactWallet' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactId": 4567,
    "walletId": 12
  }'

Combine com o webhook de novo ticket: quando o NimoChat avisar que um novo ticket foi criado, sua aplicação consulta qual vendedor está disponível (lógica round-robin, menor carga, especialidade) e atribui via API.

3. Sincronizar contatos do CRM com o NimoChat

Toda vez que um novo contato é cadastrado no seu CRM, replique-o automaticamente para o NimoChat:

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/createContact' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Maria Oliveira",
    "number": "5511988887777",
    "email": "maria@empresa.com",
    "extraInfo": [
      { "name": "empresa", "value": "ACME Ltda" },
      { "name": "cargo", "value": "Diretora Comercial" }
    ]
  }'

4. Cadastrar atendentes via integração com RH

Quando um novo colaborador é admitido no seu sistema de RH, crie automaticamente o usuário (atendente) no NimoChat:

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/createUser' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Carlos Santos",
    "email": "carlos.santos@empresa.com",
    "password": "SenhaTemp123!",
    "profile": "user"
  }'

5. Humanizar bots — mostrar "digitando..." antes da resposta

Antes do seu bot enviar uma resposta automática, envie um sinal de presence "typing" para humanizar a interação:

# 1. Envia "digitando..." (typing)
curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/sendPresence' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --data '{ "ticketId": 12345, "state": "typing" }'

# 2. Aguarda 2-4 segundos
sleep 3

# 3. Envia a mensagem real
curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/sendMessageAPIText' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --data '{ "number": "5511999999999", "message": "Resposta do bot" }'

6. Classificar tickets durante o atendimento

Use addTag para classificar o ticket sem perder as tags anteriores. Por exemplo, ao detectar uma palavra-chave no texto da mensagem:

curl --request POST \
  --url 'https://SEU_DOMINIO.nimochat.com.br/v2/api/external/SEU_API_ID/addTag' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --data '{ "ticketId": 12345, "tagId": [42, 87] }'

📚 Referência completa de endpoints

A coleção do Postman tem mais de 165 endpoints documentados com exemplos prontos de request e response em várias linguagens (cURL, Node.js, Python, PHP, Go, Java).

Abra a coleção, clique em qualquer endpoint, e copie o snippet na linguagem desejada usando o painel "Code" (lateral direita).

Endpoints por categoria

Resumo de tudo que está disponível na coleção:

📅 Agendamentos e Lembretes

Crie e gerencie agendamentos e lembretes automáticos.

📣 Campanhas

Crie, gerencie e dispare campanhas de marketing em massa.

🔌 Canais e Sessões

Gerencie conexões WhatsApp, escaneie QR Codes, inicie e finalize sessões.

👤 Contatos (avançado)

🏗️ CRM - Pipeline

Gerencie pipelines (funis) e estágios do CRM.

📊 Dashboard

Métricas e gráficos para BI / dashboards externos.

📤 Envio em Lote (Bulk)

Disparos em massa de mensagens com controle de progresso.

📂 Galeria de mídias

👥 Grupos WhatsApp

Crie e gerencie grupos do WhatsApp.

🏷️ Kanban / Tags / Motivos / Filas

CRUD completo de objetos auxiliares.

🔍 Listagens utilitárias

📞 Logs de Chamadas

📨 Mensagens (extras)

👥 Mensagens em Grupo

💼 Oportunidades (CRM)

📋 Templates WABA (API Oficial)

🎫 Tickets (extras)

✅ To-Do List

❓ FAQ — Perguntas frequentes

Posso testar sem código?

Sim. Acesse a coleção do Postman, clique em qualquer endpoint, preencha as variáveis (token, URL base, API ID) e clique em "Send". É a forma mais rápida de testar.

Como gerar exemplos de código em outras linguagens?

No Postman, abra o endpoint, clique no ícone { } (Code Snippets) na lateral direita e escolha a linguagem: cURL, Node.js, Python, PHP, Java, Go, C#, Ruby, etc.

Existe limite de requisições (rate limit)?

Sim. Use a API com bom senso — picos muito altos podem ser bloqueados. Para disparos em massa, use os endpoints específicos de Bulk com delay entre mensagens (recomendado: 5-10 segundos).

Como funciona a autenticação Bearer?

Você gera um token no painel admin (menu API) e envia ele em todas as requisições no header Authorization: Bearer SEU_TOKEN. O token é específico da sua conta e isola seus dados.

O que é o apiId no URL?

É o identificador único da sua chave de API. É gerado junto com o token quando você cria uma nova API no painel. Cada chave pode estar associada a uma conexão WhatsApp específica.

Por que minhas mensagens não chegam ao destino?

Possíveis causas: (1) número formatado errado — sempre use DDI+DDD+número (ex: 5511999999999), (2) conexão WhatsApp desconectada — verifique no painel, (3) número do destinatário não tem WhatsApp, (4) o WhatsApp pode ter bloqueado por excesso de mensagens.

O webhook não está chegando, o que fazer?

Confira: (1) URL configurada está correta e é HTTPS pública, (2) seu servidor responde com HTTP 200 em até 15 segundos, (3) a opção "Receber eventos de mensagem" está ativada se você quer receber mensagens individuais, (4) seu firewall não está bloqueando os IPs do NimoChat.

Onde reportar bugs ou sugerir novos endpoints?

Entre em contato pelo nosso canal de suporte — vamos avaliar e priorizar. Atualizações da API são notificadas via release notes no Postman.