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.

Transferência para humano (Human Handoff)

O Human Handoff garante que conversas que precisam de atenção humana sejam transferidas sem atrito para um Agente humano.

É especialmente útil para perguntas fora da Base de Conhecimento ou quando o usuário pede para falar com uma pessoa. Durante a transferência, o Assistente de IA pausa e o Agente humano assume pela Caixa de entrada (Inbox).

O que acontece para o usuário:

1. O usuário conversa com o Assistente de IA.
2. Se a solicitação excede a capacidade da IA ou o usuário pede um humano, a IA informa sobre a transferência.
3. A conversa é desatribuída da IA e atribuída a um Agente humano.
4. O humano resolve a solicitação ou reatribui à IA para continuar.

O que você vê no Quickchat AI:

1. A conversa não atribuída aparece na Inbox.
2. O membro do time lê o Resumo de IA.
3. Assume a conversa e atende o usuário.
4. Encerra ou reatribui.

Ativar o Human Handoff

Vá em Capabilities > Human Handoff e ative.

Opções de configuração:

Disponibilidade do Agente humano

Garanta que a transferência ocorra apenas no horário de atendimento.

• Horário de trabalho: início/fim e dias
• Fuso horário
• Mensagem fora do horário

Pergunta

Defina a pergunta que a IA fará antes da transferência.

Exemplo: Deseja que eu conecte você com nossa equipe de Suporte?

Confirmação

Defina a mensagem de confirmação quando a transferência iniciar.

Exemplo: Entendido. Vou transferi‑lo para nossa equipe de Suporte. Um instante.

Resumo de IA

Ative Resumos de IA para gerar automaticamente uma síntese da conversa até aqui, dando contexto ao Agente humano.

(Opcional) Palavras‑chave de gatilho

Insira palavras que sempre disparam a transferência.

Cuidado

Opcional, pois o Human Handoff detecta a intenção do usuário e transfere se necessário.

Exemplo: para o Assistente “Helpful Macintosh” da MacShop, use “nota fiscal”, “recibo” e “status de entrega”.

Notificações por e‑mail

Configure e‑mails para aviso quando houver nova conversa que requer humano.

---

Coleta inteligente de dados / Geração de leads

A Coleta inteligente de dados permite que seu Agente peça informações (nome, e‑mail, telefone, etc.) de forma natural. Esses dados podem ser enviados ao seu CRM ou outros sistemas.

Como funciona

Integrada ao fluxo da conversa.

1. A IA detecta oportunidades de coleta.
2. Faz perguntas direcionadas, por exemplo:
   • “Qual seu nome para que eu possa ajudar melhor?”
   • “Qual o melhor e‑mail para contato?”
3. Armazena as respostas para revisão ou integração.

Configuração

Ativar Coleta de Dados

• Vá em Actions & MCPs
• Abra Smart Data Gathering
• Ative

Dados a coletar

• E‑mail
• Primeiro nome
• Telefone

Quando perguntar

• Após algumas mensagens
• Logo após demonstrar interesse

Como perguntar

• Sutil: integrado naturalmente
• Direto: pedido explícito

Exportar dados coletados

1. Vá na Inbox
2. Clique em export
3. Escolha Export Gathered Data
4. Defina período
5. Selecione formato (CSV, XLSX)
6. Download

---

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. Você define uma Ação de API com nome, descrição, método HTTP, URL do endpoint, cabeçalhos e parâmetros.
2. No chat, a IA decide quando usar com base na descrição e nas dicas dos parâmetros.
3. O Quickchat envia a requisição e retorna o JSON para a IA, que responde ao usuário em linguagem natural.
4. Você pode testar a requisição no editor antes de usar 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. Configure Connection:
   • Action Type: GET ou POST
   • Action endpoint URL: URL completa
   • Headers: cabeçalhos necessários (Authorization, content-type: application/json etc.)
5. 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}}.
6. 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.

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.

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