Ajuda › Webhooks e API

Webhooks e API

Há dois sentidos de integração, e cada um tem a sua aba em Integrações:

Webhooks (o NexaChat avisa o seu sistema)#

1. Em Integrações › Enviar avisos (Webhooks), clique em Novo webhook.
2. Informe o endereço do seu sistema (precisa ser público; endereços internos e privados são bloqueados por segurança) e escolha os eventos.
3. Clique em Enviar teste. O resultado aparece no histórico.

Eventos disponíveis:

O corpo de exemplo de cada evento está na documentação da API, na seção Webhooks. Nos avisos de teste (conversas do Simulador, quando você liga a opção de disparar webhooks), o corpo traz "test": true.

Como é o aviso: um POST com JSON (event, data e timestamp) e estes cabeçalhos:

X-NexaChat-Event: conversation.opened
X-NexaChat-Signature: sha256=<hmac_sha256(segredo, corpo)>

Confira a assinatura recalculando o HMAC-SHA256 do corpo com o segredo do webhook. Exemplo em Node:

const crypto = require('node:crypto');
const esperado = 'sha256=' + crypto.createHmac('sha256', SEGREDO).update(corpoBruto).digest('hex');
if (esperado !== req.headers['x-nexachat-signature']) return res.status(401).end();

Se o seu sistema não responder com sucesso (código diferente de 2xx), o NexaChat tenta de novo depois de 1 minuto, 5 minutos, 30 minutos e 2 horas (5 tentativas no total). O histórico mostra o código HTTP, o tempo de resposta, a resposta do seu sistema e a hora da próxima tentativa. Você pode Reenviar qualquer entrega.

API v1 (o seu sistema fala com o NexaChat)#

A documentação completa e interativa está em /docs/api/, com todos os endereços, parâmetros e um botão para testar. A especificação OpenAPI 3.1 está em /docs/api/openapi.json.

1. Criar um token#

Em Integrações › API do NexaChat › Tokens de acesso, informe o nome do sistema, escolha a permissão e crie:

• Somente consultar (leitura): só lê dados.
• Consultar e criar/alterar (leitura e escrita): também cria e altera.

Copie o token na hora: ele só aparece uma vez. O NexaChat guarda apenas uma impressão digital dele. Você pode ter vários tokens (um por sistema), definir validade e revogar quando quiser: o acesso termina na hora.

2. Fazer uma chamada#

Todas as chamadas levam Authorization: Bearer SEU_TOKEN.

curl:

curl 'https://SEU-DOMINIO/api/v1/contacts?limit=5' \
  -H 'Authorization: Bearer SEU_TOKEN'

Node.js:

const res = await fetch('https://SEU-DOMINIO/api/v1/contacts', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + process.env.NEXACHAT_TOKEN, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ name: 'Maria Souza', phone: '+5531999998888' })
});
const json = await res.json();
if (!res.ok) throw new Error(json.error.code + ': ' + json.error.message);

PHP:

<?php
$ch = curl_init('https://SEU-DOMINIO/api/v1/conversations');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NEXACHAT_TOKEN'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['phone' => '+5531999998888', 'subject' => 'Segunda via', 'message' => 'Preciso da fatura']),
]);
$resposta = json_decode(curl_exec($ch), true);

O que a API oferece#

Contatos (listar, criar, buscar, alterar), atendimentos (listar, abrir, buscar, encerrar, transferir, atribuir), mensagens (listar e enviar) e, para leitura, agentes, filas e canais.

Regras importantes#

• Erros sempre no formato { "error": { "code": "...", "message": "..." } }.
• Limite: 300 chamadas por minuto por token. Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset mostram o saldo. Ao passar, a resposta é 429 com Retry-After.
• Listas usam cursor: envie limit e, para a próxima página, o next_cursor recebido.
• Idempotency-Key: envie um valor único nos POST. Se repetir a mesma chamada (por falha de rede, por exemplo), o NexaChat devolve o resultado original sem duplicar.
• Isolamento: um token só enxerga a própria empresa. O id de outra empresa responde 404.
• Auditoria: cada ação de escrita feita pela API aparece no histórico da empresa com o nome do token.

Objetos atualizados (v1.1)#

• Mensagem: channel, delivery_status (sent, delivered, read, failed) e transcript (texto do áudio do cliente, quando há motor de voz).
• Atendimento: tags, priority, department, protocol e quality (a Nota de Qualidade, somente leitura).

Veja a lista de mudanças por versão no Histórico de mudanças da documentação.

API antiga (/api/ext)#

Quem já usava o token único com os três endereços /api/ext/contacts, /api/ext/conversations e /api/ext/messages continua funcionando. Para integrações novas, use a API v1.

Enviar template do WhatsApp Oficial pela API#

POST /api/v1/messages/template (token com escopo de escrita) envia um template aprovado a um cliente, inclusive fora da janela de 24 h. Exemplo: {"to":"81999998888","template":"fatura_disponivel","variables":{"nome":"Maria","fatura_valor":"99,90"},"reference":"fatura-123"}. As variáveis podem ser uma lista (na ordem) ou um objeto com os nomes do template; reference e Idempotency-Key evitam envio duplicado. Templates de marketing não vão a quem respondeu SAIR (403). Veja WhatsApp Oficial.