Integre via HTTPS, não slides
Implemente chat servidor a servidor, transmita tokens para sua própria interface e dispare automações a partir de webhooks que terminam no seu host FlexyAgents. As rotas abaixo são os handlers Next.js reais — copie os valores de Implantação depois de gerar uma conexão de API FlexyAgents.
- POST /api/agents/{agentId}/chat aceita Bearer ligados à conexão FlexyAgents de automação e executa a mesma pilha RAG + modelo que o widget
- Streaming opcional devolve chunks JSON NDJSON; sem streaming a resposta é um único payload do assistente
- Limites por IP antes dos planos; planos hospedados aplicam orçamentos de tokens e BYOK devolve erros explícitos se faltar a chave do provedor
- Gatilhos webhook, callbacks de canal e integrações de saída compartilham o mesmo modelo de tenancy — tudo resolve a organização e agente
Precisa de chaves primeiro? Criar um workspace e abra Configurações → Chaves de API ou o modal de conexão do agente.
Superfícies HTTP em resumo
Os caminhos refletem a árvore de rotas Next.js. Substitua os placeholders pelo ID do agente e pelo host da sua tela de implantação.
- POST/api/agents/{agentId}/chat
Chat do agente e streaming
Envie um corpo JSON com um array messages (role + content) e a flag stream opcional. Bearer valida contra a chave de API da FlexyAgents guardada na conexão do agente; com chave correta a organização é resolvida automaticamente.
- POST/api/webhooks/automations/...
Entrada de gatilhos de automação
Automações publicadas podem expor URLs webhook que deserializam payloads e chamam executeAutomation — útil quando seus serviços devem iniciar fluxos sem OAuth.
- GET/POST/api/webhooks/*
Webhooks de canais e provedores
Rotas irmãs em /api/webhooks gerenciam WhatsApp, Instagram, Facebook Messenger, e-mail entrante e callbacks similares para que implantação omnicanal fique no seu domínio.
- —Integrações → Webhooks
Entrega de saída
Configure webhooks de saída assinados no painel quando quiser que a FlexyAgents envie eventos de conversa ou do sistema ao seu SIEM, data lake ou ponte com ticketing.
Chamada mínima sem streaming
curl -X POST "https://SEU_HOST_APP/api/agents/ID_AGENTE/chat" \
-H "Authorization: Bearer SUA_CHAVE_API_FLEXYAGENTS" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Olá"}],"stream":false}'Substitua pelos valores copiados de Implantação → API depois de conectar o app FlexyAgents nesse agente.
Invocar
Chat HTTPS-first com o mesmo cérebro que o widget
A tela de implantação copia um curl contra seu host ao vivo. O handler valida chaves de API com o armazenamento de conexões de automação, carrega comportamento + conhecimento e incrementa uso como qualquer outro canal.
Contrato do array messages
O corpo deve incluir pelo menos um turno de chat. O executor recorta o histórico à última mensagem de usuário para recuperação, mas aceita arrays multi-turno para uso futuro.
- Roles limitados a user, assistant ou system no validador
- Metadados só em headers quando documentado — priorize o contrato JSON
- Formas inválidas devolvem 400 com detalhe Zod para depurar mais rápido
Modo streaming
Com stream: true você recebe chunks NDJSON (um objeto JSON por linha) que o frontend pode despejar na UI conforme tokens chegam.
- Ideal para clientes mobile ou desktop com paridade com widget hospedado
- Erros no meio do stream também são serializados como linhas JSON
- Desative streaming se proxies bufferizarem agressivamente as respostas
Chaves Bearer API vs cookies de sessão
Contas de serviço devem usar a chave de conexão FlexyAgents gerada por agente. Testes interativos podem usar sessão do painel, mas servidor a servidor sempre Bearer.
- Chaves são criptografadas em repouso junto às demais credenciais de automação
- Rotacionar uma chave não muda o ID do agente na sua URL
- Chaves inválidas ou ausentes devolvem 401 antes de gastar modelo
Limites que você verá em produção
Limites com Redis devolvem 429 ante picos. O plano adiciona MESSAGE_LIMIT_REACHED para cotas mensais hospedadas/BYOK e tetos de tokens em inferência hospedada.
- Automações e chat compartilham a mesma contabilidade em nível org
- Registre IDs de correlação dos erros ao falar com suporte
- Faça upgrade ou adicione créditos onde billing permitir mais throughput
Eventos
Traga sua stack para a FlexyAgents — e empurre eventos de volta
Rotas entrantes normalizam assinaturas de vendor enquanto configuração de saída vive junto ao restante de integrações. Automações também podem POST HTTP arbitrário dentro de um fluxo.
Gatilhos webhook de automação
Quando um fluxo publica um gatilho webhook, a FlexyAgents guarda o segmento de rota e verifica payloads antes de chamar executeAutomation com o corpo parseado.
- Combina com passos de agente que chamem Slack, CRMs ou REST próprios
- Gating por plano pode exigir nível superior antes da ingestão genérica
- Logs aparecem no mesmo histórico de execução que gatilhos OAuth
Callbacks de provedores de canal
WhatsApp, Instagram DM, Messenger e e-mail entrante registram endpoints HTTPS públicos para que Meta, Twilio ou e-mail verifiquem e entreguem eventos.
- Configure URLs de callback no console do vendor para coincidir com seu host de implantação
- Handshakes de verificação ocorrem nas mesmas rotas que tráfego real
- Mantém payloads sensíveis em infraestrutura que você já audita
Ações HTTP de saída
Ações de automação podem POST ou PUT em URLs do cliente com corpos templados — p.ex. «notificar Opsgenie» ou «criar ticket Jira» sem esperar conector de primeira parte.
- Mapeie campos do gatilho a corpos JSON com o builder de automações
- Retries e erros seguem os defaults do executor de automações
- Combine com passos de agente para resumos legíveis antes de entregar
Referência
Especificações, docs e ferramentas exploratórias
Páginas de marketing são narrativas; engenheiros devem apoiar-se em /docs, definições OpenAPI no repo e snippets de implantação que sempre coincidem com seus IDs de tenant.
Centro de documentação
Comece em /docs com guias conceituais e linke para /api para inícios rápidos, primers de autenticação e referências em abas quando existirem.
- Exemplos com curl, JavaScript e padrões de embed do widget
- Promessas de SDK/Postman devem coincidir com o que realmente distribuímos
- Reporte lacunas via suporte para alinhar marketing e redação técnica
OpenAPI como fonte da verdade
O repositório inclui OpenAPI completo com schemas de auth, payloads de chat e recursos REST auxiliares — gere clientes ou importe no Postman a partir desse arquivo.
- Versionamento segue o ritmo de releases do pacote, não esta landing
- URLs base de staging e produção estão em servers do spec
- Em local você bate no mesmo path /api/agents/{id}/chat que em produção no seu host de tenant
Widget e companheiros mobile
Nem toda experiência precisa de REST bruto — o script embed chama o mesmo endpoint de chat com contexto de visitante. Combine API com widget para self-service web e jobs backend.
- Páginas hospedadas reutilizam a configuração do agente que você já testou
- CSP e cookies devem permitir a origem do widget que você configurar
- Deep links de e-mail podem abrir chat hospedado com query params
Combine APIs com Automações, Canais e governança em Analytics.
Próximo passo
Copie um curl funcional e endureça para produção
Gere a chave de conexão FlexyAgents, cole no seu cofre de segredos e aponte webhooks de automação para os caminhos que você controla. Quando estiver pronto, conecte observabilidade ao mesmo workspace de analytics que sua equipe de sucesso ao cliente já usa.