Como migrar seu chatbot de IA do GPT Assistant v1.2.0 para o v1.3.0 (Assistants API → Responses API)
Índice
Este guia explica como migrar um chatbot de IA existente do GPT Assistant v1.2.0 (baseado na Assistants API da OpenAI) para o GPT Assistant v1.3.0 (baseado na Responses API da OpenAI) dentro do WOZTELL.
O que esta migração é: e o que não é
| A migração não é automática | Não existe um botão que atualize da v1.2.0 para a v1.3.0. Você cria uma nova extensão v1.3.0 e reconstrói a configuração. |
| Uma nova extensão é criada | Sua extensão v1.2.0 não é alterada. Você instala uma extensão v1.3.0 separada, ao lado dela. |
| Seu chatbot v1.2.0 continua funcionando | Mantenha o chatbot antigo ativo até validar totalmente o novo, para que seus clientes nunca fiquem sem resposta. |
| Os usuários finais não são afetados | Os clientes continuam escrevendo pelo mesmo canal de WhatsApp, Instagram, Facebook Messenger ou Webchat. Só muda a conexão interna com a OpenAI. |
Abordagem recomendada: migrar com testes. Crie o novo chatbot v1.3.0, valide-o em um ambiente de teste com um grupo pequeno de testadores e só passe para produção quando tiver total confiança. Assim, seus clientes continuam conversando com o chatbot v1.2.0 já comprovado durante todo o processo, sem interrupções.
Antes de começar
Certifique-se de ter:
- Acesso à configuração da sua extensão v1.2.0 (você vai copiar os ajustes dela).
- Sua API Key da OpenAI (a mesma chave pode ser reutilizada).
- Pelo menos um canal já conectado no WOZTELL (WhatsApp Business Platform / Cloud API, Instagram, Facebook Messenger ou Webchat).
- Alguns testadores cujas contas ou números de telefone você possa usar para testar o novo chatbot com segurança.
A forma mais rápida de migrar é abrir a configuração da sua v1.2.0 em uma aba e a nova extensão v1.3.0 em outra, e copiar cada ajuste de uma para a outra.
Passo 1: Mantenha seu chatbot v1.2.0 ativo
Ainda não desconecte nem exclua seu chatbot atual. Ele permanece ativo e continua respondendo aos clientes durante todo o tempo em que você constrói e testa o novo. Você só vai desativá-lo no fim, durante a virada para produção (Passo 6).
Passo 2: Crie a nova extensão v1.3.0
Você vai criar o novo chatbot do zero, como uma extensão separada.
- Acesse Marketplace → + New Extension.
- Procure o card da extensão ChatGPT (Artificial Intelligence · OpenAI | WOZTELL) e clique em Learn More.
- Em Extension Version, selecione v1.3.0.
- Informe um Alias único (em minúsculas, sem espaços), por exemplo my-gpt-assistant-v13.
- Clique em Install e, em seguida, abra a nova extensão em Installed Extensions.
- Na seção API Key Setup, cole sua API Key da OpenAI e clique em Save. Uma marca verde confirma que a chave é válida e libera as seções Configuration e Connect to Channel.
Passo 3: Replique sua configuração
Na v1.2.0, todo o comportamento do seu chatbot ficava no prompt (Instructions). Migrá-lo é, basicamente, uma questão de copiar esse prompt e selecionar o modelo certo.
Na nova extensão v1.3.0, abra Configuration → AI Chatbot e defina as Instructions (prompt), o Model, o Transcription model e os ajustes avançados.
Como funcionam os canais e os ambientes
Este é o conceito que torna possível uma migração segura, então vale a pena entendê-lo antes de conectar qualquer coisa.
- Um canal é o canal de comunicação conectado ao WOZTELL: WhatsApp, Instagram, Facebook Messenger ou Webchat.
- Um ambiente é um espaço de trabalho dentro de um canal que permite separar os testes da produção. Se você não criou ambientes adicionais, o canal usa o ambiente Default.
Durante a migração, os ambientes permitem rodar o novo chatbot v1.3.0 em um ambiente de teste enquanto seu chatbot v1.2.0 permanece no ambiente ativo (Default/produção). Seus clientes continuam conversando com o chatbot antigo, já comprovado, até você decidir fazer a virada.
Passo 4: Conecte o novo chatbot a um ambiente de teste
Agora conecte o novo chatbot, mas a um ambiente de teste, não à produção.
- Se ainda não tiver um, crie um ambiente de teste e atribua testadores para o seu canal. Consulte: Como criar um ambiente de teste.
- Na extensão v1.3.0, abra a seção Connect to Channel.
- Encontre seu canal e selecione o ambiente de teste que você criou, não o ambiente Default/produção onde a v1.2.0 está ativa.
- Clique em Connect.
- Informe um Prefix Name, se solicitado; use um rótulo claro, como AI-CHATBOT-WHATSAPP-TEST.
- Clique em Confirm e depois em Connect novamente.
Quando o botão mudar para Disconnect, o novo chatbot estará ativo somente no ambiente de teste.
Passo 5: Teste e valide
Agora, apenas os testadores da sua lista (whitelist) são direcionados ao ambiente de teste e ao novo chatbot v1.3.0. A produção, e seus clientes reais, permanece na v1.2.0, sem alterações.
Peça aos seus testadores que coloquem o novo chatbot à prova:
- De um dispositivo ou número da whitelist, envie mensagens ao canal.
- Confirme que o chatbot responde e que as respostas correspondem às suas Instructions.
- Teste diferentes tipos de perguntas e casos extremos (inclusive perguntas fora do escopo do chatbot).
- Se você adicionou um Knowledge Base / File Search, faça perguntas que devam ser respondidas a partir dos seus documentos e confirme que funciona.
- Revise os logs em busca de erros (API Key, modelo, tools, File Search ou problemas de conexão do canal).
Passo 6: Faça a virada para produção
Quando estiver confiante no novo chatbot, troque seu canal ativo da v1.2.0 para a v1.3.0.
- Desconecte o chatbot v1.2.0 do canal/ambiente de produção (Default).
- Conecte o chatbot v1.3.0 a esse ambiente de produção (os mesmos passos do Passo 4, mas selecionando desta vez o ambiente de produção).
- Envie um último teste ao vivo para confirmar que o novo chatbot está respondendo em produção.
Depois de confirmar que a v1.3.0 está funcionando em produção, você pode remover com segurança a antiga extensão v1.2.0.
Problemas conhecidos durante a migração
| Problema | Causa | O que fazer |
|---|---|---|
| Respostas imprevisíveis / usuários chegando ao bot errado | Dois chatbots ficaram ativos dentro do mesmo ambiente. | Mantenha a v1.2.0 e a v1.3.0 em ambientes separados. Durante a virada, desconecte um antes de conectar o outro no mesmo ambiente. |
| Os testadores não conseguem acessar o novo chatbot | Nenhum Priority Group foi atribuído, ou os testadores não foram adicionados a ele. | Confirme que o Priority Group está atribuído ao ambiente de teste e que cada testador está na whitelist (no WhatsApp, os testadores precisam escrever primeiro para a WABA). |
| Parte da lógica baseada no prompt se comporta de forma diferente | A Responses API lida com o contexto de forma diferente da Assistants API. | Revise e ajuste o prompt durante a validação; considere mover o conteúdo de referência para o File Search. |
| O assistente não responde no ambiente de teste | A API Key não foi salva, o chatbot não está conectado ou o ambiente errado foi selecionado. | Confirme que a API Key está salva, que o chatbot está conectado e que você está escrevendo para o ambiente correto. |
Perguntas frequentes
Por que preciso migrar do GPT Assistant v1.2.0 para o v1.3.0?
A OpenAI vai encerrar a Assistants API, que é a base da v1.2.0, em 26 de agosto de 2026. Depois dessa data, os chatbots ainda na v1.2.0 podem parar de funcionar. A v1.3.0 roda na nova Responses API da OpenAI, então migrar mantém seu chatbot funcionando.
A migração é automática?
Não. Não existe um botão que atualize da v1.2.0 para a v1.3.0. Você cria uma nova extensão v1.3.0 e reconstrói a configuração, enquanto seu chatbot v1.2.0 continua funcionando até o novo estar pronto.
Meus clientes serão afetados durante a migração?
Não, se você migrar com testes. Você mantém a v1.2.0 ativa, cria e valida a v1.3.0 em um ambiente de teste separado e só passa para produção quando estiver confiante, então os clientes nunca ficam sem atendimento.
O que é um ambiente de teste e por que devo usá-lo?
Um ambiente é um espaço de trabalho dentro de um canal que separa os testes da produção. Rodar a v1.3.0 em um ambiente de teste permite que um grupo pequeno de testadores experimente, enquanto os clientes reais permanecem na v1.2.0, o que evita que dois chatbots colidam no mesmo ambiente.
Preciso reconstruir meu prompt e minhas configurações?
Sim. Na v1.2.0 o comportamento do chatbot ficava no prompt. Copie esse prompt para a nova extensão v1.3.0, selecione o modelo e o transcription model e replique suas configurações avançadas. Se quiser, mova o conteúdo de referência extenso para o File Search.
Qual é o prazo para migrar?
26 de agosto de 2026, quando a OpenAI encerra a Assistants API. Migre antes dessa data para evitar qualquer interrupção.
