Índice da documentação

Guia · Início rápido

Integre o agente ao seu sistema

Neste guia você coloca o agente do Genius Hub dentro do seu produto: o seu usuário conversa na sua interface, e o Hub cuida da IA, do histórico, do WhatsApp e do atendimento humano.

Você vai	Tempo
1. Criar uma chave de API	2 min
2. Fazer a primeira chamada	2 min
3. Expor o chat pelo seu backend	5 min
4. Montar a inbox (opcional)	—
5. Conectar o WhatsApp (opcional)	—
6. Receber eventos por webhook (opcional)	—

Pré-requisitos

Uma conta no Genius Hub com perfil de titular ou administrador e ao menos um agente criado. Ainda não tem agente? Veja como criar um.

Como as peças se ligam

┌──────────────┐      ┌──────────────────┐   x-api-key   ┌─────────────────┐
│ Seu front-end│ ───► │  Seu backend     │ ────────────► │ Genius Hub API  │
│ (site / app) │ ◄─── │  (guarda a chave)│ ◄──────────── │ /api/v1         │
└──────────────┘      └──────────────────┘               └────────┬────────┘
                              ▲                                   │
                              │   webhook assinado (HMAC)         │
                              └───────────────────────────────────┘

Passo 1

Crie uma chave de API

1No painel, abra Configurações → Integração (API). O ID do agente está na mesma tela, em IDs para a integração.
2Dê um nome que identifique o sistema: site, app, erp.
3Em Agentes autorizados, marque só os agentes que esse sistema vai usar.
4Defina uma validade, se a integração for temporária.
5Clique em Gerar chave e copie o valor — ele aparece uma única vez.

Guarde a chave e o id do agente nas variáveis de ambiente do seu backend. O id do agente aparece na URL da página dele no painel.

Uma chave por sistema. Assim você revoga a do site sem derrubar a do ERP, e sabe qual delas está em uso.

.env

# .env do seu backend — nunca no front-end
GENIUS_API_URL=https://api.geniushub.online/api
GENIUS_API_KEY=ghk_sua_chave
GENIUS_AGENT_ID=593eb3c4-08f5-437f-a377-d2d59da4fb10
GENIUS_WEBHOOK_SECRET=segredo_do_webhook

Passo 2

Faça a primeira chamada

Envie uma mensagem ao agente com POST /v1/chat. A resposta vem na mesma chamada, no campo reply.

O chatId é a conversa

O chatId é um identificador que você escolhe. Envie sempre o mesmo valor para o mesmo usuário e o agente lembra do que já foi conversado — o histórico fica no Hub, você não precisa reenviá-lo.

Use algo estável do seu sistema: usuario-{id}, pedido-{numero}, ticket-{id}.
Não gere um chatId novo a cada mensagem — cada valor novo começa uma conversa do zero.
Não use número de telefone: ele é o chatId das conversas de WhatsApp do agente, e a API recusa com 409.

Campos da resposta que importam

Campo	O que fazer
`reply`	Exiba como a mensagem do agente. Pode vir vazio se o contato estiver bloqueado ou silenciado.
`handoff`	Se `true`, o agente pediu uma pessoa. Avise sua equipe; o motivo está em `handoffReason`.
`files`	Arquivos que o agente quis enviar. A URL é temporária: exiba ou baixe logo.

POST /v1/chat

curl -X POST "https://api.geniushub.online/api/v1/chat" \
  -H "x-api-key: $GENIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'"$GENIUS_AGENT_ID"'",
    "chatId": "cliente-8842",
    "message": "Olá, preciso de ajuda",
    "senderName": "Maria"
  }'

Resposta

{
  "agentId": "593eb3c4-08f5-437f-a377-d2d59da4fb10",
  "chatId": "cliente-8842",
  "reply": "Olá, Maria! Como posso ajudar?",
  "messageId": "9a41c0de-…",
  "toolCallsExecuted": [],
  "handoff": false
}

Passo 3

Exponha o chat pelo seu backend

O navegador nunca fala direto com o Genius Hub. Crie uma rota no seu servidor que recebe a mensagem do usuário logado, chama a API com a chave e devolve só o que a interface precisa.

A chave fica no servidor — quem abre o DevTools não a encontra.
O chatId sai da sessão do seu usuário, não do corpo da requisição. Isso impede que alguém leia a conversa de outra pessoa trocando um parâmetro.
Você controla limites, logs e o formato da resposta para o seu front-end.

O agente pode levar alguns segundos para responder (ele consulta a base de conhecimento e ferramentas). Mostre um indicador de “digitando” e use um timeout de 60 segundos no seu backend.

Seu backend como intermediário

// O navegador chama ESTA rota; só o servidor conhece a chave.
app.post("/api/chat", autenticarUsuario, async (req, res) => {
  const resposta = await fetch(`${process.env.GENIUS_API_URL}/v1/chat`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.GENIUS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agentId: process.env.GENIUS_AGENT_ID,
      // O chatId vem da SUA sessão, nunca do corpo enviado pelo navegador:
      // assim um usuário não lê a conversa de outro.
      chatId: `usuario-${req.user.id}`,
      message: String(req.body.message ?? "").slice(0, 8000),
      senderName: req.user.name,
    }),
  });

  const dados = await resposta.json();
  if (!resposta.ok) return res.status(resposta.status).json({ erro: dados.message });

  res.json({ reply: dados.reply, handoff: dados.handoff, files: dados.files ?? [] });
});

Passo 4 · opcional

Monte a sua inbox de atendimento

Se a sua equipe vai acompanhar e assumir conversas dentro do seu sistema, estas rotas dão tudo o que uma inbox precisa:

Na interface	Rota
Lista de conversas	`GET /v1/chat/sessions/{agentId}`
Mensagens da conversa	`GET /v1/chat/history/{agentId}/{chatId}`
Botão “Assumir atendimento”	`POST /v1/chat/takeover`
Responder pelo WhatsApp	`POST /v1/messages/send`
Botão “Devolver para a IA”	`POST /v1/chat/release`
Mensagens novas em tempo real	Webhooks

Estado de cada conversa

handoffStatus	Significado	Sugestão de interface
`AGENT`	A IA está respondendo.	Etiqueta neutra “IA”.
`WAITING`	O agente pediu uma pessoa.	Destaque e alerta para a equipe.
`HUMAN`	Alguém assumiu; a IA está em silêncio.	Mostrar o atendente e o botão “Devolver”.

Mídia nas mensagens

Nos eventos de webhook, use mediaKind e mimeType para escolher o componente — nunca trate tudo como texto. Sem mediaUrl, mostre a mensagem como “arquivo indisponível” em vez de quebrar a conversa.

mediaKind	Exibir como
`null`	Balão de texto com content.
`image`	Miniatura com opção de ampliar.
`audio`	Player de áudio.
`video`	Player de vídeo.
`document`	Cartão com nome do arquivo e botão de download.

Operações da inbox

GET https://api.geniushub.online/api/v1/chat/sessions/{agentId}
x-api-key: ghk_sua_chave

Passo 5 · opcional

Conecte e use o WhatsApp

Para o agente atender no WhatsApp, o número precisa estar conectado. Você pode fazer isso pelo painel, na tela WhatsApp, ou pela API — útil quando o seu próprio produto oferece a conexão aos seus clientes:

Crie o canal para o agente.
Peça o QR Code e exiba para o usuário ler no celular.
Consulte o canal até o status virar CONNECTED. O QR expira: gere outro quando necessário.
Pronto: o agente responde sozinho, e você pode enviar mensagens com POST /v1/messages/send.

QUEUED significa que a mensagem entrou na fila de envio, não que já chegou ao aparelho. Assine o evento message.sent para saber quando ela saiu.

Conectar e enviar

POST https://api.geniushub.online/api/v1/channels
x-api-key: ghk_sua_chave
Content-Type: application/json

{ "agentId": "{agentId}", "displayName": "WhatsApp da Loja" }

→ 201 { "instance": { "id": "{instanceId}", "status": "DISCONNECTED", … } }

Passo 6 · opcional

Receba eventos em tempo real

Em vez de consultar a API repetidamente, aponte um webhook: o Hub faz um POST no seu servidor a cada mensagem recebida ou enviada pelo número.

Configurar

Pelo painel: Configurações → Webhook da integração, escolha o canal, informe a URL e salve.
Pela API: POST /v1/webhooks/config, como no exemplo ao lado.
Nos dois casos o secret aparece uma única vez. Guarde em GENIUS_WEBHOOK_SECRET.

Receber com segurança

Valide a assinatura X-Genius-Signature antes de qualquer coisa.
Ignore repetições pelo deliveryId.
Responda 2xx em até 10 segundos e processe numa fila.

Quando a sua URL falha

O Hub tenta a entrega até três vezes: na hora, dois segundos depois e oito segundos depois, cada uma com limite de 10 segundos de espera. Passadas as três, o evento é descartado: não há reenvio posterior nem fila de eventos perdidos. O último erro fica registrado no webhook do canal, em lastError.

Por isso, use o webhook como aviso e a API como fonte da verdade: se um evento se perder, a conversa continua na API.
Um evento só é enviado para mensagens que o Hub gravou. Mensagens de grupo ignoradas pelo agente não geram evento.
Uma mesma mensagem reentregue pelo WhatsApp não gera um segundo evento.

Como verificar a assinatura

Configurar

POST https://api.geniushub.online/api/v1/webhooks/config
x-api-key: ghk_sua_chave
Content-Type: application/json

{
  "instanceId": "{instanceId}",
  "url": "https://seusistema.com.br/hooks/genius",
  "events": ["message.received", "message.sent"]
}

→ 201 { …, "secret": "6f1c9d0b7e…" }   ← guarde: aparece uma vez só

Receber

app.post("/hooks/genius", express.raw({ type: "application/json" }), async (req, res) => {
  if (!assinaturaValida(req)) return res.sendStatus(401); // veja "Verificar a assinatura"

  const evento = JSON.parse(req.body.toString("utf8"));

  // A mesma entrega pode chegar mais de uma vez.
  if (await jaProcessado(evento.deliveryId)) return res.sendStatus(200);

  switch (evento.event) {
    case "message.received":
      await inbox.adicionar(evento.data.chatId, { lado: "contato", ...evento.data });
      break;
    case "message.sent":
      await inbox.marcarEnviada(evento.data.chatId, evento.data.providerMessageId);
      break;
  }

  res.sendStatus(200); // responda rápido; trabalho pesado vai para a fila
});

Checklist de produção

	Item
Segurança	Chave só no backend, em variável de ambiente; uma chave por sistema; restrita aos agentes necessários.
Segurança	chatId derivado da sessão do usuário, nunca enviado pelo navegador.
Segurança	Webhook em HTTPS, com assinatura e timestamp validados.
Robustez	Repetir só em 429 e 5xx, com espera crescente. Não repetir 4xx.
Robustez	Timeout de 60 s nas chamadas de chat e indicador de “digitando” na interface.
Robustez	Eventos de webhook deduplicados por deliveryId.
Operação	handoff: true chega à equipe (notificação, fila ou chamado).
Operação	Alerta para 401 (chave revogada/vencida) e para falhas em lastError do webhook.

Referência completa da API Como criar um bom agente