> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar status

> Consulta se a sessão do usuário está em execução, aguardando input ou idle

## Descrição

Retorna o status da sessão associada a um `referenceId` para um agente com canal personalizado.

Este endpoint é uma consulta **controlada**: exige a mesma assinatura HMAC que [enviar interação](/pt/api/custom-channel/enviar-interacao). A autenticação `credentials.auth` do canal **não** é exigida aqui (aplica-se apenas às chamadas de saída para o seu webhook).

## Endpoint

```
POST https://chatbot.jelou.ai/v1/custom-channel/{botId}/status
```

## Parâmetros de rota

<ParamField path="botId" type="string" required>
  Identificador do agente.
</ParamField>

## Parâmetros do corpo

<ParamField body="referenceId" type="string" required>
  Mesmo identificador de usuário usado ao [enviar a interação](/pt/api/custom-channel/enviar-interacao).
</ParamField>

## Autenticação / assinatura

Inclua o header obrigatório:

```
X-Jelou-Signature: sha256=<HMAC_HEX>
```

A assinatura é calculada sobre o **raw body** exato da requisição (HMAC-SHA256). Detalhes em [Assinatura HMAC](/pt/api/custom-channel/assinatura-hmac).

## Valores de `status`

| Valor           | Significado                                |
| --------------- | ------------------------------------------ |
| `running`       | Há uma execução do fluxo em andamento.     |
| `pending_input` | O agente aguarda uma resposta do usuário.  |
| `idle`          | Não há execução ativa nem espera de input. |

## Exemplo de solicitação

```bash cURL theme={null}
curl --request POST \
  --url https://chatbot.jelou.ai/v1/custom-channel/BOT_ID/status \
  --header 'Content-Type: application/json' \
  --header 'X-Jelou-Signature: sha256=HMAC_HEX' \
  --data '{
    "referenceId": "user-123"
  }'
```

## Respostas

| Código | Status                | Descrição                                            |
| ------ | --------------------- | ---------------------------------------------------- |
| 200    | OK                    | Status retornado.                                    |
| 400    | Bad Request           | Falta `referenceId`.                                 |
| 401    | Unauthorized          | Assinatura inválida, ausente ou chave não resolvida. |
| 500    | Internal Server Error | Não foi possível ler o status.                       |

## Exemplo de resposta

```json theme={null}
{
  "status": "pending_input"
}
```