Publique seu workflow como uma interface de chat conversacional com a qual os usuários interagem por um link compartilhável ou widget embutido. O chat oferece suporte a conversas multi-turno, upload de arquivos e entrada por voz.
Cada mensagem do chat dispara uma nova execução do workflow, com o histórico completo da conversa passado como contexto. As respostas voltam em streaming para o usuário em tempo real.
Execuções de chat rodam contra o snapshot de deployment ativo do workflow. Publique um novo deployment depois de alterar o canvas para que o chat use a versão atualizada.
Criando um chat
Abra o workflow, clique em Deploy e selecione a aba Chat. Você verá o painel de configuração do chat:
Configure os campos a seguir e clique em Launch Chat:
| Campo | Descrição |
|---|---|
| URL | Slug que forma a URL pública, por exemplo https://app.zoen.space/chat/your-slug. Apenas letras minúsculas, números e hífens. Deve ser único em todos os workspaces. |
| Title | Nome exibido no cabeçalho do chat. |
| Output | Campos de saída dos blocos do workflow retornados como resposta do chat. Pelo menos um deve ser selecionado. |
| Welcome Message | Saudação mostrada antes da primeira mensagem do usuário. O padrão é "Hi there! How can I help you today?". |
| Access Control | Controla quem pode acessar o chat. Veja Controle de acesso abaixo. |
Seleção de saída
O dropdown de saída agrupa os campos disponíveis por bloco. Em um bloco Agent, você pode escolher entre content, model, tokens, toolCalls, providerTiming e cost. Na maioria dos casos, selecionar content do bloco Agent final é o suficiente — ele transmite a resposta em texto do agente diretamente ao usuário.
Controle de acesso
| Modo | Descrição |
|---|---|
| Public | Qualquer pessoa com o link pode conversar — sem autenticação |
| Password | Os usuários precisam digitar uma senha antes de começar a conversar |
| Só endereços de e-mail ou domínios específicos podem acessar. Os usuários verificam com um OTP de 6 dígitos enviado ao e-mail | |
| SSO | Single sign-on baseado em OIDC (somente enterprise) |
Acesso por e-mail: Adicione endereços individuais (user@example.com) ou domínios inteiros (@example.com) no campo Allowed emails. Os usuários recebem um OTP de 6 dígitos de uso único na caixa de entrada — depois de verificados, podem conversar durante a sessão.
Acesso por senha: Um campo de senha aparece quando este modo é selecionado. Compartilhe a senha diretamente com os usuários; eles a digitam antes de a conversa começar.
SSO: Usa OIDC para autenticar usuários pelo seu provedor de identidade. Disponível em planos enterprise.
Compartilhamento
Link direto
https://app.zoen.space/chat/your-slugIframe
<iframe
src="https://app.zoen.space/chat/your-slug"
width="100%"
height="600"
frameborder="0"
title="Chat"
></iframe>Envio via API
Você também pode enviar mensagens a um chat de forma programática. As respostas são transmitidas com server-sent events (SSE).
curl -X POST https://app.zoen.space/api/chat/your-slug \
-H "Content-Type: application/json" \
-d '{
"input": "Hello, I need help with my order",
"conversationId": "optional-conversation-id"
}'const response = await fetch('https://app.zoen.space/api/chat/your-slug', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
input: 'Hello, I need help with my order',
conversationId: 'optional-conversation-id'
})
});
// Response is an SSE stream
const reader = response.body?.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader!.read();
if (done) break;
console.log(decoder.decode(value));
}Com upload de arquivos
curl -X POST https://app.zoen.space/api/chat/your-slug \
-H "Content-Type: application/json" \
-d '{
"input": "What does this document say?",
"files": [{
"name": "report.pdf",
"type": "application/pdf",
"size": 1048576,
"data": "data:application/pdf;base64,..."
}]
}'Chats protegidos
Para chats protegidos por senha, inclua a senha no body da request:
curl -X POST https://app.zoen.space/api/chat/your-slug \
-H "Content-Type: application/json" \
-d '{ "password": "secret", "input": "Hello" }'Para chats protegidos por e-mail, autentique com OTP primeiro:
# Step 1: Request OTP — sends a 6-digit code to the email address
curl -X POST https://app.zoen.space/api/chat/your-slug/otp \
-H "Content-Type: application/json" \
-d '{ "email": "allowed@example.com" }'
# Step 2: Verify OTP — save the Set-Cookie header for subsequent requests
curl -X PUT https://app.zoen.space/api/chat/your-slug/otp \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{ "email": "allowed@example.com", "otp": "123456" }'
# Step 3: Send messages using the auth cookie from Step 2
curl -X POST https://app.zoen.space/api/chat/your-slug \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{ "input": "Hello" }'Solução de problemas
Chat retorna 403 — O deployment está inativo. Abra o modal Deploy e publique o workflow de novo.
"At least one output block is required" — Nenhum campo de saída está selecionado no dropdown Output. Abra o modal Deploy, vá à aba Chat e selecione pelo menos uma saída de um bloco.
E-mail de OTP não chega — Confirme que o endereço de e-mail está na lista de permitidos e verifique a pasta de spam. Códigos OTP expiram após 15 minutos e podem ser reenviados depois de um cooldown de 30 segundos.
Chat não carrega no iframe — Verifique se a Content Security Policy do seu site permite iframes de app.zoen.space.
Respostas não atualizam depois de mudanças no workflow — O chat usa o snapshot de deployment ativo. Publique um novo deployment pelo modal Deploy para incorporar as alterações mais recentes.