Agente de IA de Apoio ao Cliente: documentação completa

Guia completo de instalação, configuração e utilização do plugin DataFirefly AI Customer Service Agent, um agente de IA de apoio ao cliente para WooCommerce que percebe o contexto, chama ferramentas apenas de leitura na sua loja e escalona de forma inteligente os casos complexos para o Slack e para o e-mail.

1. Requisitos

• WordPress 6.4 ou superior
• WooCommerce 8.0 ou superior
• PHP 8.1, 8.2 ou 8.3
• Uma chave de API da Anthropic (Claude) ou da OpenAI (recomendado: Claude Sonnet 4.5)
• Opcional: um webhook do Slack para o escalonamento em tempo real
• Opcional: Polylang Pro ou WPML se a sua loja for multilingue

2. Instalação

Instalação do ZIP

1. A partir da sua conta DataFirefly, descarregue o ficheiro df-ai-customer-service.zip
2. No WordPress, vá a Plugins → Adicionar plugin → Carregar plugin
3. Selecione o ZIP e clique em Instalar
4. Clique em Ativar quando a instalação terminar

O que acontece na ativação?

O plugin cria automaticamente 5 tabelas na base de dados com o prefixo wp_dfaics_: conversations, messages, escalations, faq e analytics. Declara também a compatibilidade com HPOS e com os blocos Gutenberg de carrinho e checkout, e agenda uma tarefa cron diária para limpar as conversas expiradas.

3. Configuração do fornecedor de IA

O plugin suporta dois fornecedores de IA. Escolhe o que preferir em AI Support → Definições → IA. Fornece a sua própria chave de API: a DataFirefly não interceta nada nem cobra qualquer comissão sobre o seu consumo.

Opção A: Claude (recomendado)

1. Crie uma conta em console.anthropic.com
2. Gere uma chave de API em Settings → API Keys
3. Copie a chave (começa por sk-ant-...)
4. No WordPress, vá a AI Support → Definições → IA
5. Selecione o fornecedor Anthropic (Claude)
6. Cole a chave no campo Chave de API Anthropic
7. Modelo predefinido: claude-sonnet-4-5 (excelente relação qualidade/custo)
8. Clique em Testar a chave para validar
9. Guarde

Opção B: OpenAI

1. Crie uma conta em platform.openai.com
2. Gere uma chave de API em API Keys
3. Copie a chave (começa por sk-...)
4. No WordPress, selecione o fornecedor OpenAI
5. Modelo predefinido: gpt-4o-mini (o mais económico com tool calling fiável)

Custo indicativo

Uma conversa típica de 5 a 10 trocas com tool calling custa:

• Cerca de 0,01 a 0,05 USD com o Claude Sonnet 4.5
• Cerca de 0,005 a 0,02 USD com o GPT-4o mini

O painel mostra o total de tokens de entrada e de saída consumidos no período.

4. Configuração do widget

O widget de chat aparece por predefinição em baixo à direita em todas as páginas do front-end. Personalize-o em AI Support → Definições → Widget.

Opções de aparência

• Cor principal: cor do botão flutuante e do cabeçalho (por predefinição #0073aa)
• Cor do texto: cor do texto no cabeçalho (por predefinição, branco)
• Posição: em baixo à direita ou em baixo à esquerda
• Título do widget: por exemplo «Precisa de ajuda?»
• Mensagem de boas-vindas: primeira mensagem apresentada na abertura
• Placeholder: texto do campo de introdução
• Apresentar o distintivo DataFirefly: pequena menção no fundo do widget

Apresentação condicional

No separador Widget, pode limitar a apresentação:

• Todas as páginas: comportamento predefinido
• Apenas páginas de produto: para um apoio dirigido às fichas
• Exceto carrinho e checkout: para evitar a distração durante a compra
• Ocultar nestes IDs de conteúdo: lista de IDs a excluir

Shortcode

Também pode integrar o chat numa página ou num artigo com o shortcode:

[dfaics_chat]

Isso apresenta o widget em modo integrado (não flutuante), prático para uma página «Contacte-nos» dedicada.

5. As 6 ferramentas do agente

O agente dispõe de 6 ferramentas que escolhe chamar ou não conforme a pergunta. Todas são estritamente de leitura. Ativa-as ou desativa-as individualmente em Definições → Comportamento.

lookup_order

Obtém o estado de uma encomenda WooCommerce. Exige uma verificação obrigatória do e-mail antes da divulgação: o agente pede o e-mail ao cliente e confronta-o com o da encomenda. Devolve o número, o estado, o montante, a data, o método de entrega e o número de seguimento, se existir.

search_products

Pesquisa no catálogo por nome, categoria, etiqueta, disponibilidade e intervalo de preços. Devolve até 5 resultados por predefinição com título, SKU, preço, URL e stock. Útil para responder a «tem isto em azul?» ou «qual é o preço de X?».

get_shipping_info

Devolve as zonas e os métodos de entrega configurados no WooCommerce, com os custos e os prazos. O agente pode assim responder com precisão a «entregam em Espanha?» ou «quanto custa o expresso?».

get_returns_policy

Devolve o conteúdo da sua política de devoluções (que configura nas definições). O agente pode explicar o prazo, o procedimento e as condições.

search_faq

Procura nas suas FAQ personalizadas (geridas em AI Support → FAQ). Resultados delimitados pelo idioma da conversa. Cada entrada encontrada incrementa um contador de utilização, para o ajudar a identificar as perguntas mais frequentes.

escalate_to_human

O agente chama esta ferramenta quando determina que um caso precisa de um humano (frustração do cliente, caso complexo, várias falhas de ferramentas). Desencadeia as notificações de Slack e/ou de e-mail configuradas. Ver a secção Escalonamento mais abaixo.

6. Gestão da FAQ

Crie entradas de FAQ personalizadas que o agente possa pesquisar durante uma conversa. Cada entrada está delimitada por idioma.

Criar uma entrada

1. Vá a AI Support → FAQ
2. Clique em Adicionar uma entrada
3. Escolha o idioma
4. Redija a pergunta e a resposta em linguagem natural
5. Acrescente palavras-chave separadas por vírgulas (facultativo, melhora a pesquisa)
6. Escolha uma categoria (por exemplo entrega, tamanhos, garantia)
7. Guarde

Boas práticas de FAQ

• Formule as perguntas como um cliente as faria, não como um redator de SEO
• Respostas curtas e acionáveis (2 a 4 frases chegam, o agente reformula)
• Crie uma entrada por cada idioma principal da sua clientela
• Consulte regularmente o contador de utilização para identificar as perguntas a enriquecer

7. Escalonamento para um humano

O escalonamento configura-se em Definições → Escalonamento. São suportados dois canais em paralelo: Slack e e-mail.

Configuração do Slack

1. No Slack, crie uma nova app em api.slack.com/apps
2. Ative os Incoming Webhooks
3. Crie um webhook para o canal pretendido (por exemplo #support-escalations)
4. Copie o URL do webhook
5. No WordPress, cole-o em Webhook do Slack
6. Clique em Testar o webhook para enviar uma mensagem de teste

Cada escalonamento envia ao Slack uma mensagem em blocos ricos com: o excerto das 3 últimas mensagens, o motivo do escalonamento, os metadados do cliente (e-mail verificado, idioma, página de origem) e um botão Abrir na administração que aponta diretamente para o detalhe da conversa.

Configuração do e-mail

Em E-mail de escalonamento, indique um ou vários endereços separados por vírgulas. Cada escalonamento envia um e-mail HTML com a transcrição completa, os dados do cliente e uma ligação para a administração.

Acionadores de escalonamento

O agente escalona em 3 situações:

1. Palavras-chave sensíveis: lista configurável (por predefinição: reembolso, advogado, partido, reclamação, complaint, refund, lawyer, broken)
2. Limiar de sentimento: deteção de frustração ou de descontentamento (parametrizável de -1 a 0)
3. Falha repetida de ferramentas: após 6 voltas sem resolução, escalonamento forçado

8. Painel e análises

O painel AI Support → Dashboard mostra 4 indicadores-chave:

• Volume: número total de conversas nos últimos 7, 30 ou 90 dias
• Taxa de autorresolução: percentagem de conversas que terminam sem escalonamento
• Satisfação média: classificação em estrelas dada pelos clientes após o escalonamento
• Tokens consumidos: entrada mais saída acumuladas, para a estimativa do custo de IA

A página Conversas lista todas as sessões com filtros (idioma, estado, com ou sem escalonamento). Clique numa linha para ver a transcrição completa com as chamadas de ferramentas detalhadas em JSON.

9. Multilingue

O plugin suporta nativamente 5 idiomas: francês, inglês, espanhol, alemão e italiano. O idioma da conversa é resolvido automaticamente por esta ordem:

1. Idioma Polylang da página onde o widget é apresentado (se o Polylang estiver instalado)
2. Idioma WPML da página (se o WPML estiver instalado)
3. Locale do navegador do visitante
4. Idioma de recurso configurado nas definições (por predefinição: inglês)

O system prompt do agente indica explicitamente ao modelo o idioma de resposta esperado. Isso garante que um visitante que escreva em francês recebe uma resposta em francês, mesmo que a sua loja seja maioritariamente inglesa.

10. Segurança e confidencialidade

Cifragem das chaves de API

As chaves da Anthropic e da OpenAI e o webhook do Slack são cifrados em AES-256-CBC no momento da gravação, com uma chave derivada da AUTH_KEY mais a AUTH_SALT. O campo de introdução nunca reapresenta o valor: se deixar o campo vazio e guardar, o valor anterior é preservado.

Verificação de e-mail nas encomendas

A ferramenta lookup_order exige obrigatoriamente uma verificação: o agente pede ao cliente o seu e-mail e confronta-o com o associado à encomenda. Sem correspondência, nenhum dado é divulgado. Este comportamento não é desativável, porque protege contra a extração de encomendas através do agente.

Limite de débito

É aplicado no servidor um limite anti-spam de 5 mensagens por minuto por sessão. O número máximo de mensagens por conversa é de 25 por predefinição (configurável). Acima disso, o agente propõe um escalonamento humano.

Retenção e RGPD

As conversas são conservadas 30 dias por predefinição e depois eliminadas automaticamente por uma tarefa cron diária. Pode reduzir esta duração em Definições → Privacidade. O IP do visitante e o user agent podem ou não ser registados, conforme a sua política.

O plugin propõe também uma opção Anonimizar os dados pessoais nos registos que mascara e-mails e números de telefone nos registos técnicos (logger do WooCommerce).

11. Compatibilidade com HPOS e com os blocos de checkout

O plugin declara oficialmente a compatibilidade com:

• HPOS (High-Performance Order Storage): todas as consultas de encomendas passam pelos CRUD oficiais do WooCommerce (wc_get_order, wc_get_orders), pelo que funcionam tanto nas tabelas antigas como nas tabelas HPOS
• Blocos Gutenberg de carrinho e checkout: sem qualquer interferência com os novos blocos de pagamento
• WordPress Multisite: ativação em rede suportada, opções delimitadas por site

12. Hooks e filtros para programadores

O plugin expõe vários hooks para personalizar o seu comportamento sem alterar o código-fonte.

Filtros disponíveis

// Alterar o system prompt antes do envio ao modelo
apply_filters('dfaics_system_prompt', $prompt, $context);

// Acrescentar ou retirar ferramentas dinamicamente
apply_filters('dfaics_tools_available', $tools, $conversation);

// Alterar o limiar de mensagens máximas antes do escalonamento forçado
apply_filters('dfaics_max_messages', 25, $conversation);

// Personalizar o conteúdo do e-mail de escalonamento
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Enriquecer os metadados do Slack
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Ações disponíveis

// Após a criação de uma conversa
do_action('dfaics_conversation_created', $conversation_id, $session);

// Após o envio de uma mensagem pelo agente
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Após um escalonamento
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Após a limpeza cron das conversas expiradas
do_action('dfaics_cleanup_done', $deleted_count);

Acrescentar uma ferramenta personalizada

Crie uma classe que estenda ToolBase e registe-a através do filtro dfaics_tools_available. O namespace é DataFireflyAiCustomerServiceAgentTools. Cada ferramenta declara o seu esquema JSON e a sua descrição, e implementa um método execute() que devolve um array associativo serializável.

13. Resolução de problemas

O widget não aparece

• Verifique que o widget está ativo em Definições → Widget → Ativar o widget
• Verifique a regra de apresentação condicional (páginas autorizadas)
• Abra a consola do navegador (F12) e procure erros de JS
• Limpe a cache se usar um plugin de cache (WP Rocket, W3 Total Cache…)

O agente não responde

• Verifique que a chave de API é válida através do botão Testar a chave
• Verifique o crédito ou a quota na conta da Anthropic ou da OpenAI
• Consulte os registos do WooCommerce em WooCommerce → Estado → Registos, origem df-ai-customer-service

O escalonamento para o Slack não chega

• Verifique o webhook através do botão Testar o webhook
• Regenere o webhook do lado do Slack, se for necessário
• Verifique que o canal de destino existe e que o bot tem acesso

Reinicializar por completo o plugin

Em Definições → Privacidade, assinale Eliminar todos os dados na desinstalação. Depois desative e desinstale o plugin: as 5 tabelas e as opções são eliminadas.

14. FAQ técnica

Posso mudar de fornecedor de IA sem perder as conversas?

Sim, a troca entre Claude e OpenAI é instantânea e não afeta o histórico. As novas conversas passam a usar o novo fornecedor.

O plugin funciona em modo headless?

A API REST do plugin (/wp-json/dfaics/v1/) pode ser usada a partir de qualquer front-end (Next.js, Vue, aplicação móvel). O widget nativo é em JavaScript puro e pode ser substituído pela sua própria implementação, que chama a mesma API.

É possível ligar o plugin ao Zendesk ou ao Freshdesk?

Não nativamente na 1.0.0: o escalonamento está limitado ao Slack e ao e-mail. Pode, no entanto, usar o hook dfaics_escalated para acionar a sua própria integração.

O agente aprende com as minhas conversas?

Não. Não é feito qualquer fine-tuning. O agente usa apenas o prompt de sistema, as ferramentas e o contexto da conversa em curso. Os seus dados não são usados para melhorar os modelos da Anthropic ou da OpenAI (os dois fornecedores oferecem uma opção de exclusão que está ativa por predefinição nas suas API profissionais).

15. Suporte

Para qualquer questão ou comunicação de erro, escreva para support at datafirefly.com indicando o seu número de licença. Respondemos em 48 horas úteis.