> For the complete documentation index, see [llms.txt](https://docs.chatlayer.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/integrateandcode/custom-back-end-integrations/configure-your-api-integration.md).

# Configure sua integração de API

Uma etapa do Chatlayer **API** etapa está disponível na [**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 redirecione seus usuários para fluxos diferentes com base na sua própria lógica de negócios.

Você pode usar esta solução em qualquer plataforma que suporte receber e responder a solicitações HTTP.

A etapa de API envia uma solicitação para o seu servidor backend.

### Enviar uma solicitação de API

Para configurar sua etapa de API:

1. Adicione 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 uma etapa 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>

A etapa de API suporta 5 métodos HTTPS:

* POST
* GET
* DELETE
* PUT
* PATCH

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

</details>

{% hint style="warning" %}
Você só pode definir um corpo da solicitação quando o método da solicitação for POST ou DELETE.
{% endhint %}

{% tabs %}
{% tab title="Consulta" %}

<figure><img src="/files/0634459decce61be88937492f50252c306ba7a77" alt="" width="375"><figcaption><p>A guia Query dentro da sua etapa de API.</p></figcaption></figure>

Na **Consulta** guia, adicione parâmetros de consulta e/ou um payload de corpo definindo combinações de chave-valor. Cada chave pode ter 3 tipos de valor possíveis:

* **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 da chave. A notação de ponto e de array são suportadas, por exemplo: `users[0].firstname`
* **dialogstate**: selecione um estado de diálogo no menu suspenso. O ID do estado de diálogo será armazenado como valor da chave. Esse ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócios ao retornar a resposta da API.
  {% endtab %}

{% tab title="Autorização" %}

<figure><img src="/files/eee6d36b925633c80ccb1dec9ce66d73d6936283" alt="" width="375"><figcaption><p>A guia Autorização dentro da sua etapa de API.</p></figcaption></figure>

A **Autorização** guia 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 de 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 com token Bearer.</p></figcaption></figure>
{% endtab %}

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

<figure><img src="/files/14f00ade437c708ad34ba434970d7955dc6b1f78" alt="" width="375"><figcaption><p>A guia Cabeçalhos dentro da sua etapa de API.</p></figcaption></figure>

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

{% tab title="Corpo" %}

<figure><img src="/files/1e200ba4d4867ffe5ead52eddee680a8d97c4427" alt="" width="375"><figcaption><p>A guia Corpo dentro da etapa de API.</p></figcaption></figure>

**Corpo** é onde você pode definir um corpo da solicitação em todos os métodos HTTPS.

Na **Corpo** guia, adicione parâmetros de consulta e/ou um payload de corpo definindo combinações de chave-valor. Cada chave pode ter 3 tipos de valor possíveis:

* **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 da chave. A notação de ponto e de array são suportadas, por exemplo: `users[0].firstname`
* **dialogstate**: selecione um estado de diálogo no menu suspenso. O ID do estado de diálogo será armazenado como valor da chave. Esse ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócios ao retornar a resposta da API.

Neste exemplo, representando uma transferência de dinheiro, enviamos cinco chaves no payload do corpo de uma solicitaçã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>

* A **amount** a chave terá o valor da variável de sessão do usuário `transfer_amount` (ex.: 500).
* A **destination** a chave terá o valor da variável de sessão do usuário `transfer_destination` (ex.: Elon Musk).
* A **accountType** a chave terá o valor da variável de sessão do usuário `card_type` (ex.: savings\_account).
* A **transactionSuccess** a chave terá o identificador do estado de diálogo para o estado de diálogo de ‘transação bem-sucedida’. Esse identificador pode ser usado na resposta desta solicitação de API para redirecionar o usuário para um novo estado de diálogo.
* A **transactionNoMoney** a chave terá o identificador do estado de diálogo para o estado de diálogo de ‘transação malsucedida’. Esse identificador pode ser usado na resposta desta solicitação de API para redirecionar o usuário para um novo estado de diálogo.
* A **teste** a chave terá o valor de ‘5’.

Isso resultará no seguinte payload do corpo:

```javascript
{
    "amount": 500,
    "destination": "Elon Musk",
    "accountType": "savings_account",
    "transactionSuccess": "transação bem-sucedida",
    "transactionNoMoney": "transação malsucedida",
    "test": 5
}
```

{% endtab %}

{% tab title="Configuração" %}

<figure><img src="/files/56893f4788cc939a5e674833dc8dc1a7b6578d81" alt="" width="375"><figcaption><p>A guia Configuração dentro de uma etapa 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ê a verá aqui.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Se [se seu bot for multilíngua](/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 do agente de volta ao usuário e o agente suportar vários idiomas, não se esqueça de enviar o idioma do usuário na solicitação. O idioma do usuário está disponível em [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 de volta a resposta no idioma do usuário `preferredLanguage`.
{% endhint %}

### Escutar uma resposta da API

Você não precisa configurar o plugin de API para escutar uma resposta. Isso é feito automaticamente e a **API** etapa escutará o que sua API retornar.

<details>

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

A **API** etapa suporta 3 tipos de variáveis de retorno:

* `session`: 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 nessa chave de namespace na sessão do usuário. Você pode acessar esse objeto no Chatlayer.ai usando interpolação: *{namespace.dataKey}.*
  * `data`: um objeto que será salvo nos dados da sessão do usuário na chave de namespace.
* `messages`: uma matriz de mensagens para enviar de volta para o canal da 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 na [estrutura da mensagem de chat](/chatlayer-documentation-pt-br/integrateandcode/chat-message-structure-for-apis.md).
* `ação`: 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 da conversa.

As 3 opções acima são executadas na ordem mostrada acima: as variáveis de sessão são definidas primeiro, depois as mensagens são enviadas e então você irá 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: 'mensagem aleatória 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 (regular ou poupança) para alguém. 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 o tipo de conta (conta corrente - conta poupança) 
  const account = account_synonyms[accountType];
 
  if( accounts[account].amount + accounts[accounthlimit — amount < ) {
    nextDialogstate = transactionNoMoney 
  } else { 
    // transferir o 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 de payload do corpo conforme definido no Chatlayer **API** step. 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 à solicitaçã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 nos dados de sessão dele sob o namespace account. Esses dados podem ser usados naquele próximo estado de diálogo.

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

Como solução alternativa, você também pode enviar essa mensagem de chat como resposta às solicitações do plugin de API usando a chave messages.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.