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

# Quick Start

> From zero to your first WhatsApp send: pick official or unofficial connection and follow the steps.

<Tip>
  This guide takes you from **account to first send**. Choose your mode below: **official** for production or **unofficial** to test quickly.
</Tip>

## In brief

* **Official:** Meta login in the dashboard, card in WhatsApp Manager, first send with an **approved template**
* **Unofficial:** create the instance, **scan the code on your phone**, send **free-form text**
* Both use the **same API**; only how you connect the number changes

Not sure which to pick? See [Connection modes](/en/whatsapp-api/como-funciona/modos-de-conexao).

## Before you start

* An **API Key** (`sk_live_...` or `sk_test_...` for sandbox)
* Instance and send permissions on the key. See [Scopes](/en/whatsapp-api/como-funciona/escopos-api-key)
* In examples, replace `sk_live_xxxxx` with your key and `https://api.notifique.dev` with your base URL if needed

<Note>
  Just getting started? Use `sk_test_...` and check results in the [Sandbox inbox](/en/guides/sandbox/index).
</Note>

***

<Tabs>
  <Tab title="Official connection">
    ### 1. Connect the number

    Three paths, pick what fits your integration:

    #### 1A, Via dashboard

    1. WhatsApp → New instance → **Official**
    2. Sign in with your Meta account and link the number
    3. When status is **active**, note the **instance id**

    #### 1B, Via API with a link for the customer

    For **remote onboarding** (no browser on your server): create a draft and send the link, the customer completes Meta login on the page.

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Official support",
      "mode": "OFFICIAL",
      "generateShareableLink": true
    }
    ```

    Expected response: **200** with a **PENDING** instance and the link:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Official support",
          "status": "PENDING",
          "phoneNumber": null
        },
        "connection": {
          "provider": "META_CLOUD",
          "status": "pending_signup"
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=...",
          "publicId": "..."
        }
      }
    }
    ```

    Send `shareableLink.hostedUrl` to the customer. When they finish, the instance becomes **active**.

    <Warning>
      Anyone with the link can connect or disconnect the instance. After use, rotate the secret with `POST /v1/whatsapp/instances/:instanceId/connect-page/rotate-secret`.
    </Warning>

    #### 1C, Via API with Meta credentials

    With **Embedded Signup** already done in the browser, create an already **active** official instance using the three Meta fields:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Official support",
      "mode": "OFFICIAL",
      "metaEmbeddedCode": "EMBEDDED_SIGNUP_CODE",
      "metaPhoneNumberId": "123456789012345",
      "metaWabaId": "987654321098765"
    }
    ```

    Expected response: **200** with an **active** instance:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Official support",
          "status": "ACTIVE",
          "phoneNumber": "5511999999999",
          "createdAt": "2025-02-20T12:00:00.000Z"
        }
      }
    }
    ```

    <Info>
      Summary: **dashboard** for the simplest path; **`generateShareableLink: true`** when someone else needs to complete Meta login; **`metaEmbeddedCode` + `metaPhoneNumberId` + `metaWabaId`** when you already have Embedded Signup data.
    </Info>

    ### 2. Add a card in WhatsApp Manager

    Meta bills **conversations** on your account. Without a card on file, production sends will not work.

    1. Open [WhatsApp Manager](https://business.facebook.com/wa/manage/)
    2. Go to **Payment settings**
    3. Add a valid card
    4. In the Notifique dashboard, confirm payment is active

    ### 3. Sync templates

    In the dashboard, use **Sync templates with Meta** (or create a new one). You need an **approved** template for first contact.

    Details: [Official Meta templates](/en/whatsapp-api/como-funciona/templates-oficiais-meta).

    ### 4. Send your first template

    Outside a recent chat, official requires an **approved template**:

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "INSTANCE_ID",
      "to": ["5511999999999"],
      "type": "template",
      "payload": {
        "templateId": "TEMPLATE_ID",
        "variables": { "1": "Maria" }
      }
    }
    ```

    Expected response: **202** with the message queued:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx789..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```

    ### 5. Chat after they reply

    When the customer **replies**, you have about **24 hours** to send free-form text or media:

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "INSTANCE_ID",
      "to": ["5511999999999"],
      "type": "text",
      "payload": {
        "message": "Hi! We got your message. How can we help?"
      }
    }
    ```

    Expected response: **202**:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx790..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```

    Outside that window, use a **template** again.
  </Tab>

  <Tab title="Unofficial connection">
    <Warning>
      Use unofficial for **tests and MVPs**. For real customers in production, prefer **official**.
    </Warning>

    ### 1. Create instance and pair

    Three paths, pick what fits your integration:

    #### 1A, Via dashboard

    1. WhatsApp → New instance (default is **unofficial**)
    2. Open the **code on your phone** shown in the dashboard
    3. Scan it in the WhatsApp app on the number that will send messages
    4. When status is **active**, note the **instance id**

    #### 1B, Via API with QR in your UI

    Creates the connection and returns the code for you to render:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "My test instance"
    }
    ```

    Expected response: **200** with the code in `connection.base64`:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "My test instance",
          "status": "PENDING",
          "phoneNumber": null,
          "createdAt": "2025-02-20T12:00:00.000Z"
        },
        "connection": {
          "pairingCode": null,
          "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
          "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
          "count": 1
        }
      }
    }
    ```

    Use `connection.base64` to show the **code** (image) and scan it in WhatsApp on the sending number.

    #### 1C, Via API with a link for the customer to scan

    Pass `generateShareableLink: true` to also get a link, useful when the person scanning is not on your screen:

    ```http theme={null}
    POST /v1/whatsapp/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "My test instance",
      "generateShareableLink": true
    }
    ```

    Expected response: **200** with QR **and** shareable link:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "My test instance",
          "status": "PENDING",
          "phoneNumber": null,
          "createdAt": "2025-02-20T12:00:00.000Z"
        },
        "connection": {
          "pairingCode": null,
          "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
          "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
          "count": 1
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=...",
          "publicId": "..."
        }
      }
    }
    ```

    Send `shareableLink.hostedUrl` for the customer to open and scan. When connected, status becomes **active**.

    <Warning>
      Anyone with the link can connect or disconnect the instance. After use, rotate the secret with `POST /v1/whatsapp/instances/:instanceId/connect-page/rotate-secret`.
    </Warning>

    <Info>
      Summary: **dashboard** for the simplest path; **API with QR** to embed the code in your UI; **`generateShareableLink: true`** when someone else needs to scan.
    </Info>

    <Warning>
      **New SIM or number?** Read [New numbers and SIMs](/en/whatsapp-api/como-funciona/politica-anti-banimento#new-numbers-and-sims) before your first production send.
    </Warning>

    ### 2. Refresh the code (if it expires)

    The code expires quickly. Request a new one **without creating a new instance**:

    ```http theme={null}
    GET /v1/whatsapp/instances/:instanceId/qr
    Authorization: Bearer sk_live_xxxxx
    ```

    Expected response: **200** with a fresh code:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "status": "PENDING",
        "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs..."
      }
    }
    ```

    You can also get a new code via [webhook](/en/whatsapp-api/como-funciona/eventos-do-webhooks) (`instance.qrcode`).

    ### 3. Send a text message

    With an **active** instance, send to numbers in international format (`5511999999999`):

    ```http theme={null}
    POST /v1/whatsapp/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "INSTANCE_ID",
      "to": ["5511999999999"],
      "type": "text",
      "payload": {
        "message": "Hi! Test message."
      }
    }
    ```

    Expected response: **202** with the message queued:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["clxx789..."],
        "status": "QUEUED",
        "scheduledAt": null
      }
    }
    ```
  </Tab>
</Tabs>

***

## After the first send

* Track **delivery and read** via [webhooks](/en/whatsapp-api/como-funciona/eventos-do-webhooks)
* Multiple numbers? See [Sending Pools](/en/whatsapp-api/como-funciona/sending-pools)
* Full fields and routes: **API reference** on the WhatsApp tab

## Next steps

* [Introduction](/en/whatsapp-api/como-funciona/introducao): channel overview
* [Connection modes](/en/whatsapp-api/como-funciona/modos-de-conexao): full comparison
* [Official Meta templates](/en/whatsapp-api/como-funciona/templates-oficiais-meta)
* [Anti-ban policy](/en/whatsapp-api/como-funciona/politica-anti-banimento)