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 executada automaticamente antes da primeira resposta ou quando as condições de metadados corresponderem pela primeira vez.
3. 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.
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, Antes da primeira resposta ou Quando os metadados correspondem.
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 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 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.
• 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.

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 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

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 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 Run only when 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 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 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.

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