Sobre a função
O bloco Comunicação assíncrona permite que o Hi Bot processe várias mensagens do consumidor de uma vez e obtenha as respostas por meio de uma API externa.
Esse recurso é ideal para os casos em que a empresa utiliza um agente de IA próprio e precisa de mais tempo ou de novas interações para gerar uma resposta conclusiva.
Quando recursos como Pergunta, Botões, Listas etc., são utilizados, o Hi Bot recebe uma resposta única do usuário, armazena em uma variável e dá continuidade ao fluxo.
Porém, é comum que os usuários enviem várias mensagens "quebradas", como:
Para esse cenário, é recomendado o uso do bloco Comunicação assíncrona, pois ele funciona como um endpoint, sendo capaz de esperar todas as interações do usuário, antes de dar continuidade à conversa.
Veja como fazer
Faça login em nossa plataforma e acesse o departamento de bot desejado.
Em seguida, clique em Configurações > Bot > Fluxos de conteúdos:
Adicione a Comunicação assíncrona que fica no bloco Integração, como mostramos abaixo:
Entenda como preencher cada um dos campos do bloco:
1- Pergunta: Define a mensagem inicial enviada ao consumidor. Essa pergunta marca o momento em que o fluxo entra em situação de parada, permitindo que o cliente envie múltiplas mensagens enquanto a interação externa acontece.
2- Variável para resposta do cliente: Seleciona a variável que irá armazenar todas as mensagens enviadas pelo consumidor durante a comunicação assíncrona.
Essa variável é utilizada pelo sistema externo para processar as interações recebidas enquanto o fluxo permanece pausado.
3- Variável de registro: Quando ativada, permite taguear as respostas do consumidor para fins de histórico, auditoria ou relatórios, sem interferir diretamente na lógica da integração assíncrona. Saiba mais.
4- Título da API: Esse título é apenas identificador e facilita a organização quando há múltiplas APIs configuradas no fluxo.
5- URL: Endereço do endpoint externo responsável por receber e processar as mensagens enquanto o atendimento está em situação de parada.
Esse endpoint deve estar preparado para consumir as informações enviadas pelo consumidor e responder conforme a lógica definida no ambiente externo do cliente.
6- Corpo: Estrutura do payload enviado na chamada da API.
É nesse campo que são configurados os dados enviados ao sistema externo, como mensagens do consumidor, identificadores da sessão e demais informações necessárias para o processamento.
O usuário poderá criar o corpo da requisição da sua API da maneira que for conveniente, mas é importante incluir o protocolo (treatmentId) e a mensagem do consumidor (message).
Exemplo de chamada de API:
curl --location 'https://bot-api.hiplatform.com/1.0/api/treatmentStopRuleAsync' \
--header 'Authorization: Basic <<TOKEN_DE_ACESSO>>' \
--header 'Content-Type: application/json' \
--data '{
"message": "mensagem para o usuário",
"treatmentId": "<<ID DE SESSÃO DE ATENDIMENTO>>",
"completed": true|false,
“data”: “qualquer valor em texto”
}'
- Para toda chamada a esse endpoint será necessário fornecer o TOKEN_DE_ACESSO que será descrito na próxima seção.
- Para toda chamada a esse endpoint será necessário informar qual é a sessão que está em situação de parada (treatmentId, sessionId e hi_protocol carregam sempre o mesmo valor).
- Para toda chamada a esse endpoint o campo “completed” é opcional, porém relevante; ele determina se uma situação de parada numa sessão de atendimento deve continuar ou não interagindo com o consumidor; caso seja hipótese de sair, o fluxo se seguirá normalmente.
- Para toda chamada a esse endpoint o campo “data” é opcional; caso seja hipótese de sair, o valor preenchido será salvo na variável de retorno configurada no Bloco Comunicação assíncrona.
7- Habilitar autenticação: Permite definir o modelo de autenticação utilizado na chamada da API. Esse recurso é obrigatório, pois o endpoint externo exige credenciais, como token de acesso, para autorizar a comunicação.
8- Criar cabeçalho/header: Utilizado para adicionar headers personalizados à requisição, como Authorization, Content-Type ou outros parâmetros exigidos pelo endpoint externo.
9- Mensagem de erro: Mensagem exibida ao consumidor caso ocorra falha na integração externa durante a comunicação assíncrona. Esse texto garante uma experiência controlada, evitando que o cliente fique sem retorno em caso de erro.
10- Variável para salvar o retorno da API: Define a variável que irá receber o conteúdo retornado pelo endpoint externo quando a situação de parada for finalizada.
Esse valor corresponde ao campo data enviado na chamada do endpoint quando o parâmetro completed for definido como true.
11- Limite de interações: Define a quantidade máxima de mensagens que o consumidor pode enviar enquanto o fluxo estiver em situação de parada. Se esse limite for atingido, o fluxo deixa a comunicação assíncrona e segue para o comportamento definido no fallback.
12- Conteúdo do fallback: Conteúdo exibido ao consumidor caso o limite de interações seja alcançado ou a comunicação assíncrona não seja concluída corretamente.
Esse recurso garante a continuidade do atendimento, direcionando o cliente para outro fluxo ou canal.
Token de acesso
Para obter o token de acesso às APIs da Hi, siga as instruções disponíveis na documentação de Gestão de usuários de API, clique aqui para ver como acessar.
Após a criação do usuário de API, siga os passos abaixo para gerar o token corretamente:
- Concatene o usuário e a senha da API, separados por dois-pontos (
:).
Exemplo:usuarioApi:senhaApi - Codifique essa string em Base64. Você pode utilizar uma ferramenta online, como:
https://www.base64encode.org/ - Envie o token gerado no header de autorização da requisição, utilizando o formato:
Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ=
Esse token é obrigatório para autenticar as chamadas às APIs da Hi e garantir a segurança da integração.