Integração com APIs de terceiros

Você pode criar bots que interagem com outros recursos via API. Por exemplo, bots podem atender a solicitações com a capacidade de verificar se é possível agendar um compromisso para uma determinada data ou encontrar um produto em uma loja online.

Como lidar com API de terceiros no exemplo do DaData

Vamos usar as dicas da API de https://dadata.ru/api/suggest/address como exemplo

Leia atentamente a documentação de APIs de terceiros

Abra seu projeto no Salebot e abra as configurações avançadas nas configurações de um bloco; lá você precisa alterar o tipo de solicitação para POST-json.

No campo “URL da solicitação” insira a seguinte URL: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address

No campo “Cabeçalho da solicitação” digite o cabeçalho no formato JSON:

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

Nos “Parâmetros JSON” coloque a própria solicitação - { "query": "#{CurrencyType}" }

Para obter os resultados, você também precisará preencher a guia “Valores armazenados”.

Um exemplo da solicitação está abaixo:

Como salvar valores de variáveis

Nem todo mundo entende de imediato, até que você tente fazer isso sozinho.

Para começar, digite #{custom_answer} no campo de resposta. (A variável #{custom_answer} contém a resposta obtida do servidor que foi mencionada no campo “URL para uma resposta do servidor”)

Execute o bloco com a solicitação para enviar a solicitação e obter uma resposta. Você precisa analisar a resposta e configurar o acesso às variáveis nela. Para isso, você precisa trabalhar com a guia “Valores armazenados”.

Vamos analisar um exemplo para entender melhor o processo.

Como resultado da nossa solicitação #{custom_answer}, uma resposta no formato chegou:

{"suggestions": [{"value": "Libra esterlina", "unrestricted_value": "Libra esterlina", "data": {"code": "826", "strcode": "GBP", "name": "Libra esterlina", "country": "Reino Unido"}}]}

Agora vamos escrever no campo “Valores armazenados” nosso VALOR->VARIÁVEL

suggestions - a chave do array [{"value": "Libra esterlina", "unrestricted_value": "Libra esterlina", "data": {"code": "826", "strcode": "GBP", "name": "Libra esterlina", "country": "Reino Unido"}}]

suggestions|0 - a chave do primeiro elemento no array {"value": "Libra esterlina", "unrestricted_value": "Libra esterlina", "data": {"code": "826", "strcode": "GBP", "name": "Libra esterlina", "country": "Reino Unido"}}

suggestions|0|value - a chave para o valor “Libra esterlina”

A chave mais longa neste JSON:

suggestions|0|data|strcode - a chave para o valor “GBP”

As chaves são separadas pela barra vertical (|). Se houver um array no JSON, o acesso ao seu elemento é numerado, começando pelo número 0 e também é escrito com a barra vertical.

É necessário repetir todo o aninhamento. Para maior comodidade, você pode visualizar o JSON em um aplicativo JSON-viewer.

Os níveis de aninhamento são separados por barras verticais. Então você precisa listar todas as chaves separadas pela barra para chegar ao valor.

Se houver um array no JSON, em vez da chave, você precisa mencionar o número do elemento começando com 0.

Separe as frases de obtenção de variáveis pelo símbolo de ponto e vírgula (;). As frases consistem no link para os dados na resposta e no nome da variável para salvá-la, que são separados pelos símbolos -> (traço + colchete angular).

A consulta de pesquisa é, de certa forma, um caminho no JSON para o valor necessário.

Desenvolvendo API para bots

Para desenvolver uma API, você precisará de uma hospedagem na qual ela será baseada. Se você não tiver uma ou não for um expert em programação, pode entrar em contato conosco e desenvolveremos a API para o seu bot e a hospedaremos na nossa. A hospedagem em si é gratuita, você pagará apenas pelo desenvolvimento.

Mas por enquanto, um pouco de teoria.

O bot suporta as solicitações GET e POST, que são os principais tipos usados na maioria das APIs públicas.

GET é uma solicitação que ocorre ao clicar em um link ou ao abrir um link no navegador. Os parâmetros em tal solicitação são transferidos para URLs de solicitação.

A sintaxe dos parâmetros transferidos: após a url, há um ponto de interrogação (?), então cada parâmetro é separado pelo e comercial (&). Um parâmetro consiste no nome e seu valor após o sinal de igual (=). Um exemplo de URL com um parâmetro:

Aqui você pode ver que um parâmetro chamado “search_query” está sendo compartilhado e que seu valor é “queen live aid”. O ‘+’ aqui é o espaço entre as palavras; ao trabalhar com o software de edição, você pode simplesmente deixar os espaços – o bot os alterará sozinho.

POST é um tipo de solicitação que é enviada com mais frequência ao preencher um formulário em um site. A solicitação transfere os parâmetros no corpo; claro, eles podem ser compartilhados da mesma forma que GET, mas raramente é feito dessa forma. O parâmetro no corpo pode estar no formato JSON ou como chave-valor. Como chave-valor, os parâmetros compartilham formulários; o formato JSON é o mais usado para API.

Cabeçalho da solicitação. Toda solicitação pode ter um cabeçalho/título adicionado. O formato dos dados compartilhados e as chaves de acesso são escritos nele na maioria das vezes. Geralmente deixamos esta guia vazia, mas é necessário colocar o Token da API ou o tipo de solicitação “Content-type”: “application/json” em raras ocasiões.

JSON - (JavaScript Object Notation) é um formato de arquivo padrão aberto e formato de intercâmbio de dados que usa texto legível por humanos para armazenar e transmitir objetos de dados que consistem em pares atributo-valor e arrays. Para trabalhar com a API em bots, você precisa conhecer este formato, tudo é baseado nele.

Antes de continuar, leia os seguintes artigos:

https://www.json.org/json-en.html
https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json

E também tente criar seu próprio arquivo JSON neste site:

https://jsoneditoronline.org

Prática

Blocos e condições podem atender a solicitações. As solicitações de condição são criadas para entender no site se o diálogo pode seguir um determinado caminho ou não. A solicitação neste caso ocorre toda vez que a condição do caminho é verificada. As solicitações dos blocos, ao contrário, são executadas apenas quando a movimentação para o bloco ocorre.

Antes de criar uma solicitação, você precisa escolher seu tipo:

POST-data e POST-json são diferenciados pelo método de transferência de parâmetros conforme mencionado acima (formato JSON ou como chave-valor). Se você escolher JSON, os parâmetros podem ser transferidos apenas na solicitação. Um campo adicional é aberto para o post: Parâmetros JSON POST. Importante! Os parâmetros devem ser escritos apenas no formato JSON, o bot só funciona dessa forma.

A resposta do servidor pode ser analisada e salva nas variáveis.

Você pode interpretar a resposta apenas se ela estiver no formato JSON.

As variáveis salvas são escritas na última submissão não preenchida; se a submissão for transferida através de um bloco vermelho, as variáveis são anuladas. Então, se você precisar salvar os dados, precisa transferir variáveis através do bloco amarelo.

A propósito, você pode ver o que o bot escreveu nas variáveis na seção Leads:

Transferência de dados não como uma linha

Por padrão, o valor da variável vem no formato #{} mas depois vem como uma linha. Para fazer a variável ser transferida como um número, você precisa desativar a verificação do formato dos parâmetros post-json.

Então você pode simplesmente mencionar o nome da variável, como {"key": #{variable_name}}, variable_name é a variável, então sem usar colchetes.

Após configurar os parâmetros, é recomendável reativar a verificação.