Um assistente que lê o preço e a disponibilidade na sua loja no segundo em que o cliente pergunta.
Ligamos o assistente ao catálogo da loja através da sua porta pública, colocamo-lo nos canais onde os clientes já escrevem e damos-lhe uma regra que não pode violar: não diz um preço que não esteja publicado na loja. Quando ultrapassa o papel, entrega a conversa a uma pessoa, com registo.
Já construídoSe poate verifica din exterior, fără să ne întrebi pe noi. Punctul nostru de catalog livrat unui distribuitor răspunde 200 și spune „154 rezultate”, iar interfața publică a magazinului lui, interogată direct, întoarce antetul `x-wp-total: 154` — aceeași cifră, două surse independente, 06.09.2026. A doua implementare e funcția de catalog din platforma de asistenți: `storeCatalog.service.js` plus trei unelte încorporate pe care agentul le poate chema în timpul conversației. Rezerva pe care o spunem înainte de contract: mesajele din șablon WhatsApp nu există în codul platformei, deci nu promitem niciun mesaj proactiv în afara ferestrei de 24 de ore; iar traseul de catalog stă pe o ramură de dezvoltare care nu e unificată în trunchi — e livrat pentru magazinele pe care le-am conectat, nu pornit implicit pentru toți.
Um assistente de loja não falha porque não entende a pergunta. Falha porque responde a partir de uma cópia do catálogo. Alguém exportou os produtos uma vez, colou-os num ficheiro, e desde então o assistente lê uma fotografia antiga da loja: o preço de há três semanas, o stock de antes do fim de semana. Funciona na perfeição até à primeira alteração de preço e até ao primeiro produto esgotado — e então erra com convicção, o que é pior do que ficar calado. No comércio, isto não é um erro de nuance: o cliente vem à loja com o preço que o bot lhe disse.
A nossa escolha é simples e tem consequências: o catálogo não se copia, lê-se. Para lojas em WooCommerce, a Store API é pública — por isso a ligação é feita com o endereço do site, sem chave de consumidor e sem segredo. Quando o cliente pergunta por um produto, o agente chama uma ferramenta, a ferramenta pergunta à loja, a loja responde com o preço e a disponibilidade atuais. O que aparece na conversa é o que está na loja, não o que existia quando a integração foi feita.
O custo desta escolha é visível no código, não está escondido: o catálogo é carregado paginado, até trinta páginas de cem produtos cada, é mantido numa memória temporária de dez minutos por site e é normalizado numa única forma, lida sem alterações por todos os consumidores — incluindo o carrossel de produtos na mensageria, que precisa de preço numérico, e o widget na página. Dez minutos é o compromisso: uma alteração de preço feita agora vê-se no máximo em dez minutos, não instantaneamente. Dizemos o número, para que o possa contestar.
O resto das limitações não vem de nós, mas dos canais, e é mais honesto conhecê-las antes: a Meta recusa texto livre fora da janela de 24 horas desde a última mensagem do cliente, o Instagram não tem carrosséis de produtos, e uma foto enviada pelo cliente é marcada na conversa, não é anexada automaticamente a uma encomenda. Cada uma destas frases é citada abaixo com ficheiro e linha.
Qué incluye
O que muda concretamente no comércio online
A pergunta torna-se uma pesquisa no seu catálogo, não um palpite
O agente tem três ferramentas incorporadas sobre um serviço comum de catálogo: `store_catalog_search` para pesquisa, `store_catalog_match` para correspondência de uma formulação do cliente com um produto específico, `store_catalog_product` para a ficha completa. Não são ferramentas escritas separadamente para cada loja — são função da plataforma. A diferença prática: quando corrigimos algo na correspondência, é corrigido para todas as lojas ligadas de uma vez.
O preço e o stock são lidos da loja no momento da pergunta
O resultado da ferramenta vem da sua loja, não de um ficheiro nosso. A memória temporária é de dez minutos por site, e o catálogo é percorrido paginado — até 30 páginas de 100 produtos cada. A consequência que tem de aceitar: uma alteração de preço aparece na conversa com um atraso de no máximo dez minutos. A consequência que ganha: não existe o cenário em que o agente repete durante meses um preço retirado da loja.
A resposta sai no canal onde o cliente escreveu
Seis canais têm código próprio na plataforma: Messenger, Instagram Direct, Telegram, o widget na página, uma plataforma local de anúncios e WhatsApp através da Cloud API no Graph v22.0. Não é um único «chat» renomeado seis vezes: cada canal tem as suas próprias regras de formato e os seus próprios modos de falhar, e nós verificamos também o caso feio — um token de página expirado pára o canal em silêncio se não for monitorizado.
A ligação da loja em WooCommerce é feita com o seu endereço, sem chaves
A Store API é pública, por isso não lhe pedimos `consumer_key` e `consumer_secret`. Não é uma comodidade, é uma decisão de risco: as ferramentas escritas manualmente que este percurso substituiu guardavam, algumas delas, chaves de loja escritas em claro na base de dados. O novo percurso substituiu 109 ferramentas escritas manualmente, das quais 28 eram scrapers sobre HTML — ou seja, integrações que se quebravam à primeira alteração do tema da loja.
O carrossel de produtos tem condições, e elas diferem de canal para canal
No Messenger, o carrossel é exibido apenas quando três condições são cumpridas em simultâneo; se uma faltar, a resposta mantém-se em texto, não falha. No Instagram não existe carrossel de produtos — a Meta não tem modelos genéricos no Instagram, portanto ninguém pode entregar isso lá, independentemente do que esteja escrito na oferta. É o tipo de frase que preferimos que ouça de nós antes do contrato.
A janela de 24 de horas no WhatsApp, dita com o número do erro
Fora da janela de 24 horas desde a última mensagem do cliente, a Meta rejeita o texto livre com o erro 131047, e a mensagem fica marcada como falhada na plataforma. As mensagens de modelo — a única forma legítima de escrever primeiro após a janela — não existem no código da plataforma: uma pesquisa pelo tipo `template` devolve zero resultados, apenas é enviado o tipo `text`. Portanto: recuperação de carrinho abandonado no WhatsApp após 48 horas não lhe podemos prometer hoje.
As rajadas de mensagens e as mensagens duplicadas são tratadas, não ignoradas
O webhook da Meta de facto reenvi a mesma mensagem: a deduplicação é feita pelo identificador da mensagem, com 120 segundos de memória. E o cliente que escreve «olá», «têm», «o modelo preto» em três linhas recebe uma única resposta para tudo o que escreveu, não três respostas parciais — as mensagens são acumuladas num tampão de 15 segundos. No comércio, isto conta mais do que parece: três respostas parciais a uma única intenção parecem exatamente um robot.
A passagem para humano tem estado, não é uma promessa
O fio de conversa tem estado explícito `bot` ou `human`. O registo de passagem conhece três ações: passagem para um humano, retorno ao bot, reativação automática. Separadamente, o fio tem estado de cumprimento do tempo de resposta — `ok`, `warning`, `breached` — por isso vê-se qual conversa ficou sem resposta humana, não apenas quantas houve.
O que um assistente de loja não resolve
Não processa o pagamento. Não cria a encomenda na loja se a loja não tiver um canal de escrita — a leitura é pública, a escrita não. Não anexa a foto enviada pelo cliente a uma encomenda: a fotografia recebida é marcada na conversa, e só isso, e a geração de PDF não existe na plataforma. E não repete a encomenda anterior de um cliente sem acesso autorizado ao seu histórico. Cada uma destas coisas pode ser construída, mas como trabalho separado, não como item assinalado na proposta.
Traseul
Como um pedido passa pelo sistema.
01
Primeiro verificamos que porta pública a sua loja tem
A primeira verificação, não a última: pedimos o catálogo do exterior e contamos o que volta. Se a loja estiver em WooCommerce com a Store API ativa, a integração não precisa de chaves. Se não, passamos para a autenticação — e então a chave torna-se uma peça que se administra, com tudo o que isso implica. Entregamos o resultado desta verificação por escrito, incluindo quando a resposta é que não é possível.
02
Ligamos o catálogo e os canais, com o caso feio testado
A ligação à Meta é feita através de Embedded Signup. Em cada canal verificamos não só a primeira mensagem bem-sucedida, mas também o que acontece quando o token expira ou quando a loja não responde. Entregamos os canais ligados e a lista escrita do comportamento em cada modo de falha.
03
Escrevemos a função, as ferramentas e o limite
Cada ferramenta tem descrição escrita para o modelo, parâmetros tipados e prazo próprio de execução — por defeito 15 segundos. A função do agente diz explicitamente o que ele não pode afirmar: preço não publicado, prazo de entrega, disponibilidade que não leu. Entregamos a configuração do agente e a lista de ferramentas associadas a ele — não todas as ferramentas da plataforma, apenas as de que ele precisa.
04
Ativamos a passagem humana e ajustamos os limiares
Começamos com a passagem para humano configurada e com o registo de consultas ativo, para que se veja que fragmentos o agente usou e com que pontuações. A partir daí, ajusta-se o limiar de semelhança e o número de fragmentos por pergunta. Entregamos um relatório de conversas com as decisões de ajuste, não apenas um assistente ativo.
Traseul, în 5 pași
Os dados
Qué tocamos, dónde están y cuánto se quedan
As regras diferem de indústria para indústria. Estas são as que se aplicam ao comércio online.
O catálogo não é copiado para nós
Os produtos, os preços e o stock ficam consigo. O que passa pela plataforma é a resposta a uma pergunta, guardada em memória temporária durante dez minutos. Não existe connosco uma base com o seu catálogo que alguém possa exportar, porque não há nenhum export para fazer.
Onde ficam as conversas
MySQL, no servidor próprio em Microsoft Azure. O esquema tem mais de 80 tabelas modeladas em Prisma, com tabelas separadas para os threads do Meta, os threads do Telegram, os threads da plataforma de anúncios, comentários, etiquetas, notas internas e registo de auditoria. O token do canal é guardado encriptado com Fernet.
Os dados da encomenda entram em campo livre
Numa conversa de loja entram nome, telefone, morada de entrega e, por vezes, o tamanho ou o problema médico para o qual o cliente compra o produto. Tecnicamente, não se pode impedir. Pode-se tratar: define-se o que se guarda, por quanto tempo, quem tem acesso e o que a equipa foi instruída a não pedir no canal. O registo de tratamentos da implementação é escrito na implementação, não depois.
O widget na página e a lista de origens
O widget tem uma lista de origens permitidas por assistente, mas o comportamento predefinido deve ser conhecido: se a lista estiver vazia, a verificação passa. É uma escolha de compatibilidade com instalações antigas, escrita assim no código. Na prática, a restrição ao domínio da sua loja configura-se explicitamente em cada implementação — não vem pré-definida.
Prazo de retenção
Define-se por implementação e escreve-se na política publicada por si. A regra que aplicamos connosco e que pedimos também nos projetos: se uma alteração de código mudar o que é recolhido, a quem chega ou quanto tempo é guardado, a política publicada é alterada no mesmo commit.
Un caso
Um catálogo de 154 produtos, verificado de dois lados
A situação
Um distribuidor de Chișinău vendia através de uma loja WooCommerce e respondia a perguntas sobre produtos em canais de mensagens. A integração óbvia — um export de produtos colocado na base de conhecimentos do agente — teria funcionado até à primeira campanha de descontos.
Qué construimos
Ligámos o catálogo pela interface pública da loja, que não pede chaves, e colocámos por cima três ferramentas que o agente chama na conversa: pesquisa, correspondência e ficha de produto. Os resultados são normalizados numa forma única, lida da mesma maneira pelo carrossel na mensageria e pelo widget na página, para não existirem duas verdades sobre o mesmo preço.
Qué salió
A verificação pode ser feita externamente, sem terem de acreditar na nossa palavra: o nosso ponto de catálogo responde 200 e reporta 154 resultados, e a interface pública da loja, consultada diretamente, devolve o cabeçalho `x-wp-total: 154`. O mesmo número, duas fontes independentes, no mesmo dia.
Qué no dice el caso
O número é desse dia, 06.09.2026, e muda quando o distribuidor adiciona produtos — essa é a ideia. Não é uma medição de desempenho e não diz nada sobre vendas; diz apenas que o agente lê o catálogo real.
Perguntas
O que alguém no comércio online pergunta
Como sei que não está a dizer um preço antigo?
Porque não tem de onde o tirar. O preço vem da resposta da sua loja no momento da pergunta, guardado em memória temporária por no máximo dez minutos. Não existe connosco uma cópia do catálogo da qual possa ler. Pode fazer a verificação sozinho: pergunta ao agente por um produto, altera o preço na loja, espera dez minutos e pergunta de novo.
O que responde quando o produto está esgotado?
O que a loja diz. A disponibilidade vem da mesma resposta que o preço. O que não faz — e é uma decisão, não uma falha — é inventar uma data de reposição. Se quiser que o agente proponha alternativas quando um produto falta, essa é uma regra que escrevemos explicitamente no seu papel e testamos, não algo que acontece por si.
Pode finalizar a encomenda?
Não a partir da leitura do catálogo. A Store API pública é uma porta de leitura; a escrita de uma encomenda exige um caminho autenticado para a loja, portanto um trabalho separado, com chaves que são administradas. O que faz hoje: leva o cliente até ao produto certo, com o preço certo, e dá-lhe a ligação ou entrega a conversa a uma pessoa.
Pode ele escrever primeiro a um cliente que abandonou o carrinho?
No WhatsApp, não, fora da janela de 24 horas. A Meta rejeita texto livre com o erro 131047, e as mensagens de template não existem no código da plataforma. No Telegram e no Messenger, dentro dos limites das regras de cada canal, existem automatizações agendadas que retomam as conversas sem resposta, com contadores visíveis de quantas partiram e quantas foram ignoradas.
Funciona com carrossel de produtos no Instagram?
Não. A Meta não tem templates genéricos no Instagram, por isso o carrossel não existe lá para ninguém. No Messenger existe, mas exige três condições em simultâneo; quando uma falta, a resposta mantém-se em texto. Preferimos que ouça isto agora, e não na terceira semana de implementação.
A minha loja não está em WooCommerce. O que muda?
Muda a primeira etapa: em vez de ligarmos o endereço, verificamos que interface pública a sua plataforma tem e se responde depressa o suficiente para uma conversa. Se não tiver nenhuma, ou escrevemos um conector autenticado — e então discutimos quem administra a chave — ou dizemos que não se pode fazer honestamente um catálogo vivo e ficamos com uma base de conhecimento atualizada periodicamente, assinalada como tal.
O cliente envia a foto do produto que quer. O que acontece?
A fotografia é marcada na conversa e fica ali para a pessoa que assumir. Não é anexada automaticamente a uma encomenda e não é gerado nenhum documento a partir dela — não existe código para isso. Um agente que afirmasse ter registado a encomenda a partir da foto estaria a mentir, e isso descobre-se na entrega.
O que acontece quando o cliente escreve quatro mensagens seguidas?
Recebe uma única resposta, a tudo o que escreveu. As mensagens são reunidas num buffer de 15 segundos antes de serem enviadas ao modelo. Separadamente, se a plataforma Meta reenviar a mesma mensagem — e fá-lo —, a deduplicação pelo identificador da mensagem, com 120 segundos de memória, impede a segunda resposta.
Quem responde quando o agente não sabe?
Uma pessoa da sua equipa, e a passagem vê-se no sistema: o fio passa do estado `bot` para `human`, o registo de transferência nota quem e quando, e o estado de cumprimento do tempo de resposta mostra se o fio ficou pendurado. Sem esse mecanismo, “passa a um operador” é uma promessa que ninguém pode verificar meses mais tarde.