Ações

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.

Ações personalizadas

Permitem que sua IA chame APIs externas durante a conversa. Use para buscar ferramentas internas, criar tickets, acionar alertas ou obter dados atualizados fora da Base de Conhecimento. Estão em Actions & MCPs → Custom Actions.

Como funcionam

1. 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.
2. 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 configurada para ser executada automaticamente antes da primeira resposta.
3. O Quickchat executa a chamada e retorna o resultado à IA. A IA lê a resposta e responde ao usuário em linguagem natural.
4. Teste ou conecte a ação no editor antes de usá-la em conversas.

Dica

Escreva a descrição como instrução para a IA: quando usar, o que retorna e limites.

Criar uma Ação de API

1. Vá em Actions & MCPs.
2. Clique em + em Custom Actions e escolha API Action.
3. Preencha Details:
   • Name: claro e descritivo
   • Description: quando usar e o que incluir nos parâmetros
4. Em Quando executar, escolha A AI decide ou Antes da primeira resposta.
5. Configure Connection:
   • Action Type: GET ou POST
   • Action endpoint URL: URL completa
   • Headers: cabeçalhos necessários (Authorization, content-type: application/json etc.)
6. 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}}.
7. Test request, valide e Done.

Além da requisição em si, uma Ação de API tem três configurações opcionais que vale conhecer: Save to memory, Run only when e Response filter.

Escolher quando uma Ação de API é executada

Use Quando executar para selecionar um de dois modos:

• 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 Save to memory. 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.

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.

Identificar por e-mail ou telefone

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.

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.

Cuidado

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.

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:

1. open_support_ticket cria uma thread privada no canal selecionado, captura $.id e o salva na memória da conversa como discord_ticket_thread_id. Ela exige discord_message is true, é executada apenas no servidor selecionado e somente enquanto essa chave de memória não existir.
2. add_ticket_requester lê {{metadata_discord_ticket_thread_id}} e o valor {{metadata_discord_author_id}} fornecido pelo Discord. Ela exige discord_message is true e é executada apenas no servidor selecionado depois que o ID da thread existir.
3. post_in_ticket lê 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 corpo allowed_mentions do 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.

Cuidado

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.

Save to memory

Capture um valor da resposta da API e armazene-o 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, a 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.

Na seção Save to memory do editor de Ação de API, dê à valor capturado uma memory key e aponte-a para a parte da resposta que você quer manter. A partir daí, ela é uma variável de metadados como qualquer outra.

As memory keys são compartilhadas com as ferramentas Remote MCP do agente. Se uma ferramenta MCP já salva na mesma chave, o campo memory key avisa sobre o conflito ao salvar, então escolha outra chave.

Dica

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

Restrinja uma Ação para que ela rode apenas quando condições sobre os metadados da conversa forem verdadeiras. As condições são verificadas do nosso lado, no momento da chamada, depois que a IA decidiu chamar a Ação mas antes que qualquer requisição seja enviada, de modo que não há como contorná-las pela conversa.

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 Run only when do editor de Ação. Clique em Add condition, escolha uma chave de metadados (por exemplo telegram_sender_is_admin) e escolha como compará-la:

Condição	Passa quando o valor do metadado…
is true	é verdadeiro (truthy)
is false	é falso (falsy)
exists	está presente na conversa
does not exist	está ausente
equals	corresponde a um valor que você especifica
does not equal	difere de um valor que você especifica

A Ação roda apenas quando todas as condições forem verdadeiras. Uma condição sobre uma chave que não está definida na conversa não passa.

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:

Cuidado

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

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 e a IA recebe apenas as partes correspondentes. Por exemplo, $.data.items[*].name mantém apenas os nomes dos itens de uma resposta maior.

Dica

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.

Cuidado

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.

Boas práticas

• Seja explícito: quando usar e como montar parâmetros.
• Escopo mínimo: apenas cabeçalhos/tokens necessários.
• Teste antes do lançamento: valide códigos e payloads.

Tutoriais

• Buscar tickets do Jira na conversa
• Enviar notificação no Slack com Ação de IA