Chatbot Builder - Ajuda
Guia completo para criar chatbots de IA a partir de vários documentos e fontes web
Visão geral
Chatbot Builder (Chatbotty.ai) é uma plataforma otimizada com Redis Cache para criar chatbots de IA a partir de vários documentos e fontes web. Serve a todos que precisam fornecer respostas de qualidade a consultas de utilizadores com base em documentos e fontes atuais - organismos públicos, organizações, empresas e particulares.
✨ Funcionalidades principais
🤖 IA e processamento
- • Chatbots de IA a partir de vários documentos e fontes web
- • Roteamento inteligente de IA para qualidade ótima de resposta
- • Base de dados vetorial para pesquisa semântica
- • Segmentação avançada por tipo de documento
⚡ Desempenho e fiabilidade
- • Cache multinível (Memória → Redis → PostgreSQL)
- • Widget assíncrono sem impacto na velocidade da página
- • Proteção contra abuso e ataques de bots
- • Limites de taxa flexíveis para chatbots individuais
📊 Gestão e análises
- • Amplas opções de personalização e configuração
- • Substituição automática de documentos com novas versões
- • Análises em tempo real e otimização de qualidade
- • Gestão automática de subscrições e planos
🎯 Ideal para
- Organismos públicos e instituições
Automação de serviços de informação para cidadãos, respostas a perguntas frequentes sobre procedimentos oficiais
- E-commerce e serviços online
Suporte inteligente ao cliente sem call center, gestão de encomendas e reclamações
- Empresas com documentação extensa
Pesquisa rápida em recursos internos, integração de novos colaboradores
- Instituições de ensino
Apoio a estudantes e respostas a perguntas frequentes, informações sobre programas de estudo
- Estabelecimentos de saúde
Informação ao paciente e apoio administrativo, guias para pacientes
- Escritórios de advocacia
Acesso rápido a documentos legais e precedentes, análise de casos jurídicos
- Empresas de TI e tecnologia
Automação de suporte técnico e documentação de API, resolução de problemas comuns
- Empresas de consultoria
Partilha de conhecimento e melhores práticas, base de conhecimento interna
- Agências de marketing
Análise de necessidades do cliente e otimização de conteúdo, assistência com briefings criativos
Primeiros passos
🎯 Guia rápido
- 1Registo e login
Crie a sua conta. Obtém automaticamente o plano Evaluation durante 14 dias com 3.000 mensagens/mês (mais do que as 500 do Elite) e todas as funcionalidades Elite.
- 2Criar o seu primeiro chatbot
Clique em "Novo Chatbot" → introduza nome e descrição → escolha o estilo de resposta (formal/amigável/profissional). Após a criação, será redirecionado para as configurações detalhadas onde pode personalizar todos os parâmetros do chatbot de acordo com as suas necessidades.
- 3Upload de documentos
Arraste e largue ficheiros PDF/DOCX/TXT/MD ou introduza o URL de uma página web. Pode escolher o tipo de documento para a estratégia de segmentação ótima (jurídico, técnico, académico, notícias, geral).
- 4Teste e incorporação
Teste o chatbot no modo de pré-visualização → copie o código de incorporação → insira no seu website
⚡ Dicas rápidas para começar
📄 Preparação de documentos
- • Estrutura: Use títulos claros, marcadores e numeração
- • Formato: PDF com texto legível (não imagens digitalizadas)
- • Tamanho: O tamanho do ficheiro afeta a velocidade de processamento
- • Conteúdo: Remova duplicados e partes irrelevantes
- • Linguagem: Terminologia e estilo consistentes
- • Metadados: Nomes de ficheiros claros para melhor organização
- • Atualidade: Use as versões mais recentes dos documentos
🎨 Integração do widget
Integração simples usando código JavaScript:
<script src="https://chatbotty.ai/chatbot-embed.js" data-chatbot-id="xxxxxxxx"> </script>
- • Carregamento assíncrono sem bloquear a página
- • Suporte entre domínios
Gestão de chatbots
➕ Criar chatbots
🎯 Configuração básica
Informações básicas:
- • Nome do chatbot: Identificação do seu chatbot
- • Descrição: Breve descrição do propósito do chatbot
- • Estilo de resposta: Formal / Amigável / Profissional / Informal
🎨 Aparência
Personalizar a aparência do widget do chatbot:
- • Cor do tema: Seleção de cores predefinidas
- • Mensagem de boas-vindas: Texto para primeiro contacto com o utilizador
- • Mensagem de erro: Texto exibido quando o chatbot está indisponível
- • Domínios permitidos para incorporação: Especifique onde o widget pode ser usado
💎 Número máximo de chatbots por plano
Free
1 chatbot
Evaluation
1 chatbot
14 dias de teste
Basic
1 chatbot
Elite
2 chatbots
Enterprise
3 chatbots
🗑️ Confirmação de eliminação
Processo de eliminação seguro
Ao eliminar um chatbot, surge um diálogo de confirmação para evitar eliminações acidentais. Isto garante que não perde dados importantes por engano.
⚠️ Aviso:
Todos os dados do chatbot, documentos e análises serão permanentemente removidos e não podem ser recuperados.
Configurações avançadas do chatbot
🧠 Comportamento da IA e prompts
📝 Instruções do sistema
Defina a personalidade e o comportamento do assistente de IA. Contém diretrizes para:
- • Estilo de comunicação e tom de resposta
- • Comportamento geral e regras
- • Instruções críticas para limitações
🏷️ Marcadores disponíveis
Os seguintes marcadores podem ser usados em prompts de instruções e mensagens:
- •
{current_datetime}- Data e hora atuais - •
{chatbot_id}- Identificador único do chatbot - •
{fallback_message}- Mensagem de fallback personalizada quando não há resposta
⚡ Qualidade de pesquisa e resposta
🔍 Parâmetros de pesquisa
- • Limiar de similaridade (0.4): Correspondência mínima para usar o documento
- • Número de fragmentos de documento no contexto (5): Quantos fragmentos de documento a IA recebe
- • Roteamento inteligente de modelo: Seleciona automaticamente o melhor modelo com base na complexidade da consulta
- • Tickets de suporte automáticos: Quando a IA não consegue responder, oferece criar um ticket de suporte. Requer consentimento do utilizador e email.
- • Forçar fallback: Quando ativado, mostra sempre a mensagem de fallback para consultas com baixa relevância de documento. Quando desativado, a IA responde mesmo sem documentos relevantes (modo conversacional).
⚙️ Preferências de idioma e parâmetros de IA
- • Idioma de resposta do chatbot: Idioma em que o chatbot responderá
- • Fuso horário: Para respostas sobre data e hora atuais
- • Criatividade (Temperatura): 0.0 = preciso, 1.0 = respostas criativas
- • Comprimento máximo da resposta (tokens): Limite em tokens (≈ 375 palavras para 500 tokens)
🛡️ Proteção anti-spam
- • Máx. pedidos/dia: Número máximo de pedidos de um endereço IP por 24 horas (proteção anti-bot)
- • Máx. pedidos/sessão: Número máximo de pedidos por sessão (janela de 2 horas para prevenção de abuso)
- • Limite de taxa por minuto: Proteção contra consultas de spam
- • TTL de cache (segundos): Quanto tempo manter as respostas em cache
🔄 Repor predefinições
Restaurar configurações predefinidas
O botão 'Repor predefinições' restaura todas as configurações avançadas para os seus valores predefinidos. Um diálogo de confirmação aparece antes da reposição para evitar alterações acidentais.
ℹ️ Nota:
Pode sempre repor as suas configurações para os valores predefinidos se quiser começar de novo ou se algo não estiver a funcionar como esperado.
Gestão de documentos
📤 Upload de ficheiros
📋 Fontes suportadas
Ficheiros
PDF, DOCX, TXT, MD, HTML
Web URL
Scraping automático
Atualizações
Substituição automática de versões
🎯 Preparação ótima de documentos
✅ Práticas recomendadas:
- • Títulos e estrutura claros
- • PDF com texto legível (não imagens)
- • Formatação consistente
- • Numeração lógica de secções
❌ Evitar:
- • Imagens digitalizadas sem OCR
- • Fragmentação excessiva de texto
- • Formatação inconsistente
- • Ficheiros maiores que 10MB
💾 Limites de armazenamento por plano
Free
10MB total
Evaluation
20MB total
Basic
10MB total
Elite
20MB total
Enterprise
50MB total
📋 Deteção de duplicados
Gestão inteligente de duplicados
Ao carregar um documento com o mesmo nome que um existente, surge um diálogo de confirmação com opções para evitar substituições acidentais.
Opções disponíveis:
- • Substituir: Substitui o documento existente pela nova versão
- • Manter ambos: Mantém ambas as versões (o novo ficheiro recebe um sufixo numérico)
📄 Processo de upload de documentos
Selecionar chatbot
Escolha o chatbot ao qual o documento será atribuído
Selecionar método de upload
📎 Ficheiros (PDF, DOCX, TXT, MD)
Máximo 10 MB por ficheiro
🌐 Web URL
Scraping automático de páginas web
Selecionar tipo de documento
O sistema otimiza automaticamente o processamento por tipo:
Documento jurídico:
Leis, regulamentos, contratos
Manual técnico:
Guias, especificações, procedimentos
Notícias:
Artigos, comunicados de imprensa
Texto académico:
Artigos científicos, estudos
Documento geral:
Configurações universais
Descrever documento (opcional)
Adicione uma descrição para navegação fácil na lista de documentos
Dica de atualização de ficheiros
Ao introduzir o mesmo nome de documento, tem a opção de substituição automática da versão original sem ter de eliminar o documento desatualizado. Os seus dados ficarão sempre atuais.
Widget de chat
🔧 Incorporação web (exibir chatbot no seu website)
📋 Obter código de incorporação
Pode encontrar o código de incorporação de cada chatbot no menu de contexto (três pontos). Clique em "Copiar código de incorporação" e cole-o no seu website antes da tag de fecho </body>.
<script src="https://chatbotty.ai/chatbot-embed.js" data-chatbot-id="xxxxxxxx"> </script>
💡 Dica: O widget carrega de forma assíncrona e não afeta a velocidade da sua página. A bolha de chat aparece assim que a configuração é carregada em segundo plano.
🔴 Nota: Se o chatbot estiver desativado, o widget não aparecerá no website.
⚠️ Instalação via GTM: Se incorporar o widget através do Google Tag Manager e um visitante rejeitar cookies, o GTM não carregará e o chatbot não aparecerá. Recomendamos incorporar o código diretamente no HTML, fora do GTM.
⚙️ Configuração do widget
Pode personalizar totalmente o widget na secção "Aparência" ao editar o chatbot. Todas as configurações são aplicadas automaticamente ao código de incorporação.
🎨 Aparência e posição:
- • Cor do tema: 6 cores predefinidas (azul, vermelho, verde, amarelo, roxo, laranja)
- • Posição do widget: Inferior direito / Inferior esquerdo
- • Mensagem de boas-vindas: Saudação ao utilizador
- • Mensagem de fallback: Texto para quando o chatbot não sabe a resposta
⚙️ Comportamento do chatbot:
- • Nome do chatbot: Exibido no cabeçalho
- • Descrição: Breve descrição do propósito do chatbot (não exibida na web)
- • Estilo de resposta: Profissional, amigável, formal
- • Estado: Chatbot ativo/inativo
🎯 Personalização do widget
Opções de posição:
- • Inferior direito (predefinição)
- • Inferior esquerdo
Efeitos da bolha:
- • Efeito de pulso - Bolha animada para atrair atenção (pode ser ativado/desativado)
👁️ Pré-visualização do widget
Use o modal de pré-visualização do widget para testar o seu chatbot antes de incorporar:
- • Clique no botão "Pré-visualizar" nas configurações do chatbot
- • Abre o widget numa janela modal
- • Teste todas as funcionalidades e aparência
- • Não é necessária instalação de código
🔗 Página pública do widget
Aceda ao seu widget em: /widget-embed/[widgetId]
- • Página autónoma para testes
- • Pode ser partilhada com membros da equipa
- • Não é necessária integração com website
💡 Dica: Todas as alterações entram em vigor imediatamente em todos os websites com o widget incorporado. Não é necessário alterar o código.
⚡ Otimização de desempenho
🚀 Carregamento assíncrono
- • Carregamento assíncrono em segundo plano
- • A bolha aparece quando a configuração está pronta
- • Zero impacto na velocidade da página principal
- • Melhoria progressiva
💾 Cache inteligente
- • 90%+ taxa de acerto de cache
- • Validade de configuração de 5 minutos
- • Carregamento rápido via Redis
- • Funcionamento estável mesmo durante falha do Redis Cache
🔒 Segurança e restrições
🌐 Restrições de domínio
Limitar o acesso apenas a domínios permitidos:
Exemplo de configuração:
- • example.com
- • *.example.com (incluindo subdomínios)
🛡️ Proteção anti-spam
Configurações de limite de pedidos para proteção contra spam e abuso
Máx. pedidos/dia
50
Número máximo de pedidos de um endereço IP por 24 horas (proteção anti-bot)
Máx. pedidos/sessão
20
Número máximo de pedidos por sessão (janela de 2 horas para prevenção de abuso)
Limite de pedidos/min
10
🛡️ Proteção contra consultas de spam
TTL de cache (segundos)
300
⚡ Quanto tempo manter as respostas em cache
📝 Nota:
Estes parâmetros são totalmente configuráveis pelo utilizador nas configurações avançadas de cada chatbot para máxima flexibilidade.
Análises
🎯 Acesso por plano
🆓 Free
Sem acesso
Popup de upgrade com instruções
⭐ Evaluation
Acesso completo
14 dias de funcionalidades Elite
🔵 Basic
Métricas básicas
- • Contagem de mensagens
- • Consultas principais
- • Estatísticas do chatbot
👑 Elite+
Análises detalhadas
- • Taxa de sucesso
- • Exportação de dados
- • Relatórios detalhados
- • Interface interativa
- • Análises para cada chatbot separadamente
🤖 Análises detalhadas por chatbotElite+
📋 Visualização por chatbot
- • Visão individual: Análises separadas para cada chatbot
- • Filtragem de consultas: Exibição apenas de conversas relevantes
- • Métricas isoladas: Desempenhos individuais dos chatbots separados
- • Comparação de chatbots: Possibilidade de comparar o desempenho de diferentes bots
🔍 Visualização detalhada de consultas
- • Consulta completa: Exibição da pergunta completa do utilizador
- • Fiabilidade da resposta: Valor exato da pontuação de confiança
- • Resposta da IA: Texto completo da resposta do chatbot
- • Carimbo temporal: Data e hora de cada consulta
💡 Utilização prática: Permite uma análise precisa de como os chatbots individuais respondem às consultas dos utilizadores, identificação de áreas problemáticas e otimização de documentos para cada chatbot separadamente.
📈 Métricas disponíveis
🎯 KPIs principais
📊 Qualidade das respostas
⚠️ Limitações do histórico de dados por plano
São retidos dados correspondentes ao número máximo de consultas por mês de acordo com o seu plano. Os dados mais antigos são automaticamente eliminados para otimização do desempenho da base de dados.
- • Free: 200 consultas
- • Basic: 3000 consultas
- • Elite: 6000 consultas
- • Enterprise: 10000 consultas
📤 Exportação e relatórios
📋 Disponibilidade: A funcionalidade de exportação está disponível apenas para planos Elite+ (Elite e Enterprise).
💡 Dica: Recomendamos exportar os dados no último dia de cada mês para acompanhar o histórico completo de consultas dos clientes.
💾 Formatos de exportação
- • CSV: Dados tabulares para Excel
- • JSON: Dados estruturados para API
🔍 Filtros de dados
🕐 Filtros temporais:
- • Esta semana: Últimos 7 dias
- • Este mês: Mês atual
- • Este ano: Ano atual
📋 Filtros por resposta:
- • Todas as consultas: Histórico completo
- • ✓ Respondido: Respostas bem-sucedidas
- • ⚠ Parcialmente respondido: Respostas incompletas
- • ✗ Sem resposta: Sem resposta
Subscrição
🎯 Visão geral dos planos
Free
Perfect for getting started
•10MB storage
•1 chatbot
•100 requests/month
•Basic support
•✅ Conversation history
•❌ Basic analytics
•❌ Web URL scraping
•❌ Analytics export
•❌ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Evaluation
14-day trial with Enterprise features
•10MB storage
•1 chatbot
•500 requests/month
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•✅ Support tickets (AI)
•✅ Webhook actions (n8n)
•❌ White-label branding
•➕ Buy extra requests
•Auto-downgrade to Free
Basic
For growing businesses
•25MB storage
•1 chatbot
•3000 requests/month (total)
•Priority support
•✅ Conversation history
•✅ Basic analytics
•❌ Web URL scraping
•❌ Analytics export
•❌ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Elite
Most popular
•50MB storage
•2 chatbots (max)
•6000 requests/month (total)
•Priority support
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Enterprise
Custom solutions
•100MB storage
•3 chatbots (max)
•10000 requests/month (total)
•Premium support
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•✅ Support tickets (AI)
•✅ Webhook actions (n8n)
•✅ White-label branding
•➕ Buy extra requests
💡 Utilização de dados
10MB de dados correspondem a aproximadamente 1000 páginas de documento PDF. Em formatos puramente textuais, ainda mais.
Aviso: O tamanho original do ficheiro carregado conta para os limites de dados. Imagens incorporadas nos documentos podem aumentar significativamente o tamanho do ficheiro carregado.
💰 Subscrição anual
Poupe 2 meses com faturação anual – pague apenas 10 meses!
A faturação anual oferece poupanças significativas em comparação com pagamentos mensais. Pode alterar o período de faturação ou a subscrição a qualquer momento.
⏰ Expiração do período de avaliação
- • Downgrade automático para o plano Free após 14 dias
- • Transição sem perdas de dados
📊 Acompanhamento de utilização
📊 Painel de acompanhamento
Acompanhe a utilização do seu plano diretamente em tempo real:
📈 Limites mensais
- • Número de mensagens por mês
- • Previsão até ao final do mês
- • Reposição automática todos os meses
📋 Limites permanentes
- • Capacidade de armazenamento (MB/MB)
- • Número de chatbots (quantidade/limite)
📊 Estatísticas
- • Total de chatbots criados
- • Chatbots ativos e funcionais
- • Total de consultas dos utilizadores
- • Documentos carregados
📈 Visualização
- • Barras de progresso coloridas
- • Acompanhamento em tempo real
⚠️ Aplicação de limites
- • Armazenamento excedido: Carregamento bloqueado com aviso de atualização
- • Limite de chatbots: Criação bloqueada, diálogo de atualização exibido
- • Mensagens mensais: O widget não carrega (falha silenciosa)
- • Acesso a análises: Restrições de funcionalidades por plano
💰 Extra Messages Add-ons
Extra messages are additional message packages you can purchase to extend your monthly quota. Unlike monthly subscriptions, extra messages never expire and persist across billing cycles.
🔄 How it works:
- Your monthly quota is consumed first
- When monthly quota is exhausted, extra messages are automatically used
- Extra messages persist until fully consumed (no expiration)
- Visible on dashboard with real-time tracking
📦 Available Packages:
💡 When to buy:
- • Seasonal traffic spikes
- • Special campaigns
- • Testing before upgrade
- • One-time high usage
💳 Purchase:Click "Buy Extra Messages" on dashboard or in usage tracking card when approaching limit.
Faturas
📋 Visão geral
Todas as suas faturas e histórico de pagamentos estão disponíveis diretamente no portal do cliente. Pode encontrar subscrições, compras de complementos e todos os pagamentos anteriores.
🔗 Como aceder
- Aceda a Subscrição na barra lateral do painel
- Clique no botão Gerir Subscrição
- Será redirecionado para o portal do cliente onde pode ver todas as faturas e o histórico de pagamentos
Definições
👤 Gestão da conta de utilizador
📝 Alterar nome
Informações pessoais
- • Nome: Nome de utilizador exibido
- • Pode ser alterado a qualquer momento
- • Aparece no perfil e na comunicação
📧 Alterar email
Após submeter o novo endereço, são enviados links de confirmação para ambos os emails, atual e novo. A alteração só entra em vigor após clicar em ambos os links.
- • Verifique a sua caixa de entrada atual e confirme a partir daí
- • Verifique a sua nova caixa de entrada e confirme a partir daí
- • Apenas após ambas as confirmações o novo email ficará ativo
🔒 Alterar palavra-passe
A palavra-passe deve ter pelo menos 6 caracteres
Requisitos da palavra-passe:
- • Mínimo de 6 caracteres
- • Combinação de letras e números
- • Palavra-passe atual necessária
Palavra-passe esquecida:
- • Reposição via email
- • Link de reposição seguro
- • Entrega imediata
🌐 Definições de idioma
Alternar entre a interface em inglês e checo
- • Clique no seletor de idioma na navegação superior
- • Idiomas disponíveis: Inglês (EN) / Checo (CS)
- • Recarregamento automático da página - A página recarrega automaticamente após a alteração do idioma para aplicar todas as traduções
- • A preferência de idioma é guardada na sua conta
⚠️ Zona de perigo
As ações nesta secção são irreversíveis. Proceda com cuidado.
⚠️ Eliminar a sua conta irá remover permanentemente todos os seus dados, chatbots, documentos e conversas. Esta operação é irreversível.
O botão "Eliminar Conta" irá acionar a remoção completa de todos os dados da base de dados.
API
🚀 Acesso programático aos chatbots
💎 Disponível para planos superiores
O acesso à API está disponível para utilizadores com planos de subscrição Evaluation, Elite e Enterprise. Permite integrar os seus chatbots em aplicações, websites ou sistemas personalizados.
📋 O que obtém
- • REST API: Pedidos HTTP padrão
- • Exemplos de código: JavaScript, Python, PHP, Node.js
- • ID do chatbot: Identificador único para cada chatbot
- • Documentação completa: Disponível diretamente na aplicação
💡 Como começar: Após iniciar sessão na aplicação, encontrará a secção "Integração API" no menu, onde pode aceder a instruções detalhadas incluindo exemplos de ligação para várias linguagens de programação e amostras de teste.
🔐 Autenticação da API
Como funciona
O acesso à API utiliza autenticação por token Bearer. Cada chave API está associada a um chatbot específico.
- Crie uma chave API no Dashboard → Integração API para o seu chatbot
- Inclua a chave API no cabeçalho Authorization como token Bearer
- Envie um pedido POST para o endpoint
/api/chat - O chatbot é automaticamente identificado a partir da chave API
Importante: NÃO precisa de enviar chatbot_id no corpo do pedido. O chatbot é determinado a partir da sua chave API.
🔑 Gestão de chaves API
Criar chaves API
Gere chaves API seguras para acesso programático aos seus chatbots.
Funcionalidades:
- • Nomes personalizados - Etiquete as chaves para fácil identificação
- • Máximo 50 chaves - Limite por chatbot
- • Tokens seguros - Token completo mostrado apenas uma vez na criação
- • Rastreamento de atividade - Carimbo temporal da última utilização
- • Alternar ativo/inativo - Desativar temporariamente sem eliminação
Segurança:
- • Os tokens são mascarados na interface (mostram apenas os primeiros/últimos caracteres)
- • Copiar para a área de transferência para fácil utilização
- • Eliminar chaves comprometidas imediatamente
⚡ Quota mensal: A utilização da API conta contra o seu limite mensal de mensagens. Mensagens extra podem ser adquiridas quando a quota é excedida.
💻 Exemplos de código
JavaScript (Browser)
// 1. first request – no conversation_id needed
const response = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What is your return policy?'
// conversation_id not required – created automatically
})
})
const result = await response.json()
const conversationId = result.data.conversation_id // save for follow-up requests
// 2. follow-up request – previous messages loaded as context
const response2 = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What about exchanges?',
conversation_id: conversationId
})
})Node.js
const response = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What is your return policy?',
conversation_id: conversationId // optional: to continue a conversation
})
})
const result = await response.json()
console.log(result.data.message)
// result.data.conversation_id – save for follow-up requestsPython
import requests
response = requests.post(
'https://chatbotty.ai/api/chat',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'message': 'What is your return policy?',
'conversation_id': conversation_id # optional: to continue a conversation
}
)
result = response.json()
print(result['data']['message'])PHP
<?php
$ch = curl_init('https://chatbotty.ai/api/chat');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'message' => 'What is your return policy?',
'conversation_id' => $conversationId // optional: to continue a conversation
]));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
echo $result['data']['message'];
?>cURL
curl -X POST https://chatbotty.ai/api/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What is your return policy?"}'📋 Formato da resposta
Resposta bem-sucedida
{
"success": true,
"data": {
"message": "AI response text...",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"sources": [
{
"content": "Relevant document excerpt...",
"similarity": 0.95,
"page": 1
}
],
"metadata": {
"tokensUsed": 150,
"cached": false,
"responseTime": 1234,
"searchResults": 3
}
},
"timestamp": "2025-01-28T10:00:00.000Z"
}Resposta de erro
{
"success": false,
"error": "Internal server error",
"timestamp": "2025-01-28T10:00:00.000Z"
}⚠️ Notas importantes
- • As chaves API são específicas por chatbot - Cada chave funciona com apenas um chatbot
- • Até 50 chaves por chatbot - Crie múltiplas chaves para diferentes aplicações
- • As chaves podem ser desativadas - Desativar temporariamente sem eliminação
- • Quota mensal aplicável - Limitada pelas mensagens/mês do seu plano + mensagens extra adquiridas
- • Sem limitação de taxa por minuto - A API foi concebida para acesso programático sem limites de taxa
- • Sem validação de domínio - A API funciona a partir de qualquer origem (utilize com cuidado)
- • Contexto de conversa - Cada resposta devolve um
conversation_id. Passe-o em pedidos subsequentes para manter o contexto — o sistema carrega as últimas 20 mensagens automaticamente. Semconversation_id, cada pedido inicia uma conversa nova sem contexto — isto é perfeitamente aceitável se não precisar de memória conversacional (ex. consultas pontuais de dados). - • Proteja as suas chaves - Nunca exponha chaves API em código do lado do cliente
Conversas
📝 Como funciona
A funcionalidade de Histórico de Conversas regista automaticamente todas as sessões do chatbot com metadados abrangentes para fins de análise, conformidade e garantia de qualidade.
- • Registo de sessões: Cada conversa é registada com um ID de sessão único
- • Rastreamento de metadados: Endereço IP, URL da página, referência, agente do utilizador
- • Carimbos temporais: Temporização precisa para cada troca de mensagens
- • Informação de contacto: Email e nome fornecidos pelo utilizador quando disponíveis
🔍 Visualizar conversas
Aceda ao histórico de conversas em Dashboard → Conversas no menu principal.
Filtros disponíveis:
- • Período: Filtrar por período de tempo (este mês, últimos 7 dias, etc.)
- • Filtro (Chatbot): Mostrar conversas para um chatbot específico ou todos
- • Fonte: Filtrar por fonte (widget, API, etc.)
Colunas exibidas:
- • ID da sessão, Data/Hora, Nome do chatbot
- • Contagem de mensagens, Fonte, Email de contacto
- • Endereço IP (anonimizado), URL da página
📋 Detalhes da conversa
Clique em qualquer conversa para ver o histórico completo de mensagens com informações detalhadas.
- • Cronologia de mensagens: Todas as perguntas dos utilizadores e respostas da IA
- • Dados temporais: Carimbos temporais exatos para cada mensagem
- • Metadados de origem: URL da página, referência, agente do utilizador
- • Informação de contacto: Email e nome se o utilizador os forneceu
💡 Dica: Utilize o histórico de conversas para identificar perguntas frequentes e melhorar a base de conhecimento do seu chatbot. Padrões nas consultas dos utilizadores podem ajudá-lo a adicionar documentação em falta.
Tickets de suporte
Funcionalidade Enterprise
Os tickets de suporte com IA estão disponíveis apenas para utilizadores do plano Enterprise.
🤖 Como funciona
O sistema de Tickets de Suporte com IA deteta automaticamente quando o chatbot não consegue responder à pergunta de um utilizador e oferece a criação de um ticket de suporte para acompanhamento humano.
- • Deteção inteligente: A IA reconhece quando não consegue fornecer uma resposta satisfatória
- • Consentimento do utilizador: O sistema pergunta ao utilizador se deseja criar um ticket
- • Recolha de email: Recolhe o email do utilizador para acompanhamento
- • Resumo da IA: Gera um resumo da conversa para a equipa de suporte
📝 Fluxo de criação de tickets
O fluxo de conversa em múltiplos turnos para criação de tickets:
- Acionamento: A IA deteta uma pergunta sem resposta ou o utilizador expressa frustração
- Oferta: "Gostaria que criasse um ticket de suporte para si?"
- Consentimento: O utilizador confirma que deseja prosseguir
- Email: "Por favor, forneça o seu endereço de email para acompanhamento"
- Resumo: A IA gera automaticamente um resumo da conversa
- Confirmação: Ticket criado com número de referência
📋 Gestão de tickets
Aceda e faça a gestão dos tickets de suporte em Dashboard → Tickets de Suporte.
Fluxo de estados:
- • Aberto: Novo ticket a aguardar revisão
- • Em progresso: Equipa de suporte a trabalhar no problema
- • Resolvido: Problema tratado, a aguardar confirmação
- • Fechado: Ticket concluído e arquivado
Ações disponíveis:
- • Ver contexto completo da conversa
- • Atualizar estado do ticket
- • Adicionar notas internas
- • Enviar resposta por email ao utilizador
⚙️ Configuração
Ative e configure os tickets de suporte em Definições do Chatbot → separador Tickets de Suporte.
- • Ativar/Desativar: Alternar a criação de tickets para este chatbot
- • Notificações por email: Receber alertas para novos tickets
- • Resposta automática: Mensagem personalizada enviada ao utilizador após criação do ticket
- • Acionamentos: Configurar quando as ofertas de tickets são feitas
💡 Dica: Reveja os tickets regularmente para identificar lacunas na sua base de conhecimento. Tópicos comuns dos tickets indicam áreas onde deve adicionar mais documentação.
Ações webhook
Funcionalidade Enterprise e Evaluation
As ações webhook estão disponíveis para utilizadores Enterprise (até 10 webhooks, até 10 ferramentas no total em todos os webhooks) e Evaluation (até 5 webhooks, até 5 ferramentas no total em todos os webhooks).
🔗 Visão geral
As Ações Webhook permitem que o seu chatbot interaja com sistemas externos através de chamadas de ferramentas acionadas pela IA. Defina webhooks personalizados com ferramentas específicas que a IA pode invocar durante as conversas.
- • Webhooks personalizados: Defina endpoints com autenticação
- • Ferramentas de IA: Especifique as ferramentas que a IA pode chamar (ex. get_order_status)
- • Parâmetros: Defina parâmetros obrigatórios e opcionais para cada ferramenta
- • Tratamento de respostas: A IA processa as respostas dos webhooks naturalmente
⚙️ Configurar webhooks
Configure os webhooks em Dashboard → Webhooks para cada chatbot.
- Criar webhook: Introduza nome, URL e cabeçalhos de autenticação opcionais
- Definir ferramentas: Adicione as ferramentas que a IA pode chamar (ex. get_order_status, check_inventory)
- Definir parâmetros: Defina os parâmetros obrigatórios (ex. order_id, product_sku)
- Testar: Utilize a funcionalidade de teste para verificar que o webhook funciona corretamente
- Ativar: Ative o webhook para utilização em produção
🔄 Integração n8n
O n8n é uma ferramenta poderosa de automação de fluxos de trabalho que funciona perfeitamente com o nosso sistema de webhooks.
Configuração rápida:
- Crie um novo fluxo de trabalho no n8n
- Adicione um nó de acionamento Webhook (método POST)
- Copie o URL do webhook para a configuração do webhook do seu chatbot
- Construa a lógica do seu fluxo de trabalho (chamadas API, consultas de base de dados, etc.)
- Devolva uma resposta JSON que a IA irá processar
Formato de resposta exemplo:{"status": "shipped", "tracking": "1Z999AA1", "eta": "2024-01-15"}
💡 Exemplos de casos de utilização
📦 Consulta de estado da encomenda
O cliente pergunta "Onde está a minha encomenda?" → A IA chama get_order_status com o número da encomenda → Devolve informação de rastreamento
👤 Integração CRM
O utilizador fornece o email → A IA chama lookup_customer → Devolve detalhes da conta e atividade recente
📅 Marcação de consultas
O utilizador solicita uma consulta → A IA chama check_availability depois book_appointment → Confirma a marcação
🔍 Verificação de inventário
O cliente pergunta sobre disponibilidade do produto → A IA chama check_stock → Devolve o inventário atual
🔒 Segurança
- • HTTPS obrigatório: Todos os endpoints de webhook devem utilizar HTTPS
- • Cabeçalhos personalizados: Adicione tokens de autenticação nos cabeçalhos
- • Tratamento de timeout: Timeout de 30 segundos evita pedidos pendentes
- • Proteção SSRF: Endereços IP privados são bloqueados por segurança
- • Limitação de taxa: Proteção integrada contra chamadas excessivas
⚠️ Importante: Nunca exponha chaves API sensíveis nos URLs dos webhooks. Utilize cabeçalhos de autenticação em vez disso.
💡 Dica: Comece com operações simples de leitura (como consulta de encomendas) antes de implementar operações de escrita. Teste exaustivamente utilizando o testador de webhooks integrado antes de ativar em produção.
Dicas e truques para preparação de documentos e implementação bem-sucedida do chatbot
📄 Preparação de documentos
📋 Estruturação de conteúdo
- • Divisão temática: Um ficheiro = um tema
- • Estrutura lógica: Secções e títulos claros
- • Atualizações fáceis: Altere apenas as partes relevantes
- • Clareza: Orientação rápida no conteúdo
📝 Formato e nomenclatura
- • Formatos de texto: TXT, DOC, DOCX (sem imagens)
- • Nomes claros: Nomes de ficheiro descritivos
- • Atualização automática: Mesmo nome = substituição
- • Sem preocupações: Versão antiga eliminada automaticamente
💡 Dica: Prepare os documentos antecipadamente em formato de texto simples. Imagens e formatação complexa podem piorar a qualidade das respostas do chatbot.
🎯 Pesquisa semântica
🔍 Como o chatbot encontra respostas
- • Correspondência semântica: Procura significado similar, não texto exato
- • Palavras-chave: Identifica termos importantes na consulta
- • Contexto: Considera o significado da frase inteira
- • Similaridade: Compara com informação existente
✍️ Formulação ótima
- • Respostas diretas: "X tem Y anos" em vez de "X celebrou Y anos"
- • Várias formulações: Utilize diferentes formas de expressão
- • Perguntas esperadas: Pense nas possíveis consultas dos utilizadores
- • Palavras-chave: Inclua sinónimos e variantes
❌ Menos adequado:
"O Big Ben celebrou o seu 165.º aniversário"
✅ Melhor:
"O Big Ben tem 165 anos"
Porquê:A segunda versão responde melhor a perguntas como "Quantos anos tem o Big Ben?" ou "Qual é a idade do Big Ben?"
📊 Otimização baseada em análises
🔍 Análise de lacunas
- • Consultas sem resposta: Acompanhe perguntas frequentes sem respostas
- • Baixa fiabilidade: Identifique consultas com baixa confiança
- • Problemas recorrentes: Encontre padrões em consultas malsucedidas
- • Frustrações dos utilizadores: Observe pontos onde os utilizadores ficam "presos"
🎯 Melhorias direcionadas
- • Expansão de documentos: Adicione informação em falta
- • Reformulação: Clarifique passagens pouco claras
- • Novas formulações: Adicione diferentes formas de expressão
- • Testar e iterar: Teste alterações e meça as melhorias
💯 Interpretação da fiabilidade
< 30%
Resposta malsucedida
30-40%
Parcialmente respondida
> 40%
Resposta bem-sucedida
💡 Dica: Teste as suas modificações diretamente no chatbot. Faça as mesmas perguntas novamente e monitorize as alterações de fiabilidade. O objetivo é atingir consistentemente mais de 40% de fiabilidade.
Porquê valores tão baixos? Para 100% de fiabilidade, a consulta precisaria de ser identificada exatamente com a mesma redação no documento, o que acontece muito raramente. Portanto, os valores realistas são mais baixos.
❓ Otimização de FAQ
📈 Análise das consultas mais frequentes
- • Acompanhar tendências: Identifique perguntas recorrentes
- • Priorização: Concentre-se nas consultas mais frequentes
- • Padrões: Procure formulações similares da mesma pergunta
- • Problemas: Encontre consultas com baixa fiabilidade
📝 Criação de documento FAQ
- • Um parágrafo = P&R: Pergunta e resposta juntas
- • Linguagem natural: Utilize formulações comuns
- • Respostas completas: Toda a informação necessária de uma vez
- • Várias variantes: Inclua sinónimos e alternativas
✨ Exemplo de FAQ otimizado
Quanto tempo demora o processamento de um pedido de passaporte?O processamento de um pedido de passaporte demora normalmente 6-8 semanas a partir da submissão de uma candidatura completa. Para necessidades de viagem urgentes, está disponível processamento acelerado em 2-3 semanas por uma taxa adicional de 60€. Pode recolher o seu passaporte pessoalmente no centro de candidatura ou recebê-lo por correio na sua morada.
🚀 Resultado: O documento FAQ aumenta dramaticamente a fiabilidade das respostas às consultas mais frequentes. Satisfará 80-90% das perguntas dos utilizadores com alta precisão.
📊 Análise a longo prazo
🔍 Monitorização regular
- • Verificação semanal: Acompanhe respostas malsucedidas
- • Visão mensal: Analise tendências e alterações
- • Respostas parciais: Identifique áreas para melhoria
- • Padrões de problemas: Encontre deficiências recorrentes
📤 Exportação de análisesElite+
- • Formato CSV: Para MS Excel e Numbers
- • Dados detalhados: Todas as consultas e respostas
- • Fiabilidade: Nível de confiança para cada consulta
- • Carimbo temporal: Acompanhamento de tendências ao longo do tempo
📈 Fluxo de trabalho recomendado
1. Exportação semanal
Descarregue os dados da última semana
2. Análise Excel
Filtre por fiabilidade < 40%
3. Atualizações
Modifique documentos com base nos resultados
💡 Para utilizadores avançados: Utilize tabelas dinâmicas do Excel para agrupar consultas similares e identificar as áreas problemáticas mais comuns.
🌐 Utilização de fontes web
🔗 Extração de URL webElite+
- • Importação direta: Carregue conteúdo de websites
- • Secções FAQ: Ideal para Perguntas Frequentes existentes
- • Documentação: Utilize documentação existente pronta
- • Conteúdo atual: Sempre a versão mais recente da informação
✅ Benefícios da extração web
- • Poupança de tempo: Sem reescrita manual
- • Consistência de dados: Sem diferenças entre websites e chatbot
- • Atualizações automáticas: Basta recarregar o URL
- • Conteúdo estruturado: A formatação é preservada
📋 Fontes ideais para extração
✅ Páginas adequadas:
- • Secções FAQ
- • Documentação de produtos
- • Guias e procedimentos
- • Informação de contacto
❌ Menos adequadas:
- • Páginas com muitas imagens
- • Menus de navegação
- • Conteúdo publicitário
- • Conteúdo gerado por JavaScript
💡 Dica: Se tiver FAQ ou documentação de qualidade no seu website, utilize a extração de URL em vez de reescrita manual. Isto evita inconsistências e poupa tempo durante as atualizações.
💡 Dicas para obter o máximo valor
Obtenha melhores respostas do seu chatbot e aproveite ao máximo a sua quota mensal de mensagens com estas dicas:
📄 Qualidade dos documentos:
- • Remova conteúdo desnecessário antes do carregamento — documentos mais limpos = respostas mais precisas
- • Utilize documentos bem estruturados com títulos e secções claros
- • Evite informação duplicada entre documentos
❓ Incentive boas perguntas:
- • Perguntas específicas e focadas obtêm melhores respostas do que vagas
- • Documentos bem preparados levam a respostas mais rápidas e precisas
📊 Monitorize a sua utilização:
- • Acompanhe a sua quota de mensagens nas análises do painel
- • Para picos sazonais de tráfego, utilize complementos de mensagens extra em vez de atualizar o plano
- • Reveja as tendências mensais para decidir se o seu plano atual se adequa às suas necessidades
Resolução de problemas
⚠️ Problemas comuns
🤖 Chatbot não responde
Possíveis causas:
- • Limite mensal de mensagens excedido
- • Domínio bloqueado por restrições
- • Limitação de taxa ativada
- • Erro de carregamento do widget
Solução:
- • Verifique a utilização no painel
- • Verifique os domínios permitidos
- • Ferramentas de desenvolvimento do navegador → separador Rede
- • Contacte o suporte com detalhes do erro
📄 Documento não processa
Problemas comuns:
- • Ficheiro maior que o limite do plano
- • Formato não suportado
- • PDF corrompido ou protegido por palavra-passe
- • Sobrecarga da fila de processamento
Diagnóstico:
- • Verifique o tamanho do ficheiro vs limite do plano
- • Tente selecionar texto no PDF
- • Estado de processamento nos documentos
- • Tente carregar novamente se estiver preso
🌐 Widget não carrega
Problemas de carregamento:
- • Bloqueio por política CORS
- • Timeout no carregamento do script
- • CSP (Content Security Policy)
- • Interferência de bloqueador de anúncios
Passos de solução:
- • Mensagens de erro na consola do navegador
- • Tente outro navegador/incógnito
- • Desative temporariamente os bloqueadores de anúncios
- • Verifique as definições de domínios permitidos
🆘 Contacto de suporte
📧 Suporte por email
support@chatbotty.ai
- • Planos prioritários: em 24h (excecionalmente até 48h)
- • Planos gratuitos: normalmente em 72h
- • Anexos: Capturas de ecrã, logs bem-vindos
🔍 O que incluir
- • Tipo e versão do navegador
- • Mensagem de erro ou captura de ecrã
- • ID do chatbot e URL do widget
- • Passos de reprodução
- • Erros da consola (F12)