Calls

A WhatsApp call in Notifique is the notice that rings the phone: you dial, say what you need (code, reminder, confirmation), and hang up — no IVR or call center to build.

In short

Today: unofficial connection (QR-paired number). Dial → speak/play audio → hang up.
Soon: the same API on the official (Meta) connection, keeping the same simple shape.
Use the same instance you already use for messages.
API key scope whatsapp:call (and whatsapp:call:read for read-only).

This first version is send and hang up: no IVR, transfer, or live conversation. It is meant to say something specific and end the call.

When to use

Situation	Use calls?
Verification code spoken to the user	Yes
Short reminder (appointment, invoice, delivery)	Yes
Live two-way support	No — use messages or traditional voice
Official (Meta) instance	Coming soon; today use unofficial

Modes: Connection modes.

What you can do

Place the call

POST /v1/whatsapp/calls with speak, play, or template.

List calls

GET /v1/whatsapp/calls with pagination and instance filter.

Get a call

GET /v1/whatsapp/calls/{id} with status, duration, and events.

Template with voice

type: "template" uses the channel template text/voice.

Call webhooks

whatsapp.call.initiated, answered, completed, failed… no polling.

Routes and fields: WhatsApp API reference (Calls section). Events: WhatsApp webhooks.

Before you start

Item	Required
Unofficial instance, ACTIVE	Yes (today)
Scope `whatsapp:call` on the key	Yes
Text (`speak`) or audio URL (`play`)	Yes

Not paired yet? WhatsApp Quick Start (unofficial tab). Scopes: API Key scopes. Replace sk_live_xxxxx with your key and {instanceId} with the instance id. Base URL: https://api.notifique.dev.

The API Key belongs to one workspace. On v1 do not send x-workspace-id.

1. Place a call (speak text)

Dials, synthesizes speech, and hangs up automatically.

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

{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "speak",
  "payload": {
    "text": "Hi! Your verification code is 1 2 3 4.",
    "voice": "female"
  }
}

202 response

{
  "success": true,
  "data": {
    "messageIds": ["clxx_call..."],
    "messageId": "clxx_call...",
    "status": "QUEUED",
    "count": 1,
  }
}

2. Play audio (`play`)

{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "play",
  "payload": {
    "mediaUrl": "https://example.com/notice.mp3"
  }
}

The URL must be public and point to an audio file.

3. Template with voice

If you already created a call-channel template (whatsapp_call), use type: "template":

{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "clxx_template...",
    "variables": {
      "1": "1234",
      "name": "Ana"
    }
  }
}

The API resolves text (and voice, if set) and continues as speak.

4. List calls

GET /v1/whatsapp/calls?page=1&limit=20&instanceId=clxx...
Authorization: Bearer sk_live_xxxxx

Optional params: page, limit, instanceId.

5. Get a call

GET /v1/whatsapp/calls/{id}?includeEvents=true
Authorization: Bearer sk_live_xxxxx

With includeEvents=true you get the timeline (QUEUED, INITIATED, COMPLETED, NO_ANSWER, FAILED, …).

Status and hangup

After queueing, the call moves through statuses like QUEUED → INITIATED → COMPLETED (or NO_ANSWER / FAILED / REJECTED). hangupReason explains the end (completed, hangup, no_answer, provider_error, …).

Next steps

Typed examples in OpenAPI (WhatsApp tab → Calls)
Connection modes
API Key scopes
For traditional PSTN voice, see the Voice API

WhatsApp API

Instances

Groups

Sending pools

Mensagens

Instâncias

Grupos

Chamadas

Calls

In short

When to use

What you can do

Place the call

List calls

Get a call

Template with voice

Call webhooks

Before you start

1. Place a call (speak text)

2. Play audio (`play`)

3. Template with voice

4. List calls

5. Get a call

Status and hangup

Next steps

​In short

​When to use

​What you can do

Place the call

List calls

Get a call

Template with voice

Call webhooks

​Before you start

​1. Place a call (speak text)

​2. Play audio (play)

​3. Template with voice

​4. List calls

​5. Get a call

​Status and hangup

​Next steps

In short

When to use

What you can do

Before you start

1. Place a call (speak text)

2. Play audio (`play`)

3. Template with voice

4. List calls

5. Get a call

Status and hangup

Next steps