Você pode criar bots que interagem com outros serviços via APIs. Por exemplo, bots podem fazer requisições para verificar disponibilidade para uma data específica ou encontrar um produto em uma loja online.

Como interagir com APIs de terceiros usando Dadata como exemplo

Vamos usar uma API de sugestão de endereço como exemplo: https://dadata.ru/api/suggest/address/ link será outro

Leia atentamente a documentação das APIs de terceiros.

Atenção! APIs de terceiros exigem os endereços IP de onde as requisições serão enviadas: 158.160.49.208 – site.

No campo "URL da requisição", insira https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address.

No campo "Cabeçalho da requisição", insira o cabeçalho em formato JSON: {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}.

No campo "Parâmetros JSON", insira a própria requisição: {"query": "#{CurrencyType}"}.

Para obter o resultado da requisição, preencha o campo "Valores salvos".

Um exemplo da requisição é mostrado na ilustração abaixo.

Como salvar valores de variáveis

Pode não ficar completamente claro na primeira vez — você realmente precisa tentar por conta própria.

Primeiro, insira #{custom_answer} no campo "Resposta". (A variável #{custom_answer} contém a resposta recebida do servidor especificado no campo "URL da resposta".)

Execute o bloco de requisição para enviar a requisição e obter a resposta. A resposta recebida precisa ser analisada, e você deve configurar quais variáveis extrair dela. Para isso, use o campo "Valores salvos".

Vamos percorrer o exemplo descrito acima.

A melhor maneira de entender como acessar dados em JSON é através de exemplos. Como resultado da nossa requisição, a resposta recebida em #{custom_answer} se parece com isso:

{ "suggestions": [ { "value": "US Dollar", "unrestricted_value": "US Dollar", "data": { "code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States" } } ] }

No campo "Valores salvos", insira VALOR -> VARIÁVEL:

suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry

suggestions - chave para o array [{"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]

suggestions|0 - chave para o primeiro elemento do array {"value": "US Dollar", "unrestricted_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}

suggestions|0|value - chave para o valor "US Dollar"

A chave mais longa neste JSON:

suggestions|0|data|strcode - chave para o valor "USD"

As chaves são separadas por uma barra vertical (|). Se um elemento JSON for um array, você acessa seus itens por índice, começando de 0, e isso também é escrito usando uma barra vertical.

Você precisa repetir todo o aninhamento. Para conveniência, você pode visualizar o JSON usando um aplicativo visualizador de JSON.

O nível de aninhamento é separado por uma barra vertical. Ou seja, você precisa listar todas as chaves para alcançar o valor, separando-as com uma barra vertical.

Se o JSON contiver um array, use o índice do elemento em vez de uma chave, começando do zero.

Separe as expressões para obter nossas variáveis com ponto e vírgula ;.

Cada expressão consiste no caminho para os dados na resposta e no nome da variável para salvá-la, separados por ->.

A consulta de pesquisa representa o caminho no JSON até o valor necessário.

Desenvolvimento de API para bots

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

GET é uma requisição que ocorre quando você clica em um link ou abre uma URL no navegador. Os parâmetros nesta requisição são passados na URL.

Sintaxe para passar parâmetros: após a URL, coloque um ponto de interrogação ?, depois separe cada parâmetro com um e comercial &. Cada parâmetro consiste em um nome seguido por = e seu valor.

Exemplo de uma URL com um parâmetro:

Fig. 3

Aqui, um único parâmetro q é passado com o valor "good music". %20 representa um espaço.

Ao trabalhar com o construtor, você pode usar apenas um espaço — o bot o substituirá automaticamente.

POST é uma requisição mais frequentemente enviada ao enviar um formulário em um site. Os parâmetros são enviados no corpo da requisição. Embora também possam ser enviados na URL como em requisições GET, isso é incomum. Os parâmetros no corpo podem estar em formato JSON ou como pares chave-valor. Formulários geralmente enviam pares chave-valor, enquanto APIs geralmente usam JSON.

Cabeçalho da requisição - você pode adicionar um cabeçalho a cada requisição. Na maioria das vezes, especifica o formato dos dados e as chaves de acesso. Normalmente, este campo é deixado vazio, mas em casos raros, você precisa incluir um token de API ou um tipo de requisição, por exemplo, "Content-Type": "application/json".

JSON (JavaScript Object Notation, geralmente pronunciado /ˈdʒeɪsən/ JAY-sən) é um formato de intercâmbio de dados baseado em texto, baseado em JavaScript. Como muitos outros formatos de texto, JSON é fácil de ser lido por humanos. Para trabalhar com APIs no bot, você precisa entender este formato, pois ele fundamenta todas as interações.

Antes de continuar, leia os seguintes artigos:

https://www.json.org/json-ru.html
https://developer.mozilla.org/ru/docs/Learn/JavaScript/%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D1%8B/JSON

Além disso, tente criar seu próprio arquivo JSON neste site:

https://jsoneditoronline.org/

Prática

Requisições podem ser executadas por blocos e condições. Requisições condicionais são projetadas para verificar se um diálogo pode seguir um determinado ramo no site. Neste caso, a requisição é enviada toda vez que a condição do ramo é avaliada. Requisições em blocos, por outro lado, são executadas apenas quando o diálogo entra naquele estado.

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

POST-data e POST-JSON diferem em como os parâmetros são enviados, como mencionado anteriormente (em formato JSON ou como pares chave-valor). Se você escolher JSON, os parâmetros só podem ser enviados no corpo da requisição. Um campo adicional aparecerá para parâmetros JSON POST.

Importante! Os parâmetros devem ser escritos apenas em formato JSON, pois o bot trabalha exclusivamente com ele. Você já praticou escrever JSON.

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

Você pode analisar uma resposta apenas se ela estiver em formato JSON.

Variáveis salvas são registradas no último formulário não preenchido. Se o formulário for enviado através de um bloco vermelho, as variáveis são descartadas. Portanto, se você precisar salvar esses dados, passe as variáveis para o sistema CRM através de um bloco amarelo.

Você também pode ver o que o bot registrou nas variáveis na seção "Leads".

Fig. 8

Passando variáveis não como string

Por padrão, os valores das variáveis devem ser strings no formato "#{}", mas neste caso, a variável é enviada como string. Para passar uma variável como número, você precisa desabilitar a verificação de formato de parâmetro nas configurações do projeto:

Então você pode simplesmente usar o nome da variável, por exemplo: {"key": #{variable_name}}, onde variable_name é a própria variável — sem aspas ao redor.

Recomenda-se reativar a verificação de formato após definir os parâmetros.