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

# Instâncias

> Entenda as instâncias do WhatsApp no Cawme

## O que é uma instância?

Uma instância representa um número de telefone do WhatsApp conectado ao Cawme. Cada instância:

* Possui um `id` único com prefixo `inst_`
* Pertence a uma única conta de usuário
* Mantém uma fila de chamadas independente
* Passa por um ciclo de vida com diferentes status

## Ciclo de vida da instância

```
CREATED → CONFIGURED → ACTIVE
                           ↓
                        DELETED
```

| Status       | Descrição                                                           |
| ------------ | ------------------------------------------------------------------- |
| `CREATED`    | Instância registrada, mas sem número de WhatsApp vinculado          |
| `CONFIGURED` | QR code escaneado, número de WhatsApp vinculado                     |
| `ACTIVE`     | Instância ativa e pronta para realizar chamadas                     |
| `DELETED`    | Soft-delete; não está mais acessível (não foi removida fisicamente) |

## Vinculando um número de WhatsApp

Após criar uma instância, chame o endpoint de configuração para obter o QR code:

```bash theme={null}
curl https://cawme.com/api/v1/instances/inst_abc123/configure \
  -H "Authorization: Bearer <token>"
```

Decodifique o valor de `qrCodeBase64` em uma imagem e escaneie com o WhatsApp no seu celular.

## Fila de chamadas

Ao buscar uma instância, a resposta inclui sua `callQueue` ativa — todas as chamadas atualmente nos status `QUEUED`, `RINGING` ou `IN_PROGRESS`.

```json theme={null}
{
  "id": "inst_abc123",
  "name": "sales-team-a",
  "status": "ACTIVE",
  "callQueue": [
    {
      "id": "call_xyz789",
      "type": "FIXED_TTS",
      "status": "QUEUED"
    }
  ]
}
```

## Idempotência

Se você enviar uma chamada para uma instância que já possui uma chamada ativa (nos status `QUEUED`, `RINGING` ou `IN_PROGRESS`), a API retorna a chamada existente em vez de criar uma duplicata. Isso protege contra envios duplicados causados por retentativas de rede ou re-renderizações do cliente.

<CardGroup cols={2}>
  <Card title="Criar Instância" icon="plus" href="/api-reference/instances/create">
    POST /v1/instances
  </Card>

  <Card title="Configurar Instância" icon="qrcode" href="/api-reference/instances/configure">
    GET /v1/instances/:instanceId/configure
  </Card>

  <Card title="Listar Instâncias" icon="list" href="/api-reference/instances/list">
    GET /v1/instances
  </Card>

  <Card title="Deletar Instância" icon="trash" href="/api-reference/instances/delete">
    DELETE /v1/instances/:instanceId
  </Card>
</CardGroup>