Integração com a API do Nexchat

Qual API usar

A escolha errada aqui é a causa mais comum de integração insegura, porque a API mais fácil de usar é também a mais poderosa. Comece pela coluna da direita.

Base e versões

Autenticação

As três APIs usam o mesmo header, com significados diferentes. O que define o poder do chamador é o tipo do dono do token, não a rota.

api_access_token: <seu-token>

Por que o token de agent bot é o certo

O servidor mantém uma lista fechada do que um bot pode fazer. Qualquer rota fora dela responde 401 com Access to this endpoint is not authorized for bots, independentemente do que a conta permita. Esta é a lista inteira, como está no servidor:

Se a sua integração precisa de algo fora dessa lista — ler contatos em massa, puxar relatório, criar inbox — peça isso explicitamente. Nós avaliamos caso a caso e, quando faz sentido, a conta recebe um usuário de integração dedicado com permissão mínima, nunca o token de um atendente real.

Como o token chega até você

1. Você nos envia o nome da integração, a URL do seu webhook e os IPs de saída do seu backend.
2. Nós criamos o agent bot na conta do cliente e devolvemos o token por canal cifrado, uma vez.
3. Você guarda o token em cofre de segredos — nunca em repositório, variável de build, log ou código de frontend.
4. Rotação: você pede, nós regeramos. A regeração invalida o token anterior na hora, porque cada dono tem um único token. Planeje a troca como uma janela, não como sobreposição.

Application API

A API de atendimento, sob /api/v1/accounts/{account_id}. É onde vive a operação: conversas, mensagens, contatos, etiquetas, times, relatórios. O account_id é o número da conta do cliente e é fixo por integração — nós informamos.

Criar uma conversa e responder

# 1. achar ou criar o contato
curl -X POST https://chat.nexxchat.com.br/api/v1/accounts/1/contacts \
  -H "api_access_token: $NEXCHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 7,
    "name": "Maria Andrade",
    "phone_number": "+554933402026",
    "custom_attributes": { "contrato": "ISP-99120" }
  }'

# 2. abrir a conversa nessa inbox
curl -X POST https://chat.nexxchat.com.br/api/v1/accounts/1/conversations \
  -H "api_access_token: $NEXCHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "source_id": "ISP-99120", "inbox_id": 7, "contact_id": 4821 }'

# 3. mandar a mensagem
curl -X POST https://chat.nexxchat.com.br/api/v1/accounts/1/conversations/312/messages \
  -H "api_access_token: $NEXCHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Sua visita técnica está confirmada para amanhã, 14h.", "message_type": "outgoing" }'

Paginação e filtro

As listagens paginam por ?page=N, 25 itens por página, e devolvem a contagem em meta. Para busca estruturada existe POST .../contacts/filter e POST .../conversations/filter, que aceitam um array de condições — preferíveis a varrer páginas.

curl -X POST https://chat.nexxchat.com.br/api/v1/accounts/1/conversations/filter \
  -H "api_access_token: $NEXCHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "payload": [
        { "attribute_key": "status", "filter_operator": "equal_to",
          "values": ["open"], "query_operator": "AND" },
        { "attribute_key": "inbox_id", "filter_operator": "equal_to", "values": [7] }
      ] }'

Client API

Sob /public/api/v1/inboxes/{inbox_identifier}. É a única API que roda no navegador do seu usuário final: sem token, liberada para qualquer origem por CORS. Ela existe para você embutir o chat no seu produto.

O preço de não ter token é que a identidade do chamador vem do caminho da URL. Dois valores:

Como assinar o identificador

Nós entregamos um hmac_token por inbox. Ele é segredo de servidor: o hash é calculado no seu backend e entregue ao frontend já pronto. O frontend nunca vê o token.

// Node 18+, no SEU backend
import { createHmac } from "node:crypto";

export function identifierHash(identifier) {
  return createHmac("sha256", process.env.NEXCHAT_HMAC_TOKEN)
    .update(String(identifier))
    .digest("hex");
}

O servidor recalcula HMAC-SHA256(hmac_token, identifier) e compara em tempo constante. O hash cobre o identifier e nada mais — então ele prova quem é o contato, não o que a requisição pede.

Fluxo completo

# 1. registrar/identificar o contato — backend chama, com o hash
curl -X POST https://chat.nexxchat.com.br/public/api/v1/inboxes/$INBOX_ID/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "ISP-99120",
    "identifier_hash": "4f0c…",
    "name": "Maria Andrade",
    "email": "maria@exemplo.com.br"
  }'
# → devolve source_id, que é o contact_identifier das chamadas seguintes

# 2. abrir conversa
curl -X POST ".../public/api/v1/inboxes/$INBOX_ID/contacts/$CONTACT_ID/conversations" \
  -H "Content-Type: application/json" -d '{}'

# 3. mandar mensagem do usuário final
curl -X POST ".../public/api/v1/inboxes/$INBOX_ID/contacts/$CONTACT_ID/conversations/$CONV/messages" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Minha internet caiu desde ontem à noite." }'

# 4. ler o histórico (paginado por ?before=)
curl ".../public/api/v1/inboxes/$INBOX_ID/contacts/$CONTACT_ID/conversations/$CONV/messages"

Escopo de leitura

Vale entender porque muda o que o seu usuário vê:

• Sem HMAC verificado — as leituras ficam restritas às conversas daquele vínculo contato-inbox.
• Com HMAC verificado — as leituras passam a abranger todas as conversas do contato, inclusive as que vieram por WhatsApp, e-mail ou telefone.

O segundo é o comportamento desejado num portal do cliente: a pessoa vê o histórico dela inteiro, não só o pedaço que passou pelo seu widget. Mas ele também eleva o identifier a credencial de verdade. Trate o hmac_token com o mesmo cuidado de uma chave de assinatura de sessão.

Platform API

Sob /platform/api/v1. Cria contas, usuários e agent bots na instalação. São 17 operações e todas valem para a instalação inteira, não para uma conta.

Canal API (inbox)

Se o seu produto já tem um canal de mensagens próprio — um app, um portal, um PABX — o canal API o pluga no Nexchat. Mensagem que entra vai pela Application API; mensagem que o atendente responde chega no seu webhook_url configurado na inbox.

A inbox tem um parâmetro agent_reply_time_window que limita por quanto tempo depois da última mensagem do contato o atendente pode responder — espelha a janela de 24h do WhatsApp. Se o seu canal não tem essa restrição, deixe-o em branco.

Webhooks

O Nexchat entrega eventos por POST JSON. Há dois lugares para registrar: POST /api/v1/accounts/{id}/webhooks (eventos da conta, com assinatura de inscrições) e o webhook_url da inbox do canal API.

Eventos disponíveis

Estes treze, e nenhum outro — a inscrição é validada e um nome fora da lista derruba a criação do webhook:

Verificar a assinatura

Quando o webhook tem segredo, cada entrega traz estes headers:

// Express — verificação com corpo BRUTO e defesa de replay
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
app.post("/webhooks/nexchat",
  express.raw({ type: "application/json" }),   // o corpo cru, não o parseado
  (req, res) => {
    const ts  = req.get("X-Chatwoot-Timestamp") ?? "";
    const sig = req.get("X-Chatwoot-Signature") ?? "";

    // 1. rejeita entrega velha: o timestamp é assinado, mas quem decide a
    //    janela é você. Sem isto, uma entrega capturada vale para sempre.
    const idade = Math.abs(Date.now() / 1000 - Number(ts));
    if (!ts || Number.isNaN(idade) || idade > 300) return res.sendStatus(401);

    // 2. recalcula sobre "{ts}.{corpo bruto}"
    const esperado = "sha256=" + createHmac("sha256", process.env.NEXCHAT_WEBHOOK_SECRET)
      .update(`${ts}.${req.body.toString("utf8")}`)
      .digest("hex");

    // 3. compara em tempo constante, com os tamanhos conferidos antes
    const a = Buffer.from(sig), b = Buffer.from(esperado);
    if (a.length !== b.length || !timingSafeEqual(a, b)) return res.sendStatus(401);

    // 4. responda rápido. O Nexchat espera 5s por padrão e desiste.
    res.sendStatus(200);
    enfileirar(JSON.parse(req.body.toString("utf8")), req.get("X-Chatwoot-Delivery"));
  });

Limites e erros

O Nexchat limita por IP e por conta. Os valores abaixo são os de produção; integração que trombe neles com frequência é sinal de desenho errado, não de limite baixo.

Estouro responde 429. Faça backoff exponencial com jitter; não reenvie em laço fixo. Os contadores por chamador usam o seu token como chave, então duas integrações com o mesmo token dividem o mesmo balde — mais um motivo para cada parceiro ter o seu.

Referência completa

As 149 operações, extraídas da especificação OpenAPI 3.1 que acompanha a versão em produção. A coluna de credencial diz o tipo mínimo de token aceito.

Requisitos de segurança

Os três primeiros itens são condição para liberar a integração em produção. Os demais são o que esperamos de um parceiro que trata dado de assinante de ISP.

• 01
  Validação de identidade ligada na inbox

  Toda inbox de canal API que serve usuário final roda com identity validation. O hmac_token fica só no seu backend, e o identifier é opaco — nunca CPF, e-mail, telefone ou id sequencial.

• 02
  Assinatura de webhook verificada, com janela de replay

  Corpo bruto, comparação em tempo constante, e rejeição de X-Chatwoot-Timestamp com mais de 5 minutos. Endpoint que aceita entrega não assinada é endpoint público para qualquer um.

• 03
  Token de agent bot, guardado em cofre

  Sem token de usuário humano, sem token de platform app, nada no frontend, nada em repositório. Se um token vazar, nos avise antes de rotacionar: a rotação invalida o anterior na hora e derruba a integração.

• 04
  Dado de assinante não sai do necessário

  A API devolve nome, telefone, e-mail, histórico de conversa e atributos personalizados. Isso é dado pessoal sob LGPD. Não espelhe em base sua o que você não usa, e não mande nada disso para terceiro ou provedor de IA sem previsão em contrato.

• 05
  Log sem segredo e sem conteúdo de conversa

  Nunca logue o header api_access_token, o hmac_token, o segredo de webhook, nem o corpo das mensagens. Em erro, logue o X-Chatwoot-Delivery e o código HTTP.

• 06
  Backoff e idempotência

  Retentativa com jitter, source_id estável para não duplicar contato nem conversa, e deduplicação de webhook por id de entrega.

• 07
  Um conjunto de credenciais por ambiente

  Homologação e produção com tokens, inboxes e segredos distintos. Teste de carga combinado antes, nunca contra a conta de um cliente real.