> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.callix.dev.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.callix.dev.br/_mcp/server.

# Modelo de estados

Aqui está a inversão em relação a uma API REST convencional. A aplicação **não pergunta** se a chamada foi atendida. Ela **declara**: quando o estado for X, mostre isto. O SDK empurra o estado; a tela é uma consequência.

Os comandos — ficar disponível, entrar em pausa, discar, desligar — são **intenções sem retorno**. Não devolvem sucesso nem erro. Quem confirma é a próxima transição de estado. Um comando inválido no estado atual é descartado silenciosamente.

```mermaid
%%{init: {'theme': 'dark', 'flowchart': {'nodeSpacing': 60, 'rankSpacing': 70}}}%%
stateDiagram-v2
  direction TB
  [*] --> starting
  starting --> idle
  idle --> onBreak: enterOnBreak(id)
  onBreak --> idle: becomeAvailable()
  idle --> offline: goOffline()
  offline --> idle: becomeAvailable()
  idle --> callRinging: campanha entrega
  callRinging --> callInProgress: SDK atende
  idle --> manualCallSetup: makeManualCall(nº)
  manualCallSetup --> manualCallRinging
  manualCallRinging --> callInProgress: atendeu
  callInProgress --> afterCall: hangup()
  afterCall --> idle: finishAfterCall(...)
```

> **Note**
>
> Nove estados; a interface inteira é uma função de qual deles está ativo. Arestas menores ficaram de fora do diagrama para manter a leitura: `callRinging` volta para `idle` se a chamada cair antes de ser atendida, `goOffline()` vale a partir de quase todo estado, e as falhas aparecem como `startupError` (na inicialização) ou `manualCallFailed` (chamada manual que não completa).

## Os estados

| Estado              | Significa                                                             | O que a interface faz / pode fazer                                      |
| ------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `starting`          | subindo o softphone                                                   | tela de carregamento                                                    |
| `idle`              | disponível, aguardando                                                | libera o discador                                                       |
| `onBreak`           | em pausa                                                              | mostra qual pausa e o tempo                                             |
| `offline`           | fora de operação                                                      | botão de ficar disponível                                               |
| `callRinging`       | chamada de campanha chegando; o SDK busca o contexto e atende sozinho | abre a ficha do cliente quando `useCallOperatorCurrentCallInfo()` chega |
| `manualCallSetup`   | montando a chamada manual                                             | cancelar                                                                |
| `manualCallRinging` | chamando o destino                                                    | cancelar                                                                |
| `callInProgress`    | conversa estabelecida                                                 | espera, mudo, desligar, cronômetro                                      |
| `afterCall`         | pós-atendimento                                                       | formulário de desfecho + qualificação                                   |
| `manualCallFailed`  | chamada manual não completou                                          | mensagem e volta para `idle`                                            |
| `startupError`      | falha ao iniciar o operador                                           | mensagem e caminho de recuperação                                       |

## Onde a máquina de estados executa

A máquina roda no browser — o SDK embarca o `xstate` como dependência. Em execução medida, a transição entre o comando e a mudança de estado leva cerca de **5 ms**, rápido demais para uma ida e volta de rede. O estado local é **otimista** e a sincronização com o backend acontece por fora.

> **Warning**
>
> Na prática isso favorece a responsividade da interface, mas significa que **estado na tela não é prova de estado no servidor**: para auditoria de disponibilidade de agente, a fonte de verdade é o relatório da plataforma.