Chatbot Builder - Help

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

  1. 1
    Registo 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.

  2. 2
    Criar 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.

  3. 3
    Upload 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).

  4. 4
    Teste 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

Elite+
🌐

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

1

Selecionar chatbot

Escolha o chatbot ao qual o documento será atribuído

2

Selecionar método de upload

📎 Ficheiros (PDF, DOCX, TXT, MD)

Máximo 10 MB por ficheiro

Elite+

🌐 Web URL

Scraping automático de páginas web

3

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

4

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

📊
Total de consultas
Número de todas as mensagens por período
Taxa de sucesso
Percentagem de respostas completas
⚠️
Respostas parciais
Percentagem de respostas parciais
📈
Fiabilidade média
Pontuação de similaridade de documentos

📊 Qualidade das respostas

✅ RespondidoXX%
Resposta completa encontrada
⚠️ ParcialXX%
Resposta parcial
❌ Sem respostaXX%
Resposta não encontrada

⚠️ 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

Current

Free

Perfect for getting started

$0/month

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

Trial

Evaluation

14-day trial with Enterprise features

$0/month

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

$15/month

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

Popular

Elite

Most popular

$30/month

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

$50/month

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:

  1. Your monthly quota is consumed first
  2. When monthly quota is exhausted, extra messages are automatically used
  3. Extra messages persist until fully consumed (no expiration)
  4. 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

  1. Aceda a Subscrição na barra lateral do painel
  2. Clique no botão Gerir Subscrição
  3. 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.

  1. Crie uma chave API no Dashboard → Integração API para o seu chatbot
  2. Inclua a chave API no cabeçalho Authorization como token Bearer
  3. Envie um pedido POST para o endpoint /api/chat
  4. 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 requests

Python

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. Sem conversation_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:

  1. Acionamento: A IA deteta uma pergunta sem resposta ou o utilizador expressa frustração
  2. Oferta: "Gostaria que criasse um ticket de suporte para si?"
  3. Consentimento: O utilizador confirma que deseja prosseguir
  4. Email: "Por favor, forneça o seu endereço de email para acompanhamento"
  5. Resumo: A IA gera automaticamente um resumo da conversa
  6. 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.

  1. Criar webhook: Introduza nome, URL e cabeçalhos de autenticação opcionais
  2. Definir ferramentas: Adicione as ferramentas que a IA pode chamar (ex. get_order_status, check_inventory)
  3. Definir parâmetros: Defina os parâmetros obrigatórios (ex. order_id, product_sku)
  4. Testar: Utilize a funcionalidade de teste para verificar que o webhook funciona corretamente
  5. 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:

  1. Crie um novo fluxo de trabalho no n8n
  2. Adicione um nó de acionamento Webhook (método POST)
  3. Copie o URL do webhook para a configuração do webhook do seu chatbot
  4. Construa a lógica do seu fluxo de trabalho (chamadas API, consultas de base de dados, etc.)
  5. 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)