A ferramenta está disponível para todos os canais: Chat, Telefone e E-mail.
Não confunda com o Pedido HTTP nas Automações. Nas Automações, o Pedido HTTP é um passo do fluxo que é executado num ponto fixo. Esta ferramenta pertence ao próprio Agente de IA: é ele que decide, durante a conversa, se e quando faz o pedido, e continua a trabalhar com a resposta.
Requisitos: um Agente de IA no Superchat e uma API que pretende chamar (URL, método e, se necessário, credenciais).
Adicionar a ferramenta
Abra o seu Agente de IA e mude para a área Ferramentas e Ações à esquerda.
Clique em Adicionar ferramenta, no canto superior direito.
Selecione o cartão Pedidos HTTP e clique em Adicionar.
O editor da ferramenta abre com seis separadores: Geral, Parâmetros, Pedido, Corpo, Credenciais e Teste.
Geral: nome e regra de utilização
Nome da ferramenta: Um nome curto que descreva o que a ferramenta faz, por exemplo "Consultar estado da encomenda" ou "Criar marcação". O nome aparece na lista em Ferramentas e Ações.
Quando deve o agente usar a ferramenta? Esta descrição é a parte mais importante da ferramenta. O Agente de IA decide se faz o pedido com base neste texto. Descreva em concreto em que situação deve usar a ferramenta, o que vai encontrar na resposta e como deve utilizá-la. Mencione também quando não a deve usar.
Exemplo: "Usa esta ferramenta quando o cliente perguntar pelo estado da sua encomenda. A resposta contém o estado atual e a data de entrega prevista, que deves comunicar ao cliente. Não uses esta ferramenta se o cliente não tiver indicado um número de encomenda."
Parâmetros: que valores fornece o agente
Os parâmetros são os valores que mudam de pedido para pedido, como um número de encomenda ou o número de telefone do contacto. Define-os aqui e insere-os depois, através do botão { }, no URL, nos parâmetros de consulta, nos cabeçalhos ou no corpo.
Clique em Adicionar e preencha, para cada parâmetro:
Nome: O nome que vai usar mais tarde para inserir o valor.
Origem: De onde vem o valor.
Agente de IA: O agente retira o valor da conversa, por exemplo um número de encomenda que o cliente menciona.
Atributo do contacto: O valor vem dos dados já existentes do contacto no Superchat, por exemplo o número de cliente.
Tipo: Tipo de dados do valor, por exemplo texto.
Descrição: O que é o valor e de onde vem. Para a origem "Agente de IA", a descrição ajuda o agente a retirar o valor certo da conversa.
Obrigatório: Se o pedido precisa mesmo do valor.
A coluna Utilização mostra se o parâmetro já foi inserido em algum ponto do pedido. Se indicar "Não associado", o valor ainda não está a ser enviado para lado nenhum.
Dica sobre "Obrigatório": Desative "Obrigatório" para tudo o que vem da conversa. Se o valor não estiver disponível, o agente simplesmente omite o campo, em vez de bloquear o pedido ou de perguntar desnecessariamente ao cliente.
Pedido: método, URL, parâmetros de consulta e cabeçalhos
Método e URL: Escolha o método HTTP à esquerda (por exemplo POST) e introduza à direita o URL da sua API ou do seu webhook.
Parâmetros de consulta: Pares nome-valor acrescentados ao URL. Use Adicionar para criar mais.
Cabeçalhos: Pares nome-valor para cabeçalhos HTTP, por exemplo
Content-Type. As credenciais não pertencem aqui: use antes o separador Credenciais.Tempo limite: Segundos ao fim dos quais o pedido é cancelado (predefinição: 30). No telefone, quem liga fica à espera durante este tempo, por isso mantenha o valor tão baixo quanto a sua API permitir.
Em todos os campos pode inserir um parâmetro através do botão { }.
Corpo: conteúdo do pedido
Escolha o que o pedido envia:
Sem corpo: O pedido não envia conteúdo. Adequado para consultas simples.
JSON: Dados estruturados, o padrão da maioria das APIs e webhooks.
Dados de formulário: Campos de formulário clássicos.
Texto simples: Conteúdo de texto livre.
Também aqui insere parâmetros através de { }, por exemplo {"order_number": {{order_number}}}.
Credenciais: autentique a sua API em segurança
Se a sua API precisar de uma chave de API ou de um token, guarde-o aqui. Selecione credenciais existentes no menu pendente ou clique em Criar novas credenciais. Depois de criadas, as credenciais ficam disponíveis para outras ferramentas.
As credenciais são guardadas de forma segura. O Agente de IA nunca vê nem define estes valores, pelo que também não os pode revelar por engano numa conversa.
Teste: execute o pedido a sério uma vez
Antes de guardar, verifique o pedido no separador Teste. Introduza um valor de exemplo para cada parâmetro e clique em "Enviar pedido de teste". O pedido vai mesmo para a sua API, por isso utilize dados de teste.
A indicação "Nenhum parâmetro é usado em lado nenhum: esta ferramenta chama sempre o mesmo pedido" significa que criou parâmetros mas não os inseriu em lado nenhum através de { }, ou que a ferramenta funciona sem quaisquer parâmetros. Isso não é problema para uma consulta fixa; quando o agente tiver de enviar valores da conversa, insira-os no URL, no cabeçalho ou no corpo.
Depois clique em Guardar. A ferramenta aparece na lista em Ferramentas e Ações como Pedidos HTTP: <Nome>.
Testar numa conversa
Abra o Ambiente de teste à direita, escolha o canal (Chat, Telefone ou E-mail) e faça ao seu Agente de IA a pergunta que deve ativar a ferramenta. Assim vê se a usa no momento certo e se aproveita a resposta de forma sensata.
Se o agente não usar a ferramenta, comece por afinar o texto em Quando deve o agente usar a ferramenta? e mencione também a ferramenta em Tarefa e Regras, em "O que deve o seu agente fazer?", por exemplo: "Se um cliente perguntar pela sua encomenda, consulta o estado da encomenda através da ferramenta e indica-lhe o estado e a data de entrega."
Importante: Os atributos de contacto não são partilhados no Ambiente de teste. No Ambiente de teste, só pode trabalhar com parâmetros que o agente retira da conversa atual. Para testar com atributos de contacto, use uma conversa real, iniciada por si.
Boas práticas
Formule a regra de utilização pela positiva e pela negativa. Quando usar, quando não usar.
Mantenha as respostas enxutas. O agente lê a resposta da sua API. Quanto mais clara e curta for, mais precisa será a sua indicação ao cliente.
Mantenha o tempo limite o mais baixo possível. O contacto nota cada segundo de espera. No telefone recomendamos no máximo 10 segundos e, no chat, 30 segundos.
Teste com dados de teste. O pedido de teste e os testes no Ambiente de teste chamam mesmo a sua API.