O que seu Agente de IA pode fazer durante uma conversa: as Quickchat AI Actions integradas e as ações personalizadas que chamam sua própria API, um servidor MCP ou um atalho como o Google Sheets.
Defina o que seu Agente de IA pode fazer durante a conversa: desde responder com dados de API em tempo real e captar leads até executar tarefas personalizadas.
Os Agentes Quickchat AI têm dois tipos de ação.
As Quickchat AI Actions já vêm integradas, basta ativá-las e configurá-las:
- Human Handoff passa a conversa para uma pessoa.
- Coleta inteligente de dados reúne leads e outras informações durante o chat.
As ações personalizadas vão além do Quickchat AI:
- As ações de API chamam qualquer endpoint HTTP. São descritas nesta página.
- As ações MCP conectam um servidor MCP inteiro de uma vez.
- O Google Sheets é um atalho que configura uma ação de registro para você com um clique.
Qualquer ação pode ler dados ao vivo da conversa por meio das AI Action Variables, e o exemplo do Jira constrói uma do início ao fim.
Ferramentas opcionais de configuração
Seção intitulada “Ferramentas opcionais de configuração”-
Verificar condições de execução de Ações. Avalie condições usando metadados de exemplo fornecidos, sem executar uma Ação.
-
Verificar uma conexão MCP de exemplo. Inicialize e liste ferramentas somente no endpoint da documentação Cloudflare ou do Microsoft Learn. Não faz login nem executa ferramentas.
Ações personalizadas
Seção intitulada “Ações personalizadas”As Ações personalizadas permitem que sua IA chame ferramentas externas durante uma conversa: consultar sistemas internos, criar tickets, acionar alertas ou buscar dados atualizados que não estão na Base de Conhecimento. Você as encontra em Ações & MCPs, na seção Ações Personalizadas.
Clique em + Adicionar ação para criar uma. O menu oferece:
- Ação API: chama qualquer endpoint REST por HTTP. É a opção mais geral; use-a para qualquer serviço que tenha uma URL e aceite JSON.
- MCP: conecta um servidor MCP externo com um clique e permite que a IA use as ferramentas que ele oferece. Veja Ações MCP.
- Ação HubSpot: conexão pronta com seu CRM HubSpot. Use-a para trabalhar com contatos, negócios e tickets, incluindo adicionar notas privadas a tickets, sem precisar gerenciar tokens de API.
- Ação Discord: instala templates editáveis de Ações de API para suporte e moderação. Exige seu próprio app do Discord. Veja Ações do Discord.
- Google Sheets: lê e escreve em uma planilha conectada.
- Shopify MCP: conecta uma loja Shopify pelo servidor Shopify Storefront MCP para que a IA possa pesquisar seu catálogo e as políticas da loja, ler detalhes dos produtos e montar um carrinho. Apenas uma ação Shopify MCP por cenário. Ela não permite consultar pedidos. Veja a observação abaixo.
Cada Agente de IA pode armazenar até 15 ações. Ações ativas e inativas contam para esse limite. Todos os planos permitem ativar as ações criadas sem um limite adicional de ações ativas por plano. Exclua uma ação que não seja mais necessária para liberar espaço; desativá-la não libera espaço.
O Shopify Storefront MCP atende aos clientes e não expõe dados de pedidos. Por isso, um Agente de IA conectado apenas por ele não pode consultar um pedido do cliente. O status do pedido vem de uma Ação de API separada, Check order status, que consulta a Shopify Admin API e é configurada automaticamente quando você instala o app Quickchat pela Shopify App Store. Lojas conectadas colando uma URL não têm acesso de administrador nem consulta de pedidos. Reinstale pela App Store se precisar desse recurso.
Como funcionam
Seção intitulada “Como funcionam”- Escolha um tipo de ação: Ação API, MCP, Ação HubSpot, Ação do Discord, Google Sheets ou Shopify MCP. Configure a conexão e as instruções de que a IA precisa.
- Durante uma conversa, a IA normalmente usa a descrição da ação e os detalhes disponíveis da ferramenta ou dos parâmetros para decidir quando executá-la. Como alternativa, uma Ação de API pode ser executada automaticamente antes da primeira resposta ou quando as condições de metadados corresponderem pela primeira vez.
- O Quickchat executa a chamada. A IA pode usar a resposta quando escolhe a Ação ou quando ela é executada antes da primeira resposta. Uma Ação acionada por metadados é executada silenciosamente, e seu resultado não é adicionado ao chat.
- Teste ou conecte a ação no editor antes de usá-la em conversas.
Escreva a descrição como uma instrução para a IA. Diga quando usar a ação, o que ela retorna e quais são os limites (por exemplo, “chame apenas quando o usuário fornecer um número de pedido”).
Criar rascunhos de Ações a partir de uma descrição
Seção intitulada “Criar rascunhos de Ações a partir de uma descrição”- Em Ações & MCPs, escolha + Adicionar ação > Ação API.
- Descreva o fluxo, quando o Agente deve agir, quais APIs usar (ou inclua links para a documentação delas) e as informações necessárias em cada etapa. Clique em Gerar.
- O Quickchat prepara até quatro rascunhos de novas Ações de API, todos inativos. O resultado pode recomendar Ações existentes em vez de criar duplicatas ou pedir mais detalhes. Gerar rascunhos não executa as Ações.
- Leia Ações existentes utilizadas, os pré-requisitos e Próximos passos. Conclua a configuração, substitua os valores provisórios e revise a requisição, as instruções e as condições de execução de cada Ação. Teste cada Ação antes de ativar os rascunhos ou qualquer Ação existente inativa necessária.
A sequência sugerida descreve o comportamento esperado. Ela não garante a ordem das Ações escolhidas pela IA. Use entradas obrigatórias, valores salvos na memória e condições de execução para definir dependências. Depois de ativar as Ações, teste o fluxo completo em uma conversa.
Criar uma Ação de API
Seção intitulada “Criar uma Ação de API”- Vá em Ações & MCPs.
- Clique em + Adicionar ação em Ações Personalizadas, escolha Ação API e clique em Criar manualmente.
- Preencha Details:
- Name: claro e descritivo
- Description: quando usar e o que incluir nos parâmetros
- Em Quando executar, escolha A AI decide, Antes da primeira resposta ou Quando os metadados correspondem.
- Configure Connection:
- Action Type: método HTTP (GET, POST etc.)
- Action endpoint URL: URL completa
- Headers: cabeçalhos necessários (
Authorization,content-type: application/jsonetc.)
- Defina Parameters: para cada parâmetro, name, location (query, body ou header) e description orientando a IA sobre como compor o valor. Valores de path não são uma location de parâmetro; insira‑os diretamente na URL do endpoint usando templates
{{placeholder}}. - Test request, valide e Done.
Qualquer campo de valor (URL, cabeçalho, body ou query) aceita placeholders dinâmicos pelo botão + Adicionar dados de IA. Você pode inserir seus parâmetros de IA, variáveis nativas da conversa ({{scenario_id}}, {{language}}, {{country}}, …) e metadados da conversa ({{metadata_*}}). Veja Variáveis de Ações de IA para consultar a referência completa.
Além da requisição em si, uma Ação de API tem três configurações opcionais que vale conhecer: Salvar na memória, Run only when e Response filter.
Visualize uma solicitação de Ação de API usando um modelo fornecido e valores sintéticos de exemplo. Omita cabeçalhos com credenciais. A pré-visualização monta a solicitação sem enviá-la.
Escolher valores padrão dos parâmetros
Seção intitulada “Escolher valores padrão dos parâmetros”Para uma Ação configurada como A AI decide, escolha Sem valor padrão quando a IA precisar obter um valor da conversa. Um parâmetro obrigatório sem valor padrão não pode enviar um valor em branco. Um valor padrão intencionalmente vazio é uma configuração diferente; os valores padrão vazios existentes continuam vazios. O editor também preserva os valores padrão numéricos 0 e booleanos false.
Para um parâmetro de texto ou número, abra Opções do valor padrão ao lado do campo do valor padrão e escolha Sem valor padrão ou Valor vazio. Você pode substituir um valor padrão vazio por outro valor. Para um parâmetro booleano, escolha Sem valor padrão no menu suspenso.
Escolher quando uma Ação de API é executada
Seção intitulada “Escolher quando uma Ação de API é executada”Use Quando executar para selecionar um de três modos:
A seção fica recolhida por padrão e mostra o modo ativo ao lado do título. Expanda-a para mudar de modo.

- A AI decide: o padrão. A IA lê a descrição da Ação e decide se a solicitação do visitante precisa dela. Use este modo quando a Ação deve ser executada apenas para determinadas perguntas ou depois que a IA coletar informações do visitante.
- Antes da primeira resposta: o Quickchat executa a Ação uma vez depois que o visitante envia a primeira mensagem e antes que a IA escreva a primeira resposta. A resposta normal da IA recebe a resposta da API e todos os valores salvos com Salvar na memória. A IA já não pode escolher esta Ação como ferramenta, por isso ela é executada apenas no primeiro turno e não novamente mais tarde na conversa. Use este modo para identificar clientes, obter o contexto da conta, verificar permissões ou realizar outras configurações iniciais necessárias em toda conversa real.
- Quando os metadados correspondem: o Quickchat verifica as condições de Executar quando da Ação após cada turno da IA e a executa na primeira vez em que todas forem atendidas. Os valores que outra Ação salva na memória durante esse turno ficam disponíveis imediatamente. A IA não pode escolher esta Ação como ferramenta, e sua resposta não é adicionada ao chat. Use este modo para notificações internas, atualizações de CRM ou solicitações de acompanhamento que devem acontecer automaticamente quando os dados da conversa estiverem disponíveis.
Antes da primeira resposta está vinculado à primeira mensagem do visitante, não à criação da conversa. Abrir um chat ou receber uma mensagem de boas-vindas não executa a Ação. Portanto, chats abandonados não fazem nenhuma solicitação. O Quickchat registra a execução antes de chamar o endpoint. Por isso, ela não é repetida na mesma conversa, mesmo que a solicitação falhe ou o resultado seja incerto.
A primeira resposta espera pela solicitação, então este modo pode aumentar a latência. Se várias Ações usarem este modo, elas serão executadas uma após a outra e os tempos das solicitações serão somados. Se os metadados obrigatórios estiverem ausentes, o endpoint estiver indisponível ou uma solicitação falhar, a IA ainda responderá. Abra o Registro de solicitações da Ação para ver o que aconteceu.
Como a Ação é executada antes que a IA possa escolher valores para os parâmetros, cada parâmetro da IA usado deve ter um valor padrão. Metadados e variáveis integradas podem ser inseridos diretamente na URL, nos cabeçalhos, na query ou no body.
Quando os metadados correspondem exige pelo menos uma condição em Executar quando e um valor padrão para cada parâmetro de IA. O Quickchat registra a tentativa antes de chamar o endpoint, por isso, depois que uma solicitação é enviada, a Ação não é repetida na mesma conversa, tenha ela funcionado, falhado ou terminado com resultado incerto. Uma solicitação que sequer pôde ser montada, porque falta um valor de que precisa, não é registrada e continua disponível para um turno posterior. A Ação é executada logo depois de a IA terminar seu turno, então uma falha nunca substitui a resposta da IA. Nos canais que não entregam a resposta em streaming, o tempo da solicitação se soma à espera do visitante.
Ao escolher Quando os metadados correspondem, o editor Executar quando aparece na mesma seção, mantendo o gatilho e as suas condições juntos.

Em canais que podem fornecer um endereço de e-mail ou um número de telefone, crie uma Ação de consulta para cada identificador. Configure ambas como Antes da primeira resposta e adicione a cada uma uma condição correspondente em Run only when, como visitor_email exists ou visitor_phone_number exists. O Quickchat envia apenas a solicitação cujos metadados estão presentes.
Webhooks de fim de conversa e transcrições
Seção intitulada “Webhooks de fim de conversa e transcrições”Uma Ação de API pode notificar seu webhook durante um chat. Em A AI decide, instruir a AI a chamá-la no encerramento é uma tentativa sem garantia de execução. Os modos padrão não garantem uma chamada quando a conversa termina, o visitante fica inativo ou uma aba do navegador é fechada.
Para obter uma transcrição exata, defina na integração o que determina o fim da conversa. Envie {{conversation_id}} ao seu backend e use um token de API autorizado com read_all para buscar todas as páginas de eventos da conversa, usando limit e offset. Monte a transcrição com os eventos de mensagem. Mantenha o token no backend.
Não existe uma variável integrada de transcrição. Um parâmetro de resumo ou transcrição gerado pela AI não garante uma cópia exata. Veja as variáveis de Ações de AI para saber qual contexto você pode enviar.
Ações do HubSpot
Seção intitulada “Ações do HubSpot”Ação HubSpot abre uma galeria de Ações de API pré-preenchidas e editáveis que usam sua conta conectada do HubSpot.

O template Adicionar nota ao ticket cria uma nota privada no ticket do HubSpot vinculado à conversa. Salve o conteúdo da nota na memória da conversa como hubspot_note_body; depois, adicione o template e ative-o. Ele vem configurado com Quando os metadados correspondem e aguarda até que hubspot_note_body e hubspot_ticket_id, fornecido pelo servidor do Quickchat, estejam presentes. Você pode editar o valor padrão do parâmetro note_body para adicionar texto fixo ao redor de {{metadata_hubspot_note_body}}.
A nota é interna ao HubSpot e não é exibida ao visitante. O template tenta fazer a solicitação uma vez por conversa do Quickchat. Abra o Registro de solicitações da Ação para confirmar a entrega ou investigar uma solicitação com falha.
Ações do Discord
Seção intitulada “Ações do Discord”Ação Discord abre uma galeria de Ações de API pré-preenchidas e editáveis:
- Suporte e tickets: Abrir ticket de suporte pede que você selecione um servidor e um canal de texto. Opcionalmente, você pode selecionar um cargo de suporte mencionável. Ela cria três Ações que abrem uma thread privada, adicionam o solicitante atual e publicam um resumo com a menção opcional ao cargo.
- Moderação: Timeout de membro, Expulsar membro, Banir membro, Desbanir membro, Atribuir cargo, Definir slowmode e Enviar anúncio. Cada template é instalado com um clique e usa o servidor, membro, cargo ou canal da solicitação atual do Discord.
O Quickchat cria no backend o método HTTP, a URL, os cabeçalhos, o corpo, os parâmetros, a descrição, as configurações de resposta e as condições de execução. Os cards resultantes são Ações comuns de requisição HTTP. Você pode inspecionar e editar todos os campos.
Os sete templates de moderação incluem author_is_admin is true em Executar somente quando. O Discord calcula a permissão Administrator do autor atual, o gateway do Discord fornece esse valor e o Quickchat o verifica antes de enviar a solicitação. O chat público e os metadados da API não podem definir essa chave. Teste as Ações de moderação no Discord com uma conta de administrador e outra sem esse acesso; o AI Preview não fornece um remetente autorizado do Discord.
As Ações de moderação são editáveis. Remover ou enfraquecer a condição author_is_admin is true remove a barreira de autorização fornecida. Expulsar membro e Banir membro não pedem confirmação antes da execução.
Os templates não adicionam nenhuma automação própria. O Agente só os executa quando um administrador pede na conversa; não há contagem de strikes entre conversas, nem verificação de capturas de tela ou outras provas, nem sanções agendadas ou iniciadas por conta própria.
O próprio bot ainda precisa da permissão do Discord exigida por cada solicitação:
| Ação | Permissão ou acesso do bot |
|---|---|
| Timeout de membro | Moderate Members |
| Expulsar membro | Kick Members |
| Banir membro, Desbanir membro | Ban Members |
| Atribuir cargo | Manage Roles |
| Definir slowmode | Manage Channels |
| Enviar anúncio | View Channels e Send Messages |
O Discord também aplica a hierarquia de cargos. Posicione o cargo do bot acima dos membros e cargos que ele deve gerenciar. O template não realiza uma verificação adicional de hierarquia ou de permissões específicas para o administrador solicitante.
Definir slowmode e Enviar anúncio aceitam um parâmetro de ID de canal. Sem um destino fixo adicional, o template não verifica se o canal pertence ao servidor em que o administrador enviou a solicitação. Se o mesmo bot pertencer a vários servidores, edite essas Ações para usar um ID de canal fixo ou separe os servidores entre Agents e credenciais de bot diferentes.
A instalação de Suporte e tickets usa os recursos existentes das Ações para transferir dados:
open_support_ticketcria uma thread privada no canal selecionado, captura$.ide o salva na memória da conversa comodiscord_ticket_thread_id. Ela exigediscord_message is true, é executada apenas no servidor selecionado e somente enquanto essa chave de memória não existir.add_ticket_requesterlê{{metadata_discord_ticket_thread_id}}e o valor{{metadata_discord_author_id}}fornecido pelo Discord. Ela exigediscord_message is truee é executada apenas no servidor selecionado depois que o ID da thread existir.post_in_ticketlê o mesmo ID de thread salvo, publica o resumo de uma linha do Agent sobre o problema e menciona o solicitante. Se você selecionou um cargo de suporte, ela também menciona esse cargo. Ela tem as mesmas condições de mensagem do Discord, servidor e thread salva. O corpoallowed_mentionsdo Discord é limitado ao solicitante e, quando houver um cargo configurado, a esse cargo.
As descrições e o prompt do seu Agent devem instruí-lo a executar essas Ações nessa ordem. Não há uma camada separada de estado, bloqueio, confirmação, nova tentativa, recuperação, reconciliação ou proteção contra replays para o fluxo. Se o resultado for incerto, verifique o Discord e o log da Ação antes de tentar novamente, porque o Discord pode já ter concluído a solicitação.
discord_ticket_thread_id não é apagado automaticamente. Portanto, o template aceita um ticket por conversa do Quickchat. Para outro ticket, inicie uma nova conversa ou thread no Discord, ou edite as Ações para adicionar o ciclo de vida da memória de que você precisa.
Para Suporte e tickets, conceda ao bot View Channels, Send Messages, Read Message History, Create Private Threads, Send Messages in Threads e Manage Threads no canal de tickets selecionado. Mantenha Avisar uma função (opcional) como Não avisar nenhuma função se você não quiser mencionar nenhum cargo. Se você selecionar um cargo, ele deverá ser mencionável, e seus membros precisarão de acesso às threads privadas. Sem um cargo selecionado ou quando não houver cargos mencionáveis disponíveis, os tickets continuarão sendo abertos normalmente sem notificar um cargo. A galeria lista canais de texto e cargos mencionáveis, mas não valida todas as substituições de permissões do canal.
As Ações do Discord precisam do token do seu próprio app do Discord em Aplicativos externos → Discord → Configuração avançada. O bot compartilhado de um clique não consegue fornecer esse token sozinho. Consulte Discord.
A galeria é um atalho de configuração, não uma camada adicional de policy. Se você editar uma Ação gerada ou criar uma Ação de API personalizada do Discord, revise suas credenciais, destinos, parâmetros, exposição da resposta e condições de Executar somente quando antes de ativá-la.
Salvar na memória
Seção intitulada “Salvar na memória”Salve um valor de uma entrada da Ação ou da resposta da API na memória da conversa sob uma chave que você escolher. Ações posteriores podem reutilizá-lo como {{metadata_<key>}}, e ele aparece nos detalhes da conversa (Caixa de entrada, API e exportações).
Recorra a isso quando uma Ação produz algo de que uma Ação posterior precisa. Uma Ação de consulta pode salvar um customer_id da sua resposta; uma Ação seguinte então envia {{metadata_customer_id}} sem que a IA precise copiar o valor de uma para a outra.
No editor de Ação de API, abra Salvar na memória e adicione uma linha:
- Escolha uma Origem. Resposta da API lê a resposta JSON da API e é a opção padrão para novas linhas. Entrada da ação lê os valores dos parâmetros de entrada declarados na Ação.
- Em Valor a salvar, selecione o parâmetro no menu suspenso para Entrada da ação. Para Resposta da API, insira uma Expressão JSONPath, como
$.customer_id. - Escolha uma Chave de memória. Nomes comuns de entradas em inglês para nome, telefone e e-mail sugerem a chave de visitante correspondente. Você pode manter a sugestão ou inserir sua própria chave.
Para salvar dados de contato na Caixa de entrada, use Entrada da ação com estes mapeamentos:
| Parâmetro da Action | Chave de memória |
|---|---|
Name ou Full name | visitor_name |
Phone number ou Phone | visitor_phone_number |
Email ou Email address | visitor_email |
A entrada precisa estar declarada na Ação. Salvar essa entrada por meio de uma regra de memória Entrada da ação conta como uso do parâmetro, portanto ela pode ser coletada para a memória sem ser enviada na requisição HTTP. Essas chaves de visitante preenchem campos de contato ainda não definidos na Caixa de entrada e os metadados da conversa, usando a mesma validação da Coleta inteligente de dados. Os dados de contato existentes e os campos apagados explicitamente por um operador são preservados. Regras de resposta da API não podem gravar nessas chaves de visitante; use uma chave personalizada, como customer_id, para valores da resposta de um CRM.
As entradas são salvas depois que a Ação passa pelas verificações de entradas obrigatórias e condições de execução, antes da requisição HTTP. Assim, os dados de contato válidos continuam disponíveis se a API retornar um erro ou exceder o tempo limite. Para verificá-los, execute a Ação em uma nova conversa de Pré-visualização e abra essa conversa na Caixa de entrada. O teste isolado da API no editor não tem uma conversa em que salvar a memória.
As chaves de memória são compartilhadas com as ferramentas Remote MCP do agente. Se uma ferramenta MCP já salva na mesma chave, o campo Chave de memória avisa sobre o conflito ao salvar, então escolha outra chave. As ferramentas Remote MCP continuam salvando valores dos seus resultados.
Use chaves em snake_case (letras, dígitos, underscores). Uma chave como customer_id é referenciável como {{metadata_customer_id}}; chaves com espaços ou outra pontuação não podem ser usadas em placeholders. Veja Metadados de conversa para entender como funcionam as variáveis de metadados.
Run only when
Seção intitulada “Run only when”Restrinja uma Ação para que ela rode apenas quando condições sobre os metadados da conversa forem verdadeiras. As condições são sempre verificadas do nosso lado, fora do modelo. Com A AI decide ou Antes da primeira resposta, o Quickchat as verifica imediatamente antes de enviar a solicitação. Com Quando os metadados correspondem, as próprias condições acionam a solicitação após um turno da IA, sem esperar que a IA escolha a Ação.
Esta é a ferramenta certa para Ações privilegiadas ou irreversíveis (banir um membro, emitir um reembolso, excluir um registro). Uma linha no seu prompt dizendo “apenas administradores podem fazer isso” é uma instrução útil, mas não é uma fronteira de segurança: um usuário determinado pode discutir com o modelo ou tentar uma injeção de prompt. Uma condição de execução é determinística e vive fora do prompt, então ela se mantém independentemente do que a conversa diga.
- A condição de execução é a fronteira. Ela é avaliada no servidor e não faz parte do prompt que o modelo lê. É isso que realmente impede a Ação de rodar.
- A regra no prompt é a experiência do usuário. Mantenha uma linha no seu prompt também, para que a IA recuse educadamente e explique o porquê em vez de ficar em silêncio.
Adicione condições na seção Executar somente quando do editor de Ação. Esta seção recebe o nome Executar quando em uma Ação configurada como Quando os metadados correspondem. Clique em Adicionar condição, escolha uma chave de metadados (por exemplo telegram_sender_is_admin) e escolha como compará-la:
| Condição | Passa quando o valor do metadado… |
|---|---|
| é verdadeiro | é verdadeiro (truthy) |
| é falso | é falso (falsy) |
| existe | está presente na conversa |
| não existe | está ausente |
| é igual a | corresponde a um valor que você especifica |
| não é igual a | difere de um valor que você especifica |
| é um de | corresponde exatamente a um dos valores da lista, respeitando maiúsculas, minúsculas e espaços |
| contém texto | é texto que contém o texto literal especificado, diferenciando maiúsculas de minúsculas |
A Ação roda apenas quando todas as condições forem verdadeiras. O editor mostra E entre as linhas. Quando uma condição bloqueia uma Ação escolhida pela IA, ela pode explicar que a Ação não está disponível. Uma Ação configurada como Quando os metadados correspondem permanece silenciosa até que suas condições sejam atendidas.
Use é um de para definir alternativas para a mesma chave, inserindo cada uma em um chip de valor separado. Por exemplo, modelName is one of [K-65XR95M2, K-75XR95M2, K-85XR95M2] pode ser combinado com country equals UK; as duas linhas precisam corresponder. Você pode adicionar até 50 alternativas com até 500 caracteres cada. As vírgulas são partes literais de um valor. Linhas é igual a separadas com valores diferentes para a mesma chave não podem corresponder ao mesmo tempo.
contém texto verifica um trecho literal, sem curingas nem expressões regulares. XR95M2 também corresponde a outras variantes de nomes de modelos além das três listadas acima. As duas novas condições rejeitam chaves ausentes, null, listas e objetos; contém texto também rejeita números e booleanos. O texto de comparação não pode estar vazio. As condições existentes é falso, não é igual a e não existe podem corresponder a chaves ausentes.

Quando uma condição falha, nenhuma requisição é enviada e a IA informa ao usuário que não pode fazer aquilo. Abaixo, a mesma solicitação de banimento é bloqueada para um não administrador e permitida para um administrador, sem nada mudar além de quem está pedindo:


Use como filtro apenas metadados que o Quickchat define (como uma flag telegram_sender_is_admin verificada pelo canal), não valores que o visitante pode influenciar. Veja Metadados de conversa para saber de onde vem cada chave.
Response filter
Seção intitulada “Response filter”Por padrão, a IA vê a resposta completa da API. Adicione expressões JSONPath na seção Response filter para limitar a IA a partes específicas dela.
Duas razões comuns para filtrar:
- Ocultar campos sensíveis. Mantenha e-mails de clientes, detalhes de pagamento ou IDs internos fora do contexto do modelo quando o endpoint retorna mais do que a IA precisa.
- Reduzir o prompt. APIs verbosas podem retornar payloads grandes; filtrar para os poucos campos que importam mantém a resposta pequena e a IA focada.
Adicione uma ou mais expressões JSONPath. O filtro mantém os campos selecionados dentro dos objetos e arrays que os contêm, em vez de transformá-los em uma lista plana de valores. Os campos fora dos caminhos selecionados são omitidos. Por exemplo, use estas duas linhas:
$.customer.name$.orders[*].id
Para esta resposta da API:
{ "customer": {"name": "Ada", "email": "ada@example.com"}, "orders": [{"id": 101, "total": 25}, {"id": 102, "total": 40}]}A IA recebe esta resposta filtrada, em que customer continua sendo um objeto e orders um array de objetos:
{ "customer": {"name": "Ada"}, "orders": [{"id": 101}, {"id": 102}]}Use o painel Test Response para ver exatamente o que a IA receberá após o filtro antes de depender dele. Veja Testando sua Action.
Um JSONPath que não corresponde a nada deixa a IA com uma resposta vazia. Comece sem filtro, confirme que a chamada funciona e depois refine.

Visualize correspondências JSONPath em uma resposta JSON fornecida. A pré-visualização aceita caminhos de raiz, campo, índice de array e curinga para regras de Response filter ou Salvar na memória.
Verifique o estado e os registros das Ações
Seção intitulada “Verifique o estado e os registros das Ações”Um aviso ao lado de Ações & MCPs na barra lateral indica que uma Ação precisa de atenção. Abra a página e passe o cursor sobre o indicador no cartão da Ação ou navegue até ele com o teclado para saber o motivo:
- Com falhas: chamadas recentes falharam repetidamente. O indicador mostra a quantidade de falhas e o erro mais recente, quando disponível.
- Não executada: a Ação foi ignorada repetidamente, sem nenhuma chamada executada no período de avaliação atual. Verifique o motivo informado, como valores ausentes na conversa ou um problema de configuração.
- Reconexão necessária: uma conexão MCP perdeu a autorização e foi desativada. Abra Editar, reconecte-a e ative-a novamente.
A avaliação considera conversas reais dos últimos sete dias ou desde a última edição da Ação, se ela for mais recente. As solicitações de teste não entram nessa avaliação. Depois de corrigir e salvar uma Ação, verifique novas conversas para confirmar a correção; o desaparecimento de um aviso antigo, por si só, não comprova que ela funciona.
Para Com falhas ou Não executada, clique em Ver detalhes para abrir o Registro de solicitações com Apenas problemas ativado. Ver registros abre o registro com todas as chamadas. Desative Apenas problemas para comparar chamadas com problemas e chamadas bem-sucedidas.
Conversas ignoradas lista as conversas em que a Ação não pôde rodar, separadamente das chamadas que foram executadas. Use Ver conversa para inspecionar o contexto e Mostrar mais para carregar entradas anteriores. Uma Ação pode rodar com sucesso em algumas conversas e ser ignorada em outras, então essa lista pode aparecer mesmo sem um indicador de aviso.
Quando o motivo indicar valores ausentes, como {{metadata_visitor_email}}, forneça-os pelos metadados do seu site ou canal, ou faça uma Ação anterior salvá-los na memória. Depois, verifique o modo de execução:
- A AI decide: a Ação só é oferecida à IA em conversas que já têm os valores obrigatórios.
- Antes da primeira resposta: os valores precisam estar presentes quando o visitante envia a primeira mensagem.
- Quando os metadados correspondem: adicione uma condição existe para cada valor obrigatório, para que a Ação espere até ele estar disponível.
Veja Variáveis de Ações de IA para saber de onde vêm os valores da conversa.
Os e-mails de resumo de atividades também incluem uma seção AI Actions need attention quando uma Ação HTTP ou de MCP remoto precisa de atenção. Ela lista até cinco Ações, com um motivo e um link para Ações & MCPs; um contador indica quantas outras precisam de atenção. A seção não aparece quando está tudo funcionando corretamente.
O e-mail mostra o estado atual, cuja avaliação pode abranger um período maior do que a janela de atividade do resumo diário. Depois de corrigir e salvar uma Ação de API, a avaliação do estado passa a considerar o período a partir dessa edição. Reconectar ou desconectar uma conexão MCP afetada remove seu aviso de autorização. As preferências e as regras de elegibilidade existentes para os e-mails de resumo continuam valendo, e nenhum e-mail de alerta separado é enviado.
Boas práticas
Seção intitulada “Boas práticas”- Seja explícito nas descrições. Diga à IA quando usar a ação e o que cada parâmetro deve conter.
- Mantenha o escopo mínimo. Inclua apenas os cabeçalhos e tokens de que o endpoint precisa. Para o Jira, use o cabeçalho Basic derivado do seu e-mail da Atlassian e do token de API.
- Teste antes do lançamento usando o painel Test request. Confirme que os códigos de status e os payloads de exemplo estão corretos na ferramenta de destino.
Tutoriais
Seção intitulada “Tutoriais”- Conectar um Agente de IA aos tickets do Jira (referência principal) ou o passo a passo narrado no blog
- Enviar notificação no Slack com Ação de IA