Ação integração
Objetivo
A ação integração permite que uma automação se comunique com sistemas externos por meio de APIs, possibilitando o envio, consulta, atualização, e a remoção de informações durante a execução do fluxo.
Ela é utilizada para integrar a automação a outras plataformas, permitindo a troca de dados, em tempo real e automatizando processos que dependem de informações externas. Exemplo: buscar informações em um sistema externo para que a IA responda com dados atualizados, como horário de funcionamento, preços ou disponibilidade.
Método HTTP e URL da requisição
Ao configurar a ação integração, é necessário informar o método HTTP e a URL de requisição. Essas configurações definem como a automação irá se comunicar com a API e qual operação será executada.
Método HTTP
O método HTTP determina o tipo de operação que será realizada.
GET: Consultar ou obter informações, como horário de funcionamento, dados de clientes ou status de pedidos.
POST: Enviar informações ou criar novos registros, como cadastrar um lead, registrar um pedido ou criar um novo cliente.
PUT: Atualizar completamente um registro existente.
PATCH: Atualizar apenas informações específicas de um registro, como alterar um status ou telefone.
DELETE: Remove um registro de um sistema externo.
Importante: Utilize sempre o método indicado pela documentação da API que será integrada.
URL de requisição
A URL de requisição é o endereço da API para o qual a ação de integração enviará a solicitação. É por meio dela que a automação estabelece comunicação com um sistema externo.
Cada URL corresponde a um endpoint, responsável por executar uma operação específica, como consultar informações específicas, criar registros, atualizar dados ou excluir recursos.
Como configurar
Informe a URL exatamente conforme disponibilizada pela documentação da API que será integrada. Cada endpoint é desenvolvido para atender uma finalidade específica, portanto, é importante utilizar o endereço correspondente à operação desejada.
Exemplo de URL:
https://api.exemplo.com/clientes
Também é possível utilizar variáveis na URL para tomar a requisição dinâmica, permitindo que as informações enviadas variem conforme o contato que está passando pela automação.
Exemplo de URL:
https://api.exemplo.com/clientes/{{name}}
Nesse exemplo, a variável {{name}} será substituída automaticamente pelo nome do contato durante a execução da automação, permitindo que a API consulte as informações correspondentes.
Importante: Se a URL estiver incorreta, indisponível ou inacessível, a requisição não será concluída e a integração poderá não retornar o resultado esperado.
Headers:
O campo headers é utilizado para enviar informações adicionais junto com a requisição. Nele, normalmente são configurados dados como chaves de autenticação, tokens de acesso e outros parâmetros exigidos pela API.
As informações que devem ser preenchidas variam conforme a documentação da API utilizada. Por isso, é importante verificar quais headers são obrigatórios antes de realizar a integração.
Importante: Caso a API exija autenticação, as credenciais deverão ser informadas corretamente neste campo para que a requisição seja processada com sucesso.
Exemplo: Na imagem, foram configurados os Headers Content-Type, Authorization, X-API-Key e X-Sistema, utilizados para definir o formato dos dados, autenticar a requisição e enviar informações adicionais exigidas pela API.
Body:
O campo Body é utilizado para definir o conteúdo da requisição que será enviado para a API. Nele, devem ser informados os dados necessários para que o sistema externo processe a solicitação corretamente.
O conteúdo deve ser preenchido no formato JSON, conforme especificado pela documentação da API. Além de valores fixos, também é possível utilizar o botão de variáveis para inserir informações da automação, que serão substituídas automaticamente durante a execução da requisição.
Importante: A estrutura do JSON e os campos obrigatórios variam de acordo com a API utilizada. Consulte a documentação da API para preencher o Body corretamente.
Exemplo: Na imagem, a requisição envia o campo nome, preenchido automaticamente com a variável {{userFirstName}}.
Resposta:
O campo resposta exibe o retorno enviado pela API após a execução da requisição. Nele, é possível visualizar os dados retornados pelo sistema externo, como mensagens, informações consultadas ou o resultado da operação realizada.
Esses dados podem ser utilizados para validar se a integração está funcionando corretamente e, quando necessário, realizar o mapeamento das informações para utilização nas próximas etapas da automação.
Importante: A estrutura da resposta varia de acordo com a API utilizada. Consulte a documentação da API para identificar os campos disponíveis e como eles podem ser utilizados.
Exemplo: Na imagem, a API retorna uma mensagem de boas-vindas e o horário de funcionamento, que poderão ser utilizados na automação.
Mapeamento da resposta:
O campo mapeamento da resposta permite associar os dados retornados pela API a variáveis da integração. Dessa forma, as informações recebidas podem ser utilizadas nas próximas etapas da automação, como em mensagens, condições, ações, ou novas integrações.
Para realizar o mapeamento, informe o nome do campo retornado pela API e defina a variável onde esse valor será armazenado.
Na imagem abaixo, os campos mensagem e horário, retornados pela API, foram mapeados para as variáveis context.integration.mensagem e context.integration.horário. Após a execução da integração, essas variáveis poderão ser utilizadas em outras ações da automação, como enviar uma mensagem ao contato informando o horário de funcionamento retornado pela API.
Importante: Apenas os campos mapeados ficarão disponíveis como variáveis de integração para utilização nas próximas etapas da automação.
Saídas da ação:
A ação integração possui duas saídas:
Sucesso: utilizada quando a requisição é executada com sucesso e a API retorna, uma resposta válida.
Falha: utilizada quando ocorre algum erro durante a execução da requisição, permitindo definir um fluxo alternativo para tratar a situação.
Exemplo: Na imagem abaixo, a automação segue pela saída Sucesso e utiliza as variáveis configuradas no mapeamento de resposta para exibir ao contato a mensagem retornada pela API.
Utilizando as variáveis do mapeamento da resposta:
As variáveis criadas no mapeamento de resposta ficam disponíveis após a execução bem-sucedida da ação integração e podem ser utilizadas nas etapas seguintes da automação.
Essas variáveis podem ser inseridas em ações que suportam o uso de variáveis, como enviar mensagem, permitindo utilizar dinamicamente as informações retornadas pela API.
Exemplo: Na imagem abaixo, as variáveis configuradas no Mapeamento da resposta são utilizadas na ação Enviar mensagem para exibir ao contato a mensagem retornada pela API.
