Quick Start

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

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.

Before you start

An API Key (sk_live_... or sk_test_... for sandbox)
Instance and send permissions on the key. See Scopes
In examples, replace sk_live_xxxxx with your key and https://api.notifique.dev with your base URL if needed

Just getting started? Use sk_test_... and check results in the Sandbox inbox.

Official connection
Unofficial connection

1. Connect the number

Three paths, pick what fits your integration:

1A, Via dashboard

WhatsApp → New instance → Official
Sign in with your Meta account and link the number
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.

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Official support",
  "mode": "OFFICIAL",
  "generateShareableLink": true
}

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

{
  "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.

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.

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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Official support",
  "mode": "OFFICIAL",
  "metaEmbeddedCode": "EMBEDDED_SIGNUP_CODE",
  "metaPhoneNumberId": "123456789012345",
  "metaWabaId": "987654321098765"
}

Expected response: 200 with an active instance:

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

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.

2. Add a card in WhatsApp Manager

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

Open WhatsApp Manager
Go to Payment settings
Add a valid card
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.

4. Send your first template

Outside a recent chat, official requires an approved template:

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "INSTANCE_ID",
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "TEMPLATE_ID",
    "variables": { "1": "Maria" }
  }
}

Expected response: 202 with the message queued:

{
  "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:

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

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

Expected response: 202:

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

Outside that window, use a template again.

Use unofficial for tests and MVPs. For real customers in production, prefer official.

1. Create instance and pair

Three paths, pick what fits your integration:

1A, Via dashboard

WhatsApp → New instance (default is unofficial)
Open the code on your phone shown in the dashboard
Scan it in the WhatsApp app on the number that will send messages
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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "My test instance"
}

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

{
  "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:

POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "My test instance",
  "generateShareableLink": true
}

Expected response: 200 with QR and shareable link:

{
  "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.

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.

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

New SIM or number? Read New numbers and SIMs before your first production send.

2. Refresh the code (if it expires)

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

GET /v1/whatsapp/instances/:instanceId/qr
Authorization: Bearer sk_live_xxxxx

Expected response: 200 with a fresh code:

{
  "success": true,
  "data": {
    "status": "PENDING",
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs..."
  }
}

You can also get a new code via webhook (instance.qrcode).

3. Send a text message

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

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "INSTANCE_ID",
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Hi! Test message."
  }
}

Expected response: 202 with the message queued:

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

After the first send

Track delivery and read via webhooks
Multiple numbers? See Sending Pools
Full fields and routes: API reference on the WhatsApp tab

WhatsApp API

In brief

Before you start

1. Connect the number

1A, Via dashboard

1B, Via API with a link for the customer

1C, Via API with Meta credentials

2. Add a card in WhatsApp Manager

3. Sync templates

4. Send your first template

5. Chat after they reply

1. Create instance and pair

1A, Via dashboard

1B, Via API with QR in your UI

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

2. Refresh the code (if it expires)

3. Send a text message

After the first send

Next steps

​In brief

​Before you start

​1. Connect the number

​1A, Via dashboard

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

​1C, Via API with Meta credentials

​2. Add a card in WhatsApp Manager

​3. Sync templates

​4. Send your first template

​5. Chat after they reply

​1. Create instance and pair

​1A, Via dashboard

​1B, Via API with QR in your UI

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

​2. Refresh the code (if it expires)

​3. Send a text message

​After the first send

​Next steps

In brief

Before you start

1. Connect the number

1A, Via dashboard

1B, Via API with a link for the customer

1C, Via API with Meta credentials

2. Add a card in WhatsApp Manager

3. Sync templates

4. Send your first template

5. Chat after they reply

1. Create instance and pair

1A, Via dashboard

1B, Via API with QR in your UI

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

2. Refresh the code (if it expires)

3. Send a text message

After the first send

Next steps