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

# POST /v1/messages/typing — Indicador de Digitando / Gravando

> Mostre um indicador ao vivo de 'digitando' ou 'gravando' para um contato, sem enviar mensagem.

# Indicador de Digitando / Gravando

```text theme={null}
POST https://pilotstatus.com.br/v1/messages/typing
```

Mostra ao contato um indicador ao vivo de **"digitando"** ou **"gravando"** **sem enviar mensagem**. O indicador some quando uma mensagem é enviada, ou após um timeout do provedor (\~25s na Meta).

<Note>
  O "digitando" **também é mostrado automaticamente** antes de todo envio conversacional (em números Meta e Evolution). Use este endpoint apenas para mostrar o indicador de forma independente de um envio.
</Note>

## Cabeçalhos

* `Content-Type: application/json`
* `x-api-key: ps_...` (ou `x-api-key-id: <api_key_id>`) — uma chave com **escopo de número**

## Corpo

<ParamField body="to" type="string" required>
  Telefone do contato em **E.164** ou só dígitos — a quem mostrar o indicador.
</ParamField>

<ParamField body="state" default="typing" type="string">
  `typing` (padrão), `recording` ou `paused`.
</ParamField>

## Exemplo

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/messages/typing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -d '{ "to": "5511999999999", "state": "typing" }'
```

## Resposta (200)

```json theme={null}
{ "ok": true, "sent": true, "provider": "META", "effectiveState": "typing" }
```

<ResponseField name="sent" type="boolean">
  `true` quando o indicador foi despachado ao contato.
</ResponseField>

<ResponseField name="provider" type="string">
  `META` ou `EVOLUTION`.
</ResponseField>

<ResponseField name="effectiveState" type="string">
  O indicador realmente mostrado. A Meta rebaixa `recording` para `typing`.
</ResponseField>

<ResponseField name="note" type="string">
  Presente quando o indicador foi adaptado ou não pôde ser mostrado (ex.: conversa Meta sem mensagem recebida para ancorar).
</ResponseField>

## Comportamento por provedor

<Warning>
  A **Meta Cloud API** não tem endpoint de presença próprio. O "digitando" é emitido como um recibo de leitura + indicador na **última mensagem recebida** do contato, então em números Meta:

  * precisa de uma **mensagem recebida recente** para ancorar (senão `sent:false`);
  * **não existe variante "gravando"** — `recording` aparece como `typing`;
  * `paused` é **no-op**.
</Warning>

Números **Evolution** (Pilot Status web / GO) relaiam `composing` / `recording` / `paused` nativamente.

## Erros comuns

| Status | Significado                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `400`  | JSON inválido, `state` inválido, ou a chave não está vinculada a um número (`code: NUMBER_NOT_FOUND`) |
| `401`  | Header de API key ausente/inválido (`x-api-key` / `x-api-key-id`)                                     |
| `403`  | Chave com escopo de tenant usada em endpoint por número                                               |
| `404`  | Nenhuma conversa com `to` (`code: CONVERSATION_NOT_FOUND`)                                            |