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://gestor.nimochat.com.br        // contas do Atende
https://atende1admin.nimochat.com.br  // contas do Atende1

Atenção: o endereço da API não é o mesmo que você usa para entrar no painel. O painel é a tela em que você faz login; a API atende num endereço próprio. Se você usar o endereço do painel nas chamadas, elas serão redirecionadas para a tela de login e nada funcionará, sem uma mensagem de erro que explique o motivo.

Para descobrir qual é o seu, veja por onde você acessa o painel:

Na dúvida, fale com o suporte antes de começar a integração: usar o endereço errado é o motivo mais comum de a primeira chamada não responder.

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, ou esquecer o cabeçalho, retorna HTTP 403 Forbidden com {"error": "Invalid token."} ou {"error": "Token was not provided."}.

URL Base e formato dos endpoints

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

https://SUA_URL_BASE/v2/api/external/{apiId}/{endpoint}

Onde:

• SUA_URL_BASE — o endereço da API da sua conta (veja a tabela no Passo 2 acima; não é o endereço do painel)
• {apiId} — o API ID gerado no Passo 1
• {endpoint} — o nome do endpoint que você quer chamar (ex: listChannels)

Convenções da API

Formato de datas

Onde houver filtro por período (startDate, endDate), use o formato ano-mês-dia: 2026-08-21. O formato brasileiro 21/08/2026 não funciona e provoca um erro 500, que parece falha do servidor mas é só o formato errado.

?startDate=2026-08-01&endDate=2026-08-21   // certo
?startDate=01/08/2026&endDate=21/08/2026   // erro 500

Onde vem a lista nas listagens

Toda resposta traz success e data, mas o lugar da lista dentro de data muda conforme o endpoint. Confira antes de programar o laço, para não escrever um código que funciona numa rota e quebra na outra:

Paginação

Quase toda listagem traz um bloco pagination ao lado de data. O campo total está sempre presente; os demais variam por endpoint, então não assuma que o bloco é igual em todos:

Nos três endpoints que não trazem o bloco, peça a próxima página (pageNumber, quando disponível) até vir uma lista vazia.

Ritmo de chamadas

Não publicamos um limite fixo de requisições por minuto, e em uso normal a API não bloqueia: em teste, 30 chamadas seguidas foram todas respondidas. Ainda assim, evite rajadas grandes em paralelo, principalmente em importações: prefira sequencial, ou poucas chamadas simultâneas. Se algum dia receber 429, espere alguns segundos e repita a chamada.

Códigos de resposta

Exemplo rápido — sua primeira chamada

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

cURL

curl --request GET \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/listChannels' \
  --header 'Authorization: Bearer SEU_TOKEN'

Resposta esperada

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "WhatsApp Principal",
      "type": "whatsapp",
      "status": "CONNECTED",
      "number": "5511999999999",
      "isActive": true
    }
  ]
}

🤖 Usando a API com uma IA

Se você vai pedir para uma IA (ChatGPT, Claude, Gemini, Copilot ou outra) escrever a sua integração, entregue a ela o endereço desta página e o bloco abaixo. As IAs costumam completar o que não sabem com o que viram em outras plataformas parecidas, e erram justamente nos pontos listados, que conferimos no nosso servidor.

1. Copie o bloco Regras para a IA e cole no começo da conversa.
2. Se a IA consegue abrir links, passe também o endereço clientes.nimochat.com.br/llms-full.txt: é esta documentação inteira em texto, que a IA lê melhor do que a página.
3. Peça uma rota de cada vez e teste cada uma antes de seguir (o Exemplo rápido serve de primeiro teste).
4. Quando der erro, cole na conversa a resposta inteira da API: o código em error diz o que corrigir.

Regras para a IA (copie e cole no começo da conversa)

Você vai escrever uma integração com a API do NimoChat Pro+.
Use SÓ as rotas e os campos da documentação oficial:
https://clientes.nimochat.com.br/documentacaoapiproplus.php
(a mesma documentação em texto: https://clientes.nimochat.com.br/llms-full.txt)
Se precisar de algo que não está lá, pergunte. Não invente rota nem campo.

Regras conferidas no nosso servidor (última conferência em 29/10/2026):
1. URL: https://SUA_URL_BASE/v2/api/external/{apiId}/{rota}. A URL base da API
   não é o endereço do painel (tabela no Passo 2 da documentação).
2. Autenticação: header "Authorization: Bearer SEU_TOKEN". Token errado ou
   ausente responde 403 (não 401). Exceção: no envio por GET (/params/) o
   token vai no parâmetro bearertoken da URL, e o header é ignorado. Nunca
   escreva o token no código: leia de uma variável de ambiente.
3. Rotas GET leem só a URL (caminho e query string). Filtro no corpo é
   ignorado sem erro.
4. Filtros de período (startDate, endDate) em AAAA-MM-DD. DD/MM/AAAA nesses
   filtros dá erro 500. Exceções: birthdayDate do contato é DD/MM/AAAA; datas de
   agendamento aceitam os dois; em tarefas (todo) use AAAA-MM-DD, porque com
   barra a data é lida como mês/dia (02/03 vira 3 de fevereiro).
5. Hora sem fuso vale o horário de Brasília (-03:00). Prefira mandar o fuso.
6. updateContact encontra o contato pelo campo number. Não existe contactId
   nessa rota; sem number a resposta é 500.
7. createTicket exige userId. sendLocation e sendVcard exigem ticketId.
8. Várias tags: campo tagIds (lista). Lista dentro de tagId dá erro.
9. updatetag SUBSTITUI todas as tags do contato. Para acrescentar, use addTag
   ou addTagContact.
10. createContact, updateContact, addTag e removeTag exigem um token criado
    com uma conexão (senão 400 ERR_API_REQUIRES_SESSION).
11. O lugar da lista na resposta muda por rota (data, data.campaigns,
    data.data) e o bloco pagination também. Confira em "Convenções da API".
12. Em erro, leia o campo error (ex: ERR_MISSING_FIELDS). Se vier field ou
    fields, é o campo a corrigir. 201 também é sucesso.
13. bulkIndividual e bulkFastMessage exigem whatsappType (tipo da conexão,
    como em listChannels). Sem ele a resposta é 200 com success:true e nada
    é enviado.
14. Antes de enviar para clientes, teste com o seu próprio número.

📊 Listagens (GET)

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

curl --request GET \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/listChannels' \
  --header 'Authorization: Bearer SEU_TOKEN'

curl --request GET \
  --url 'https://SUA_URL_BASE/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://SUA_URL_BASE/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://SUA_URL_BASE/v2/api/external/SEU_API_ID/updateContact' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "cep": "01310-100",
    "logradouro": "Avenida Paulista",
    "numeroEndereco": "1000",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "estado": "SP"
  }'

# depois, apagar só o complemento (os outros campos ficam como estão)
curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/updateContact' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "complemento": ""
  }'

{
  "success": true,
  "data": {
    "pairs": [
      {
        "matchKind": "cross_collision",
        "confidence": "high",
        "primaryId": 3,
        "duplicateId": 47626,
        "primaryNumber": "5511999999999",
        "duplicateNumber": "5511988888888",
        "primaryName": "Maria Souza",
        "duplicateName": "Maria S.",
        "ticketsToMove": 0,
        "messagesToMove": 5,
        "conflictReason": null
      }
    ]
  }
}

curl --request POST \
  --url 'https://SUA_URL_BASE/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
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/contacts/search' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "addressUfs": ["SP", "RJ"],
    "tagId": 42,
    "limit": 100
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/telegramInvite' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "contactId": 123
  }'

{
  "success": true,
  "data": {
    "link": "https://t.me/seu_bot?start=CODIGO",
    "expiresAt": "2026-11-05T11:23:35.842Z",
    "contactId": 123,
    "whatsappId": 7
  }
}

📨 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://SUA_URL_BASE/v2/api/external/SEU_API_ID' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "body": "Olá! Esta é uma mensagem de teste."
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/sendMessageByTicket' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "ticketId": 1262,
    "body": "Olá! Recebemos seu pedido.",
    "externalKey": "pedido-8841-confirmacao"
  }'

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 1262,
    "messageId": null
  }
}

🎫 Tickets & Tags

👥 Usuários (Atendentes)

📣 Campanhas

Crie e gerencie campanhas de envio programado via API: defina mensagens (com rotação de até 3 variações), data de início, conexão de envio e a lista de contatos. Ideal para integrar disparos a CRMs e automações.

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/campaign/create' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Promoção Junho",
    "start": "2026-06-15T10:00:00.000Z",
    "message1": "Olá {nome}! Temos uma novidade para você.",
    "message2": "Oi {nome}, tudo bem? Confira nossa novidade.",
    "sessionId": 12,
    "delay": "5"
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/campaign/contacts/add/123' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    { "name": "João", "number": "5511999990001" },
    { "name": "Maria", "number": "5511999990002" }
  ]'

📤 Envio em Lote

Endpoints para disparo direto a múltiplos números, sem criar uma campanha. Os campos min e max definem o intervalo aleatório (em segundos) entre cada envio — essencial para envios saudáveis.

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/bulkSendMessage' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "whatsappId": 12,
    "arrayNumbers": ["5511999990001", "5511999990002"],
    "message": "Olá, tudo bem?",
    "min": 3,
    "max": 8
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/bulkSendMessageWithVariable' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "whatsappId": 12,
    "message": "Olá {nome}, seu código é {codigo}",
    "dataInput": "5511999990001,João,ABC123\n5511999990002,Maria,DEF456",
    "min": 3,
    "max": 8
  }'

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/bulkIndividual' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "whatsappId": 246,
    "whatsappType": "uazapi",
    "number": "5511999999999",
    "message": "Olá! Sua encomenda saiu para entrega."
  }'

👥 Grupos WhatsApp

Crie e administre grupos do WhatsApp via API: participantes, administradores, título, descrição, foto e link de convite. Em todas as rotas, whatsappId é o ID da conexão (veja Listar Canais) e groupId é o identificador do grupo (formato 123456789@g.us).

{
  "whatsappId": 12,
  "titles": ["Meu Grupo 1"],
  "number": "5511999990001"
}

{
  "whatsappId": 12,
  "groupIds": ["123456789@g.us"],
  "participants": ["5511999990001"]
}

{
  "body": "A mensagem desejada",
  "number": "123456789015189153",
  "externalKey": "SUA_CHAVE_EXTERNA",
  "isClosed": false
}

📨 Mensagens — Recursos Adicionais

Complementos aos endpoints de envio de texto e arquivo: áudio como mensagem de voz, arquivo em base64, localização, cartão de contato (vCard), busca e consulta de mensagens.

{
  "audio": "https://exemplo.com/audio.ogg",
  "number": "5511999999999",
  "externalKey": "SUA_CHAVE_EXTERNA",
  "isClosed": false
}

{
  "body": "A mensagem desejada",
  "number": "5511999999999",
  "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/png",
  "fileName": "exemplo_imagem",
  "isClosed": false
}

{
  "number": "5511999990001",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "São Paulo",
  "address": "Av. Paulista, 1000",
  "ticketId": 1262,
  "externalKey": "SUA_CHAVE_EXTERNA"
}

{
  "number": "5511999990001",
  "contact": [
    {
      "fullName": "João Silva",
      "wuid": "5511999990002@s.whatsapp.net",
      "phoneNumber": "5511999990002"
    }
  ],
  "ticketId": 1262,
  "externalKey": "SUA_CHAVE_EXTERNA"
}

🧩 Mensagens Interativas

Botões, listas, enquetes e templates ricos. Os recursos disponíveis dependem do tipo da conexão do ticket. Todos os endpoints recebem ticketId e respondem dentro da conversa existente.

{
  "ticketId": 1262,
  "body": { "text": "Escolha uma opção:" },
  "footer": { "text": "Rodapé opcional" },
  "buttons": [
    { "display_text": "Opção 1", "id": "op1" },
    { "display_text": "Opção 2", "id": "op2" }
  ]
}

{
  "ticketId": 1262,
  "text": "Qual sua preferência?",
  "choices": ["Opção A", "Opção B", "Opção C"],
  "selectableCount": 1
}

📋 Templates WABA (API Oficial)

Na API Oficial do WhatsApp, a primeira mensagem para um contato, ou qualquer mensagem depois de 24 horas sem resposta dele, só pode ser um modelo (template) aprovado pela Meta.

{
  "number": "5511999999999",
  "isClosed": false,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "type": "template",
    "template": {
      "name": "boas_vindas",
      "language": { "code": "pt_BR" }
    }
  }
}

{
  "number": "5511999999999",
  "isClosed": true,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "type": "template",
    "template": {
      "name": "fatura_disponivel",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Maria" },
            { "type": "text", "text": "R$ 150,00" }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [ { "type": "text", "text": "abc123" } ]
        }
      ]
    }
  }
}

{
  "number": "5511999999999",
  "isClosed": true,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "type": "template",
    "template": {
      "name": "reuniao_confirmada",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "video", "video": { "link": "https://seusite.com.br/video.mp4" } }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Maria" },
            { "type": "text", "text": "29/10" },
            { "type": "text", "text": "19:30" }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [ { "type": "text", "text": "abc123" } ]
        }
      ]
    }
  }
}

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 4521
  }
}

🎫 Tickets — Gestão Completa

Criação de tickets, consulta por número ou ID, atualização de fila/status/integrações, tags por contato, pausa e compartilhamento.

{
  "body": "A mensagem desejada",
  "number": "5511999999999",
  "externalKey": "SUA_CHAVE_EXTERNA",
  "userId": 3,
  "status": "pending"
}

{
  "contactId": 123,
  "tagId": 1
}

🏗️ CRM — Pipelines, Oportunidades e Cadastros

Estruture o funil de vendas via API: pipelines e estágios, oportunidades vinculadas a contatos, e os cadastros de apoio (kanban, tags, motivos de encerramento e filas).

{
  "number": "5511999990001",
  "contactName": "Nome do Contato",
  "email": "contato@email.com",
  "name": "Proposta Empresa X",
  "value": 10000.00,
  "status": "open",
  "pipelineId": 16,
  "stageId": 7,
  "responsibleId": 1,
  "closingForecast": "2026-12-31",
  "description": "Descrição da oportunidade"
}

📅 Agendamentos e Lembretes

Agende compromissos vinculados a contatos e configure lembretes automáticos por WhatsApp antes de cada evento.

{
  "title": "Reunião de Vendas",
  "description": "Reunião sobre proposta comercial",
  "contactId": 123,
  "contactName": "João Silva",
  "contactPhone": "5511999999999",
  "whatsappId": 12,
  "userId": 3,
  "startAt": "15/06/2026 14:00",
  "endAt": "2026-06-15T15:00:00-03:00",
  "status": "pending",
  "notes": "Levar proposta impressa"
}

{
  "name": "Lembrete 24h antes",
  "description": "Envia mensagem ao contato 24h antes do agendamento",
  "hoursBeforeEvent": 24,
  "messageType": "message",
  "messageContent": "Olá {nome}, lembrete da sua reunião amanhã!",
  "whatsappId": 12,
  "active": true
}

📊 Dashboard e Relatórios

Indicadores de atendimento para alimentar BI e relatórios externos. Todos os endpoints são GET e aceitam startDate e endDate (formato AAAA-MM-DD).

🔌 Canais e Sessões

Gerencie as conexões WhatsApp do tenant via API: criar, iniciar, obter QR Code e consultar canais. Complementa Listar Canais e Listar Sessões.

🗂️ Utilitários

Galeria de arquivos, tarefas (to-do), logs de chamadas, consulta de contato por número e listagens auxiliares.

{
  "number": "5511999999999"
}

{
  "success": true,
  "data": {
    "available": true,
    "folders": [{ "id": 1, "name": "Produtos", "count": 12 }],
    "unfiledCount": 30,
    "totalCount": 42
  }
}

curl --request POST \
  --url 'https://SUA_URL_BASE/v2/api/external/SEU_API_ID/formSubmit' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "formId": 12,
    "answers": {
      "f_nome": "Maria Souza",
      "f_telefone": "+5511999998888",
      "f_email": "maria@exemplo.com"
    },
    "ref": "https://www.seusite.com.br/contato"
  }'

{ "ok": true, "submissionId": 87, "status": "processed", "ticketId": 1262, "contactId": 123, "errorCode": null }

🪝 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://SUA_URL_BASE/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://SUA_URL_BASE/v2/api/external/SEU_API_ID' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "body": "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://SUA_URL_BASE/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://SUA_URL_BASE/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://SUA_URL_BASE/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://SUA_URL_BASE/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://SUA_URL_BASE/v2/api/external/SEU_API_ID' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --data '{ "number": "5511999999999", "body": "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://SUA_URL_BASE/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 é gerada a partir desta página: tem todas as rotas daqui, cada uma com corpo de exemplo, os campos, os avisos e o link para o cartão correspondente. O Postman monta o código 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.