Como criar um chatbot com IA da OpenAI na WOZTELL | User Guide
Como criar um chatbot com IA da OpenAI na WOZTELL
Conecte um assistente com tecnologia OpenAI ao WhatsApp, Instagram, Facebook Messenger e Webchat.
Este guia explica como configurar um chatbot com inteligência artificial na WOZTELL usando a extensão GPT Assistant e a Responses API da OpenAI.
Com esta extensão, você pode criar um assistente que responde automaticamente no WhatsApp Business Platform, Instagram, Facebook Messenger e Webchat. Também é possível ativar sugestões de resposta com IA dentro do WOZTELL Inbox para apoiar agentes humanos durante conversas ao vivo.
| Etapa de configuração | O que você vai configurar |
|---|---|
| 1 | Adicionar sua OpenAI API Key. |
| 2 | Configurar seu AI Chatbot, AI Inbox Replies, Knowledge Base e ferramentas. |
| 3 | Conectar o assistente a um ou mais canais da WOZTELL. |
Etapa 1 — Instalar a extensão GPT Assistant
1.1 Acessar o Marketplace
Vá para Marketplace → + New Extension.
No Marketplace, procure o cartão da extensão ChatGPT: Artificial Intelligence · OpenAI | WOZTELL. Em seguida, clique em Learn More.
1.2 Configurar a instalação
| Campo | O que fazer |
|---|---|
| Extension Version | Selecione v1.3.0. |
| Alias | Insira um nome único em letras minúsculas e sem espaços, por exemplo: my-gpt-assistant. |
| Description | Opcional. Adicione uma breve descrição sobre o que este assistente fará. |
Clique em Install. Se aparecer o erro “App Integration with alias already exists”, use um alias diferente.
Depois da instalação, clique no nome da extensão em Installed Extensions para abrir a janela de configuração. Você verá três seções principais: API Key Setup, Configuration e Connect to Channel.
Etapa 2 — Adicionar sua OpenAI API Key
A OpenAI API Key é necessária para acessar as seções de configuração e conexão de canais. Essa chave permite que a WOZTELL envie solicitações para sua conta OpenAI.
2.1 Gerar sua API Key na OpenAI
Na seção API Key Setup, clique em generate one here. Isso abrirá platform.openai.com em uma nova aba.
- Acesse API Keys.
- Clique em + Create new secret key.
- Adicione um nome descritivo, por exemplo:
woztell-gpt-assistant. - Mantenha o projeto como Default, a menos que sua conta OpenAI utilize uma estrutura específica de projetos.
- Clique em Create secret key.
- Copie a chave imediatamente.
2.2 Colar a chave na WOZTELL
Volte para a WOZTELL e cole a chave no campo API Key. Clique em Save. Uma marca verde confirma que a chave é válida. Depois de salva, as seções Configuration e Connect to Channel ficarão disponíveis.
Etapa 3 — Configurar o assistente de IA
A seção Configuration define como o assistente se comporta. Ela inclui três áreas principais:
| Área | Para que serve |
|---|---|
| AI Chatbot | Configura respostas automáticas do chatbot nos canais conectados. |
| AI Inbox Replies | Gera sugestões de resposta com IA para agentes humanos dentro do WOZTELL Inbox. |
| Knowledge Base | Permite carregar documentos que o assistente pode consultar ao responder perguntas. |
3.1 AI Chatbot — Configuração principal
A seção AI Chatbot controla o comportamento do assistente quando ele responde automaticamente aos usuários. Para um chatbot básico, você só precisa configurar Model e Instructions.
| Campo | O que fazer |
|---|---|
| Model | Selecione o modelo da OpenAI que gerará as respostas. A lista é carregada em tempo real a partir da sua conta OpenAI. Ponto de partida recomendado: gpt-4o mini, por ser rápido, econômico e confiável para a maioria dos casos de uso. |
| Transcription Model | Usado para converter mensagens de voz em texto. O modelo padrão costuma ser whisper-1. Mantenha-o sem alterações, a menos que exista um motivo específico para modificá-lo. |
| Instructions | O prompt de sistema que define o papel, tom, regras e comportamento do assistente. Essas instruções são enviadas ao modelo antes de cada conversa. |
Como escrever boas Instructions
As instruções devem definir claramente o papel do assistente, o tom, o escopo, as tarefas e as regras de encaminhamento para humanos.
Você é um assistente de pré-vendas da WOZTELL.
Seu objetivo é ajudar empresas a entender como a WOZTELL pode ajudá-las a automatizar conversas no WhatsApp, Instagram, Facebook Messenger e Webchat.
Seja amigável, conciso e profissional.
Responda apenas perguntas relacionadas à WOZTELL, WhatsApp Business Platform, chatbots com IA, integrações, automação e canais conversacionais.
Se o usuário perguntar sobre algo fora desse escopo, explique educadamente que você só pode ajudar com temas relacionados à WOZTELL.
Antes de qualificar o lead, peça nome, empresa, site e principal caso de uso.
| Elemento | Exemplo |
|---|---|
| Papel | “Você é um assistente de pré-vendas da WOZTELL.” |
| Tom | “Seja amigável, conciso e profissional.” |
| Escopo | “Responda apenas perguntas sobre nossos produtos e serviços.” |
| Tarefas | “Peça nome, empresa, site e caso de uso antes de qualificar o lead.” |
| Escalação | “Se o usuário perguntar sobre preços, integrações complexas ou suporte técnico, recomende falar com a equipe da WOZTELL.” |
3.2 Configurações avançadas
Esses campos são opcionais. A maioria dos usuários pode manter os valores padrão. Use-os apenas se precisar de mais controle sobre o comportamento do assistente ou se estiver trabalhando em uma integração personalizada.
| Campo | O que faz | Recomendação |
|---|---|---|
| Temperature | Controla o nível de criatividade ou consistência das respostas. Valores mais baixos tornam as respostas mais previsíveis. Valores mais altos tornam as respostas mais variadas. | Recomendado: 0.5. Alguns modelos podem não aceitar esse parâmetro; nesse caso, um erro aparecerá nos logs. |
| Top P | Outra forma de controlar a diversidade das respostas. | Use Temperature ou Top P, mas não ambos ao mesmo tempo. |
| Number of chat history messages used to provide context | Define quantas mensagens anteriores são enviadas como contexto para gerar uma nova resposta. | Padrão: 10. Valores mais altos podem melhorar o contexto, mas aumentam o consumo de tokens. Máximo aproximado: 20 mensagens. |
| Max Chat Session Duration | Define por quantos dias uma sessão permanece ativa. Quando a sessão expira, uma nova thread é criada e o contexto anterior é recarregado. | Padrão: 3 dias. Sessões mais longas podem aumentar o consumo de tokens. |
| Format | Define a estrutura de saída esperada. | Use Text para chatbots comuns. Use JSON Schema ou JSON Object apenas para integrações técnicas. |
3.3 Tools
As ferramentas permitem que o assistente acesse informações adicionais ou execute ações externas. Para adicionar uma ferramenta, clique no ícone + ao lado de Tools.
Web Search
Permite que o assistente pesquise na web em tempo real. Use quando o assistente precisar responder com informações atualizadas.
Você também pode usar Domain Filtering para restringir o assistente a sites específicos.
woztell.com
support.woztell.com
Não insira a URL completa com https://.
| Correto | Incorreto |
|---|---|
woztell.com | https://woztell.com/ |
File Search
Permite que o assistente pesquise arquivos armazenados em uma Knowledge Base / Vector Store. Use quando o assistente precisar responder com base em documentos carregados, FAQs, documentação de produto, guias internos ou materiais comerciais.
Antes de usar File Search, crie uma Knowledge Base e carregue os arquivos. Depois, selecione o Vector Store correspondente dentro da ferramenta File Search.
Function Call
Permite que o assistente execute ações externas, como consultar o status de um pedido, recuperar dados de clientes ou disparar um workflow. Essa opção exige uma integração técnica personalizada. A maioria dos usuários não precisa configurar Function Call na configuração básica.
3.4 AI Inbox Replies
O recurso AI Inbox Replies ajuda agentes humanos a responder mais rápido dentro do WOZTELL Inbox. Diferente do AI Chatbot, esse recurso não responde automaticamente ao cliente. Ele gera sugestões de resposta que os agentes podem revisar, editar e enviar manualmente.
- Um agente está atendendo uma conversa ao vivo.
- O agente precisa de ajuda para escrever uma resposta clara.
- A equipe quer responder mais rápido mantendo controle humano.
- A conversa exige contexto, empatia ou validação manual.
Depois que a extensão estiver ativa, as sugestões com IA ficam disponíveis no WOZTELL Inbox por meio da área de Power Apps.
Como configurar AI Inbox Replies
| Campo | O que fazer |
|---|---|
| Model | Selecione o modelo da OpenAI que gerará sugestões de resposta. |
| Instructions | Defina como o assistente deve escrever sugestões para os agentes. Esse prompt deve ser geral, porque se aplica globalmente ao WOZTELL Inbox. |
Você é um assistente de IA que ajuda agentes da WOZTELL a escrever respostas melhores dentro do Inbox.
Gere sugestões claras, concisas e profissionais com base no contexto da conversa.
Não faça promessas sobre preços, prazos, viabilidade técnica ou condições contratuais, a menos que estejam explicitamente confirmadas na conversa.
Mantenha um tom amigável e útil.
Se o cliente pedir algo que exige validação humana, sugira encaminhar a conversa para a equipe apropriada.
Configurações avançadas para AI Inbox Replies
| Campo | O que faz | Recomendação |
|---|---|---|
| Temperature | Controla o nível de criatividade das sugestões. | Recomendado: 0.5. |
| Max Tokens | Define o comprimento máximo de cada sugestão. Valores mais altos permitem respostas mais longas. | Use um valor moderado para manter respostas concisas. |
| Number of Suggestions | Define quantas opções de resposta são geradas para cada mensagem. | Recomendado: 2 ou 3 sugestões. |
| Previous messages used as context | Define quantas mensagens anteriores são usadas para gerar a sugestão. | Recomendado: 5. Mais contexto pode melhorar a precisão, mas aumenta o custo. |
3.5 Knowledge Base — Vector Stores
A Knowledge Base permite carregar documentos que o assistente pode consultar ao responder perguntas. Um Vector Store funciona como uma pasta: você pode carregar vários arquivos na mesma Knowledge Base e excluir arquivos individuais ou a pasta inteira quando necessário.
| Use uma Knowledge Base para... | Exemplos |
|---|---|
| Documentação de produto | Guias de funcionalidades, instruções de configuração, documentação técnica. |
| FAQs | Perguntas frequentes sobre preços, onboarding, canais, integrações ou suporte. |
| Material comercial | Sales decks, one-pagers, descrições de serviço. |
| Processos internos | Regras de escalonamento, playbooks de suporte, regras de qualificação. |
Como criar uma Knowledge Base
- Clique em + New Knowledge Base.
- Insira um nome descritivo, por exemplo:
woztell-faq. - Clique no ícone de upload.
- Arraste e solte seus arquivos, ou selecione-os a partir do seu dispositivo.
- Aguarde o processamento dos documentos.
- Volte para a configuração de AI Chatbot.
- Adicione a ferramenta File Search.
- Selecione a Knowledge Base / Vector Store que você criou.
Etapa 4 — Conectar o assistente a um canal
A seção Connect to Channel permite escolher onde o assistente ficará ativo. Você pode conectar o mesmo assistente a um ou mais canais da sua conta WOZTELL.
| Assistente de exemplo | Canal | Caso de uso |
|---|---|---|
| AI-CHATBOT-WHATSAPP-PRESALES | Qualificação de leads e perguntas comerciais. | |
| AI-CHATBOT-INSTAGRAM-SUPPORT | Social commerce e suporte. | |
| AI-CHATBOT-WEBCHAT-FAQ | Webchat | Automação de perguntas frequentes no site. |
| AI-CHATBOT-FACEBOOK-LEADS | Facebook Messenger | Gestão de leads recebidos. |
Entender canais e ambientes
Um canal é o canal de comunicação conectado à WOZTELL, como WhatsApp, Instagram, Facebook Messenger ou Webchat.
Um ambiente é um espaço dentro de um canal que pode ser usado para separar configurações de teste, desenvolvimento ou produção. Se você não criou ambientes adicionais, o assistente usará o ambiente default.
- Testar um chatbot antes de publicá-lo.
- Habilitar usuários específicos para testes.
- Separar configurações de desenvolvimento e produção.
- Executar diferentes assistentes em contextos diferentes.
Como conectar o assistente
- Vá para Section 3 — Connect to Channel.
- Encontre o canal e o ambiente onde deseja ativar o assistente.
- Clique em Connect.
- Insira um Prefix Name, se solicitado.
- Clique em Confirm.
- Clique novamente em Connect.
Depois de conectado, o botão mudará para Disconnect. Isso significa que o chatbot está ativo nesse canal e ambiente.
O que é o Prefix Name
O Prefix Name ajuda a identificar o assistente conectado a esse canal ou ambiente específico. Use um nome claro que explique o canal e o caso de uso.
AI-CHATBOT-WHATSAPP-PRESALES
AI-CHATBOT-INSTAGRAM-SUPPORT
AI-CHATBOT-WEBCHAT-FAQ
AI-CHATBOT-FACEBOOK-LEADS
Estrutura recomendada:
AI-CHATBOT-[CANAL]-[CASO-DE-USO]
Etapa 5 — Testar seu chatbot
Depois de conectar o assistente, teste-o antes de usá-lo com clientes reais.
Processo de teste recomendado
- Vá para o canal conectado na WOZTELL.
- Envie uma mensagem a partir de outro dispositivo, conta ou número.
- Verifique se o assistente responde corretamente.
- Confirme se a resposta está alinhada com suas Instructions.
- Teste diferentes tipos de perguntas.
- Teste casos-limite, como perguntas fora do escopo do assistente.
- Revise os logs se algo não funcionar como esperado.
Perguntas de teste sugeridas
Para um assistente de pré-vendas
Olá, quero automatizar o WhatsApp da minha empresa.
A WOZTELL pode conectar WhatsApp com Instagram?
Posso usar isso para atendimento ao cliente?
Quanto custa?
Posso falar com uma pessoa?
Para um assistente de suporte
Como posso conectar meu número de WhatsApp?
Por que meu template não foi aprovado?
Onde posso ver minhas conversas?
Como faço para carregar contatos?
Boas práticas antes de entrar em produção
| Boa prática | O que revisar |
|---|---|
| Revise as Instructions | O papel, tom, escopo, tarefas, limites e regras de escalonamento devem estar claros. |
| Carregue uma Knowledge Base limpa | Os documentos devem estar atualizados, bem estruturados e sem informações duplicadas ou contraditórias. |
| Teste cenários reais | Não teste apenas perguntas simples. Use conversas reais, objeções e mensagens ambíguas. |
| Monitore o consumo de tokens | Mais contexto, sessões longas, Knowledge Bases grandes e respostas extensas podem aumentar o consumo. |
| Mantenha o escalonamento humano disponível | Para vendas, suporte, preços, faturamento e dúvidas técnicas, é recomendável permitir que o assistente encaminhe para um agente. |
| Revise os logs regularmente | Os logs ajudam a detectar erros de API Key, modelo, ferramentas, prompt, File Search ou conexão de canal. |
Troubleshooting
Se o assistente não responder como esperado, revise primeiro a seção de logs. A maioria das mensagens de erro vem diretamente da OpenAI e normalmente indica o que falhou.
| Problema | Causa provável | Como resolver |
|---|---|---|
| API Key not accepted | A chave foi copiada incorretamente, foi revogada ou não é válida. | Gere uma nova chave na OpenAI e cole-a novamente na WOZTELL. |
| Alias error during installation | O alias já está sendo usado na sua conta WOZTELL. | Escolha um alias diferente. |
| Sections 2 or 3 are not accessible | A API Key ainda não foi salva. | Salve primeiro a API Key na Etapa 1. |
| Model does not appear in the list | Sua conta OpenAI não tem acesso a esse modelo. | Revise sua conta OpenAI, o projeto e as permissões do modelo. |
| Assistant is not responding | O canal não está conectado ou a API Key não é válida. | Verifique a conexão do canal e confirme que a API Key continua válida. |
| Temperature or Top P error appears in logs | O modelo selecionado não aceita esse parâmetro. | Desative o parâmetro ou mude para um modelo compatível. |
| File Search is not working | Não há arquivos carregados, o Vector Store incorreto foi selecionado ou File Search não foi adicionado como ferramenta. | Carregue arquivos, selecione a Knowledge Base correta e confirme que File Search está ativo. |
| Assistant answers with incorrect information | As Instructions não estão claras ou a Knowledge Base contém informações incompletas ou contraditórias. | Melhore o prompt e revise os documentos carregados. |
| Two OpenAI accounts are connected to the same channel | Outra extensão GPT Assistant já está ativa nesse canal. | Desconecte a extensão existente antes de conectar a nova. |
Recomendação final
Depois de configurar e testar o chatbot, continue melhorando-o com base em conversas reais. Revise as perguntas dos clientes, atualize a Knowledge Base, ajuste as Instructions e monitore o desempenho do assistente periodicamente.
Um assistente de IA bem configurado pode ajudar sua equipe a automatizar conversas repetitivas, apoiar agentes dentro do Inbox, qualificar leads mais rápido e oferecer respostas consistentes no WhatsApp, Instagram, Facebook Messenger e Webchat.