# Configure sua integração de 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**](/chatlayer-documentation-pt-br/buildabot/flow-logic/dialog-state/action-bot-dialog.md) bloco para o seu [canvas](/chatlayer-documentation-pt-br/navegacao/bot-builder/flows.md).

<figure><img src="/files/10e727bb57e2579776db0f5efe092910a04f32d6" alt="" width="375"><figcaption><p>Adicione um passo de Ação de API.</p></figcaption></figure>

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

<details>

<summary>Métodos HTTPS</summary>

O passo de API suporta 5 métodos HTTPS:

* POST
* GET
* DELETE
* PUT&#x20;
* PATCH

<img src="/files/5535cb22adfe6c44e4c2e14d769b1ec0e333fa49" alt="" data-size="original">

</details>

{% 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" %}

<figure><img src="/files/0634459decce61be88937492f50252c306ba7a77" alt="" width="375"><figcaption><p>A aba Query dentro do seu passo de API.</p></figcaption></figure>

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](/chatlayer-documentation-pt-br/bot-answers/session.md) 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" %}

<figure><img src="/files/eee6d36b925633c80ccb1dec9ce66d73d6936283" alt="" width="375"><figcaption><p>A aba Autorização dentro do seu passo de API.</p></figcaption></figure>

O **Autorização** aba tem os seguintes componentes:

* **Autenticação básica**: exibirá os campos para preencher nome de usuário e senha.

<figure><img src="/files/5601c6ae3e1be77e4bf0df0359534bd6a07edb7f" alt="" width="362"><figcaption><p>Autorização via autenticação básica.</p></figcaption></figure>

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

<figure><img src="/files/3bcc51639a6dc91210a156e9c9941d7be409e15c" alt="" width="362"><figcaption><p>Autorização via token Bearer.</p></figcaption></figure>
{% endtab %}

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

<figure><img src="/files/14f00ade437c708ad34ba434970d7955dc6b1f78" alt="" width="375"><figcaption><p>A aba Cabeçalhos dentro do seu passo de API.</p></figcaption></figure>

A aba Cabeçalhos é onde você configura seus cabeçalhos.
{% endtab %}

{% tab title="Corpo" %}

<figure><img src="/files/1e200ba4d4867ffe5ead52eddee680a8d97c4427" alt="" width="375"><figcaption><p>A aba Corpo dentro do passo de API.</p></figcaption></figure>

**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](/chatlayer-documentation-pt-br/bot-answers/session.md) 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 <https://chatlayer-integration-demo.glitch.me/transaction>.

<figure><img src="/files/406925093f838fa86251a4200ed63127fd11c6c0" alt="" width="375"><figcaption><p>Exemplo de payload do corpo.</p></figcaption></figure>

* 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" %}

<figure><img src="/files/56893f4788cc939a5e674833dc8dc1a7b6578d81" alt="" width="375"><figcaption><p>A aba Configuração dentro de um passo de API.</p></figcaption></figure>

**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](/chatlayer-documentation-pt-br/nlp/languages/multilanguage-bots.md)[l](/chatlayer-documentation-pt-br/nlp/languages/multilanguage-bots.md), 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](/chatlayer-documentation-pt-br/bot-answers/session.md) 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.&#x20;

<details>

<summary>Variáveis de retorno da API</summary>

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](/chatlayer-documentation-pt-br/integrateandcode/chat-message-structure-for-apis.md).
* `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.&#x20;

**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',
  },
};
```

</details>

{% 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.

<figure><img src="/files/38674b4dd5ea8cb3e16cd502bd40cf0c76446aa4" alt="" width="375"><figcaption></figcaption></figure>

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chatlayer.ai/chatlayer-documentation-pt-br/integrateandcode/custom-back-end-integrations/configure-your-api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.