# Configure sua integração com API Um passo do Chatlayer **API** etapa está disponível nos [**Ação**](https://docs.chatlayer.ai/bot-answers/dialog-state/action-bot-dialog) blocos para permitir que você crie mensagens do bot com base em informações específicas do usuário e outros dados externos, e para redirecionar seus usuários para fluxos diferentes com base na sua própria lógica de negócio. Você pode usar esta solução em qualquer plataforma que suporte receber e responder a requisições HTTP. O passo de API envia uma requisição para o seu servidor backend. ### Enviar uma requisição de API Para configurar seu passo de API: 1. Solte um [**Ação**](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/buildabot/flow-logic/dialog-state/action-bot-dialog) bloco para o seu [canvas](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/navegacao/bot-builder/flows).

2. Clique em API. 3. Configure seus parâmetros. Veja abaixo para mais detalhes.

Métodos HTTPS

O passo de API suporta 5 métodos HTTPS: * POST * GET * DELETE * PUT * PATCH

{% hint style="warning" %} Você só pode definir um corpo de requisição quando seu método de requisição for POST ou DELETE. {% endhint %} {% tabs %} {% tab title="Query" %}

Sob a **Query** aba, adicione parâmetros de query e/ou um payload de corpo definindo combinações chave-valor. Cada chave pode ter 3 tipos possíveis de valor: * **text**: texto estático. * **variável**: uma [sessão do usuário](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/bot-answers/session) variável. O valor da variável será armazenado como valor para a chave. Notação de ponto e de array são suportadas, por exemplo: `users[0].firstname` * **dialogstate**: selecione um estado de diálogo no menu. O ID do estado de diálogo será armazenado como valor para a chave. Este ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócio ao retornar a resposta da API. {% endtab %} {% tab title="Autorização" %}

A aba Autorização dentro do seu passo de API.

O **Autorização** aba tem os seguintes componentes: * **Autenticação básica**: exibirá os campos para preencher nome de usuário e senha.

* **Token Bearer**: exibirá o campo Token para ser preenchido.

{% endtab %} {% tab title="Cabeçalhos" %}

A aba Cabeçalhos dentro do seu passo de API.

A aba Cabeçalhos é onde você configura seus cabeçalhos. {% endtab %} {% tab title="Corpo" %}

**Corpo** é onde você pode definir um corpo de requisição em todos os métodos HTTPS. Sob a **Corpo** aba, adicione parâmetros de query e/ou um payload de corpo definindo combinações chave-valor. Cada chave pode ter 3 tipos possíveis de valor: * **text**: texto estático. * **variável**: uma [sessão do usuário](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/bot-answers/session) variável. O valor da variável será armazenado como valor para a chave. Notação de ponto e de array são suportadas, por exemplo: `users[0].firstname` * **dialogstate**: selecione um estado de diálogo no menu. O ID do estado de diálogo será armazenado como valor para a chave. Este ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócio ao retornar a resposta da API. Neste exemplo, representando uma transferência de dinheiro, enviamos cinco chaves no payload do corpo de uma requisição HTTPS POST para nosso endpoint de API .

* O **amount** a chave terá o valor da variável de sessão do usuário `transfer_amount` (ex: 500). * O **destination** a chave terá o valor da variável de sessão do usuário `transfer_destination` (ex: Elon Musk). * O **accountType** a chave terá o valor da variável de sessão do usuário `card_type` (ex: savings\_account). * O **transactionSuccess** a chave terá o identificador do estado de diálogo para o estado de diálogo 'transação bem-sucedida'. Este identificador pode ser usado na resposta desta requisição de API para redirecionar o usuário para um novo estado de diálogo. * O **transactionNoMoney** a chave terá o identificador do estado de diálogo para o estado de diálogo 'transação malsucedida'. Este identificador pode ser usado na resposta desta requisição de API para redirecionar o usuário para um novo estado de diálogo. * O **test** a chave terá o valor '5'. Isso resultará no seguinte payload do corpo: ```javascript { "amount": 500, "destination": "Elon Musk", "accountType": "savings_account", "transactionSuccess": "successful transaction", "transactionNoMoney": "unsuccessful transaction", "test": 5 } ``` {% endtab %} {% tab title="Configuração" %}

A aba Configuração dentro de um passo de API.

**Configuração** é onde, se você tiver uma configuração de API em [Configurações>API](https://docs.chatlayer.ai/integrations/custom-back-end-integrations/advanced-api-integrations#api-ssl-settings), você as verá aqui. {% endtab %} {% endtabs %} {% hint style="info" %} Se [seu bot é multilíngue](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/nlp/languages/multilanguage-bots)[l](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/nlp/languages/multilanguage-bots), se a resposta da API enviar mensagens de agente de volta ao usuário e o agente suportar múltiplos idiomas, não esqueça de enviar o idioma do usuário na requisição. O idioma do usuário está disponível no [sessão do usuário](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/bot-answers/session) variável `locale`. Seu serviço backend pode usar essa configuração de idioma para enviar a resposta no `idiomaPreferido`. {% endhint %} ### Escutar por uma resposta da API Você não precisa configurar o plugin de API para escutar por uma resposta. Isso é feito automaticamente e o **API** passo irá escutar o que sua API retornar.

Variáveis de retorno da API

O **API** o passo suporta 3 tipos de variáveis de retorno: * `sessão`: Um objeto de sessão para salvar dados na sessão do usuário. A sessão tem 2 campos obrigatórios: * `namespace`: um namespace de chave. O objeto de dados será armazenado nesta chave de namespace na sessão do usuário. Você pode acessar este objeto no Chatlayer.ai usando interpolação: *{namespace.dataKey}.* * `data`: um objeto que será salvo nos dados de sessão do usuário na chave de namespace. * `mensagens`: um array de mensagens para enviar de volta ao canal de interface do usuário. A estrutura dos diferentes tipos de mensagem (como texto, botões, respostas rápidas, carrosséis, listas, mídia, etc.) está disponível no [estrutura de mensagem de chat](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/integrateandcode/chat-message-structure-for-apis). * `action`: um objeto definindo uma ação, como redirecionar o usuário para um próximo estado de diálogo na conversa. * `nextDialogstate`: um identificador de estado de diálogo para redirecionar o usuário para um próximo estado de diálogo no fluxo de conversa. As 3 opções acima são executadas na ordem mostrada acima: variáveis de sessão são definidas primeiro, então as mensagens são enviadas e então você irá pular para o próximo estado de diálogo. **Exemplo** Você pode encontrar um exemplo JSON para esses 3 casos no trecho de código abaixo: ```javascript const result = { session: { namespace: 'myNamespace', data: { variable: 'test123' }, }, messages: [{ type: 'text', config: { textMessages: [{ text: 'random message 1' }] } }], action: { nextDialogstate: 'dialogstate-123-abc', }, }; ```

{% hint style="warning" %} Certifique-se de incluir o tipo de conteúdo correto no cabeçalho: `content-type: application/json;` {% endhint %} ### Exemplo Este exemplo demonstra um endpoint de API para transferir uma quantia de dinheiro de um tipo de conta (corrente ou poupança) para alguém. Nós redirecionaremos o usuário para um determinado estado de diálogo com base no resultado da transação. ```javascript app.post('/transaction', function (req, res) { let nextDialogstate; const { amount, destination, accountType, transactionSuccess, transactionNoMoney = req.body; // obter tipo de conta (corrente - conta poupança) const account = account_synonyms[accountType]; if( accounts[account].amount + accounts[accounthlimit — amount < ) { nextDialogstate = transactionNoMoney } else { // transferir valor accounts[account].amount —= amount; nextDialogstate = transactionSuccess; } res.json({ action: { nextDialogstate, }, session: { namespace: 'account', data: { limit: accounts[account].limit, amount: accounts[account].amount } }, }) }); ``` Recebemos o objeto payload do corpo conforme definido no passo do Chatlayer **API** Se o usuário não tiver uma quantia suficiente de dinheiro em sua conta, definimos o próximo estado de diálogo como 'transactionNoMoney'. Caso contrário, subtraímos o valor desejado e definimos o próximo estado de diálogo como 'transactionSuccess'. Como resposta à requisição, enviamos o próximo estado de diálogo para redirecionar o usuário para esse estado e salvamos a quantia de dinheiro e o limite da conta na sessão dele sob o namespace account. Esses dados podem ser usados nesse próximo estado de diálogo.

Como solução alternativa você também poderia enviar essa mensagem de chat como resposta das requisições do plugin de API usando a chave messages.