Solução em modo Integração

Uma solução em modo Integração não tem página de chat própria. Outro sistema — um site, um aplicativo, uma plataforma de atendimento — envia as mensagens e recebe as respostas do agente por webhook.

O modo é escolhido ao criar a solução e faz três coisas mudarem:

• a solução ganha a aba Integração nas configurações;
• o item Chat vira Chat (Integração), somente para consulta;
• enquanto não houver integração cadastrada, a tela de agentes avisa e oferece o atalho Abrir configuração de integração.

Criar a integração

Em Configurações → Integração, clique em Nova integração.

Campo	O que informar
Nome da integração	Um rótulo para o sistema conectado
URL pública da API	Preenchida pela MarIA, com botão Copiar URL. É o endereço que o outro sistema vai chamar
Modo da conversa	Enfileirar quando ocupado (recomendado) ou Rejeitar quando ocupado, que devolve HTTP 409 na hora
Limitar requisições por minuto	Opcional; protege contra picos
Máximo de requisições simultâneas	Recomendado 50
URL do Webhook	Para onde a MarIA envia o resultado de cada execução

Uma solução pode ter mais de uma integração, cada uma com sua chave, seu webhook e seus limites — útil quando dois sistemas diferentes consomem a mesma solução.

A chave aparece uma única vez

Ao criar, a MarIA exibe a API key (mk_…) e o HMAC Webhook Secret (whsec_…). Os dois são mostrados uma só vez.

Segredo	Para que serve
API key	O sistema externo a envia no header X-API-Key ao chamar a MarIA
HMAC Webhook Secret	Permite ao seu sistema conferir o header X-Hub-Signature-256 e ter certeza de que o webhook veio mesmo da MarIA

Copie e guarde os dois antes de fechar a janela. Se perder, use Regenerar chave — o que invalida a anterior e exige atualizar o sistema conectado.

A lista de integrações

A tabela mostra Integração, Status, Webhook, Rate limit, Concorrência, API key (mascarada) e Atualizada em, com as ações Editar, Regenerar chave, Desativar e Excluir.

O link Abrir Swagger da integração mostra o contrato da API para quem vai programar o outro lado.

Acompanhar as conversas

O item Chat (Integração) na barra lateral mostra, apenas para consulta, as conversas criadas pelo sistema conectado. Você não escreve ali — é a janela para ver o que os usuários finais perguntaram e o que o agente respondeu.

Quando as mensagens não chegam

Sintoma	Causa provável
O sistema externo recebe 401	API key errada ou regenerada e não atualizada do outro lado
O sistema externo recebe 409	Modo da conversa em Rejeitar quando ocupado, com a conversa em andamento
A mensagem é aceita mas nada volta	URL do webhook errada ou inacessível a partir da MarIA
Recebe, mas o agente não responde nada	A solução não tem agente ativo — veja Agentes