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

# Início rápido

> Crie uma instância, conecte seu WhatsApp e envie sua primeira mensagem em menos de 5 minutos

Este guia cobre o caminho mínimo para ter uma instância conectada e trocar sua primeira mensagem.

## Pré-requisitos

<Check>Já possuir o **TokenAccount** da RyzeAPI.</Check>
<Check>Um celular com **WhatsApp Business** (ou o normal) instalado.</Check>

## 1. Defina seu token

```bash theme={null}
export Token_Account="seu-account-token"
```

Em todos os exemplos, a Base URL é sempre `https://ryzeapi.cloud`.

## 2. Crie uma instância

Use o seu TokenAccount para provisionar uma nova instância de WhatsApp.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{"name": "$Instance_Name"}'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(`https://ryzeapi.cloud/api/instance/new`, {
    method: "POST",
    headers: {
      "token": Token_Account,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "$Instance_Name" }),
  });
  const { data } = await res.json();
  console.log(data.token); // este é o TokenInstance
  ```

  ```python Python theme={null}
  import os, requests

  r = requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={"token": os.environ["Token_Account"]},
      json={"name": "minhaInstancia"},
  )
  print(r.json()["data"]["token"])  # este é o TokenInstance
  ```
</CodeGroup>

Resposta esperada:

```json theme={null}
{
  "success": true,
  "message": "Instance created successfully",
  "status": "created",
  "data": {
    "id": "01953abc-...",
    "name": "$Instance_Name",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "createdAt": "2026-04-21T12:00:00Z"
  }
}
```

<Warning>
  **Guarde o `data.token`**, este é o seu **TokenInstance**. A partir de agora, use ele (não o TokenAccount) para operar esta instância.
</Warning>

```bash theme={null}
export Token_Instance="a1b2c3d4-..."
```

## 3. Conecte ao WhatsApp

Use seu **TokenInstance** daqui em diante.

<Tabs>
  <Tab title="Via QR code">
    ```bash theme={null}
    curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name" \
      -H "token: $Token_Instance"
    ```

    A resposta traz:

    * `data.qrCodes`, strings que podem ser convertidas em QR
    * `data.qrImages`, PNGs em base64 prontos para exibir como imagem

    Escaneie no seu celular em **WhatsApp → Dispositivos vinculados → Vincular um dispositivo**.
  </Tab>

  <Tab title="Via pairing code">
    Ideal para ambientes sem câmera. Passe seu número no parâmetro `number`:

    ```bash theme={null}
    curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name?number=5511999999999" \
      -H "token: $Token_Instance"
    ```

    A resposta traz um código de 8 caracteres para digitar em **Dispositivos vinculados → Vincular com código**.
  </Tab>
</Tabs>

## 4. Confirme que está conectado

```bash theme={null}
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=$Instance_Name" \
  -H "token: $Token_Instance"
```

Aguarde o campo `status` da instância ficar igual a `"connected"`.

## 5. Envie sua primeira mensagem

```bash theme={null}
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Olá do RyzeAPI 👋"
  }'
```

## 6. Configure um webhook (opcional)

Para receber eventos em tempo real (mensagens chegando, status de entrega, etc.):

```bash theme={null}
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "default",
    "enabled": true,
    "url": "https://seu-servidor.com/webhook",
    "events": ["message.exchange", "group.flow", "instance.state"],
    "mediaBase64": false
  }'
```

<Tip>
  Cada instância aceita até **3 webhooks simultâneos** (por exemplo: produção, staging e um de log). Veja [Eventos](/pt/api/events/overview) para os 6 tipos disponíveis.
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Enviar mídia e recursos avançados" icon="image" href="/pt/api/messages/overview">
    Imagens, vídeos, áudios, documentos, botões, carrosséis, listas e formulários.
  </Card>

  <Card title="Gerenciar contatos e etiquetas" icon="address-book" href="/pt/api/chat/overview">
    Organize conversas, crie etiquetas, arquive, bloqueie e fixe chats.
  </Card>

  <Card title="Autenticação" icon="key" href="/pt/guide/authentication">
    Entenda TokenAccount vs TokenInstance em detalhe.
  </Card>

  <Card title="Tipos de erro" icon="triangle-exclamation" href="/pt/guide/errors">
    Como interpretar e tratar cada código HTTP.
  </Card>
</CardGroup>