# Conectar instância ao WhatsApp

`POST /instance/connect`

Pasta: **Instancia**

## Autenticação

```http
token: {{token}}
```

## Descrição

# Conectar instância ao WhatsApp

Inicia a conexão da instância autenticada ao WhatsApp (QR Code/pareamento no modo companion, ou retoma o fluxo mobile se a conta já estiver registrada).

Use quando a instância estiver desconectada e você quiser autenticar ou reconectar a sessão.

## Endpoint

```http
POST {{baseUrl}}/instance/connect
```

## Autenticação

Header da instância:

```http
token: {{token}}
```

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `phone` | string | Não* | Número com DDI. Alias: `number`, `phoneNumber`. Em mobile, deve coincidir com o telefone vinculado. |
| `browser` | string | Não | Identidade do cliente companion (ex.: `chrome`). Ignorado no modo mobile. |
| `systemName` | string | Não | Nome do dispositivo exibido no WhatsApp. |

## Exemplo de Requisição

```bash
curl -X POST "{{baseUrl}}/instance/connect" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999999999",
  "browser": "chrome",
  "systemName": "GoZap Desktop"
}'
```

## Resposta de Sucesso

```json
{
  "success": true,
  "instance": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token": "inst_abc123",
    "name": "Atendimento",
    "status": "qr",
    "owner": "5511999999999",
    "connection_mode": "companion",
    "qrcode": "data:image/png;base64,..."
  },
  "runtime": {
    "present": true,
    "connected": false,
    "logged_in": false
  }
}
```

## Erros comuns

- `401` — header `token` ausente ou inválido
- `403` — cota de instâncias excedida (`quota exceeded`)
- `409` — telefone diferente do já vinculado à instância (`phone_bound`)
- `400` — payload JSON inválido

## Observações

*Em instâncias mobile já vinculadas, o telefone pode ser omitido e a API usa o `owner` salvo. Body é opcional (`bindOptionalJSON`).

## Corpo (exemplo)

```json
{
  "phone": "5511999999999",
  "browser": "chrome",
  "systemName": "GoZap Desktop"
}
```

## cURL

```bash
curl -X POST "{{baseUrl}}/instance/connect" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999999999",
  "browser": "chrome",
  "systemName": "GoZap Desktop"
}'
```

---

[Índice da pasta](./index.md) · [Índice geral](../index.md) · [UI](https://gozap.dev/docs?op=instancia/conectar-instancia-ao-whatsapp)