Como integro meu Bot com outros sistemas através de uma Superintegração? (Construtor - Bot novo)

Quer saber como utilizar uma Superintegração no novo construtor de Bots da Octadesk? Vem com a gente que vamos te contar tudo. o/

Acesse a documentação de API da Octadesk clicando aqui.

O que é uma Superintegração?

É uma maneira prática para um sistema fornecer outras aplicações com informações em tempo real, ou seja, é uma das formas de integração para troca de dados entre sistemas usando métodos HTTP como POST, GET, PUT, PATCH, DELETE e OPTIONS . Um detalhe importante: a API não é aberta.

O que eu posso integrar com o Bot?

Confira algumas funcionalidades que seu Bot pode incorporar utilizando Webhooks:

• Disponibilizar uma segunda via do boleto para o seu cliente, apenas usando um identificador (CPF, número de registro ou o que fizer mais sentido para a sua operação), e usar esse identificador para consultar os dados no seu sistema de pagamento;

• Informar o status de um pedido para o seu cliente, coletando o número do pedido e consultando a sua API de e-commerce;

• Atualizar o cadastro de um lead na sua base (RD Station, Hubspot, Pipedrive ou outra ferramenta de sua preferência) com as informações coletadas na conversa, ou criar um registro para novos leads.

Por onde começar?

Antes de tudo, acesse o Bot que você deseja realizar a integração. Para isso, você deve clicar no “Estúdio de automação” (ícone de fluxograma) localizado no menu lateral esquerdo e após definir qual canal você deseja criar o Bot (WhatsApp, Chat, Instagram ou Messenger) você deve selecionar a aba “Construtor de bots”, conforme imagem abaixo:

Selecione o Bot que será configurado ou crie um novo através do botão azul “Criar novo bot”.

No roteiro de etapas do Bot escolhido, crie uma nova etapa e selecione o componente "Conecte a outro sistema".

Método

Depois de dar um nome para essa etapa, você precisa definir como a integração será usada pelo seu Bot. Isso é chamado de método da integração e tem seis comportamentos:

• GET: Buscar/consultar dados em um sistema e exibi-los ao seu visitante;

• PUT: Usar as informações dadas pelo seu visitante para atualizar o sistema;

• POST: Criar uma entrada no sistema com essas informações;

• PATCH: Método utilizado para atualizações parciais;

• DELETE: Deletar alguma informação;

• OPTIONS: Utilizado para mapear quais as opções disponíveis de requisição para um determinado recurso.

URL

Depois de definir o comportamento da sua integração, você vai escrever com quem o seu Bot vai trocar informações, inserindo o endereço (URL) do sistema. 

No exemplo que segue abaixo, escolhemos o canal WhatsApp e vamos fazer uma consulta de endereço utilizando o CEP informado pelo cliente (em uma pergunta anterior) através da URL abaixo:

https://viacep.com.br/ws/#cep/json/

Parâmetros

O próximo passo é a definição dos parâmetros da sua integração. Esses parâmetros são as informações que o seu Bot vai enviar para o endereço (URL) que você informou no passo anterior. Esses parâmetros podem ser enviados de diferentes formas. Você deve consultar o sistema com quem seu Bot vai trocar informações para saber qual delas usar.

Path

Com o Path, você envia as informações que precisa na própria URL da aplicação. Assim, ela será modificada com base nos campos de conversa que você está usando. Por exemplo, a URL https://viacep.com.br vai ficar assim:

https://viacep.com.br/ws/#cep/json/

No exemplo abaixo, estamos incluindo o campo de conversa #cep, que foi preenchido pelo usuário durante a conversa com o Bot na URL.

Params

Ao usar o Params, você também envia as informações na URL da aplicação. Mas aqui ela se comunica de outro jeito: informando o nome e o valor de cada chave que você está usando. A chave é como se fosse uma caixa, já o valor é como se fosse o conteúdo dessa caixa. Logo, a chave serve para guardar e entregar o conteúdo (valor) para o sistema que você escolheu, assim:

https://www.urldosistema.com/?cep=#cep

No exemplo, o nome da nossa caixa (chave) é "cep", já o conteúdo (valor) dela é um campo de conversa onde o seu Bot salvou o CEP do visitante. Você pode inserir quantas chaves quiser, mas todas elas devem ter os valores informados, caso contrário sua integração vai retornar um erro.

Header

O Header é bem parecido com o Params, mas aqui ele envia as informações no cabeçalho da sua requisição. É ele que você vai usar quando o sistema pedir que informe um número de identificação (por exemplo, um token de acesso), fornecido por ele (sistema) antes de começar a trocar informações com seu Bot.

Body

Se o sistema com o qual o seu Bot vai se comunicar exige que as informações sejam enviadas no corpo da sua requisição, você vai precisar usar os parâmetros Body e inserir essas informações via código JSON.

É muito importante usar o padrão JSON para isso. Caso contrário a sua integração retornará um erro de análise, ok?

Análise de cenários

Caso sua integração retorne algum erro de requisição, você pode definir caminhos específicos. Isso garante que o seu Bot esteja preparado para continuar a interagir com seu visitante.

Para isso, escolha entre direcionar a conversa para uma das etapas já existentes no roteiro do Bot, criar uma etapa que conecte o seu visitante diretamente com seu time ou criar uma nova etapa, iniciando um novo caminho de conversa especificamente para o cenário de erro.

Em nosso exemplo, optamos por entender a demanda do cliente e realizar o direcionamento ao time responsável.

Validação da integração

Valide a sua integração. Assim, você pode verificar se as etapas anteriores foram configuradas corretamente.

Caso você esteja usando campos de conversa na sua integração, será preciso definir um valor de teste para cada campo usado para que a validação funcione corretamente. Estes valores só serão utilizados para o teste e não terão influência na conversa do Bot.

Assim que clicar em "Testar requisição", uma solicitação será acionada para o endereço que você informou, com o comportamento e informações que você definiu.

Se alguma coisa der errado, você deve descer um pouco mais na tela e olhar no detalhamento abaixo quais foram os erros encontrados. 

Salvar a resposta da integração

Você pode salvar informações encontradas pela sua integração para usá-las como precisar:

• Crie campos de conversa para usá-las na conversa do seu Bot;

• Crie campos temporários para usá-las na conversa ou comunicar valores para outra integração no mesmo roteiro do Bot;

• Crie campos de pessoa ou de organização para incluir informações em sua base de leads.

IMPORTANTE: Para que a Octadesk identifique e liste as informações que serão salvas, é preciso primeiro validar a sua integração. Depois disso, você poderá selecionar quais chaves e valores deseja salvar.

E se você quiser salvar mais de uma variável, você pode clicar em “Adicionar variável” e selecionar o campo de informação que você deseja salvar e selecionar a variável em que essa informação será salva. O campo onde você vai selecionar a variável retornada na API se chama “dado”.

Com a chave e o valor selecionados, defina o campo onde eles serão armazenados. Assim que começar a digitar, serão exibidos campos já existentes compatíveis.

Você pode também criar um campo e começar a usá-lo sem precisar sair da tela.

Selecione quantas chaves e valores precisar, armazenando cada chave em um campo específico.