Quick Start

From zero to your first call in the queue in a few steps. First: contract a number, keep it active in the workspace (calls go out from that line), and have balance or credits — voice is billed per minute.

In short

Contract a number and activate it — that’s the line calls go out from (the from field).
Choose who calls and who receives (from and to). When answered, use type + payload — same as SMS and WhatsApp.
Track and control status via API or webhooks.

Context: Introduction. Scopes: API Key scopes. Number: Phone Numbers.

Before you start

Item	Why
Active number in the workspace	Without a contracted, active line, there’s no origin to dial from
Key with `voice:call`	Permission to originate calls
`voice:read` / `voice:control`	Only if you’ll query history or control a call in progress
Balance or credits	Billed per minute of answered call time

Authentication: Authorization: Bearer sk_live_... or x-api-key. Base URL: https://api.notifique.dev. Destination numbers in international format, digits only, without + (e.g. 5511999887766). The API normalizes internally.

Request body structure (`POST /v1/voice/calls`)

The canonical contract follows the same pattern as other channels: to, type, payload. Extra fields go at the root of the JSON or inside options — not inside payload.

Field	Where it goes	What it does
`from`	Root	Origin number or line id (active in the workspace)
`to`	Root	Array of destinations (up to 500)
`type`	Root	`speak`, `play`, `gather`, `ivr`, or `template`
`payload`	Root	Content for the `type` (text, audio, keypad menu, IVR…)
`record`	Root	`true` records the call (per-minute surcharge)
`amdMode`	Root	Voicemail detection: `disabled`, `detect`, or `premium`
`clientState`	Root	Your text to correlate with CRM or queue (returned in webhooks)
`metadata`	Root	Campaign tags (key-value strings)
`localization` / `i18n`	Root	Translate spoken text or keypad prompt
`options.webhook`	Inside `options`	HTTPS URL for this call only
`schedule`	Root	Dashboard only for now — see section 7

The API still accepts legacy root aliases (speakText, playAudioUrl, standalone gather), but prefer type + payload — it’s the documented pattern and matches other channels.

1. Make a call

1A — Via dashboard

Voice → New call
Which number you’re calling from and who will receive
When answered: automatic message (text or audio) or live call (WebRTC)
Optional: translate, schedule, record, or a webhook for this call only
Dispatch (or schedule)

IVR from the dashboard has been discontinued — use type: ivr in the API (IVR and flows).

1B — Via API v1

Scope: voice:call. Complete example — speak text, record, correlate with CRM, webhook for this call only, and metadata:

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

{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": {
    "text": "Hello! This is a Notifique test call.",
    "voice": "female-natural"
  },
  "record": false,
  "amdMode": "disabled",
  "clientState": "verification-campaign-42",
  "metadata": {
    "orderId": "8842",
    "source": "checkout"
  },
  "options": {
    "webhook": {
      "url": "https://api.yourcompany.com/hooks/voice-order-8842",
      "secret": "whsec_optional"
    }
  }
}

Response 202:

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

Save the messageIds to query and control each destination. Other type and payload (same structure — only type and payload content change):

What you want	`type`	`payload`
Speak text (TTS)	`speak`	`{ "text": "...", "voice": "female-natural" }`
Play audio from URL	`play`	`{ "audioUrl": "https://cdn.../notice.mp3" }`
”Press 1, 2…” menu	`gather`	`{ "gather": { "prompt": "...", "maxDigits": 1, "timeoutSecs": 15 } }`
Published IVR	`ivr`	`{ "flowId": "flow_abc123" }`

from accepts the workspace number id or E.164 — it must be active.

2. List and query

GET /v1/voice/calls?page=1&limit=20&direction=OUTBOUND
Authorization: Bearer sk_live_xxxxx

GET /v1/voice/calls/:id?includeEvents=true
Authorization: Bearer sk_live_xxxxx

Scope: voice:read. With includeEvents=true, the response includes the timeline (dialed, answered, ended…).

3. Control a call in progress

POST /v1/voice/calls/:id/actions/{action} — scope voice:control. The call must be answered.

POST /v1/voice/calls/clvoice1.../actions/speak
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "text": "Press 1 for sales or 2 for support.",
  "voice": "female-natural"
}

Action	What it does
`speak`	Speaks text (TTS)
`play`	Plays audio from URL
`gather`	Asks the customer to press keys
`transfer`	Transfers to another number
`record-start` / `record-stop`	Records a segment
`dtmf`	Sends tones
`hangup`	Ends the call

4. Download recording

GET /v1/voice/calls/:id/recordings/latest/download
Authorization: Bearer sk_live_xxxxx

Scope: voice:read. Webhook: voice.call.recording.ready.

5. Inbound calls

When someone calls your number, configure the line in Phone Numbers: forward, speak a message and hang up, or control via webhook.

6. Global webhooks vs webhook for this call

Global — register voice.call.* events in the workspace (Webhook events). This call only — use options.webhook in the body (public HTTPS + optional secret). Events for this call go to that URL instead of the workspace global webhooks for this call.

7. Schedule a dial

Dashboard — Schedule chip on New call (paid plan, within the workspace day limit). The API v1 route POST /v1/voice/calls does not accept schedule yet — voice scheduling via API is on the roadmap, aligned with other channels. In the dashboard, the body uses legacy fields (speakText at the root); in API v1, always use type: "speak" and payload.text.

8. Translate spoken text

At the root of the body, same as SMS and email:

{
  "from": "5511987654321",
  "to": ["5511999887766", "14155552671"],
  "type": "speak",
  "payload": {
    "text": "Hello! Your delivery arrives today.",
    "voice": "female-natural"
  },
  "localization": { "mode": "ai", "sourceLocale": "pt-BR" }
}

Manual mode — text per language in i18n (keys speakText and gatherPrompt):

{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "gather",
  "payload": {
    "gather": {
      "prompt": "Press 1 to confirm.",
      "maxDigits": 1,
      "timeoutSecs": 15
    }
  },
  "localization": { "mode": "manual", "sourceLocale": "pt-BR" },
  "i18n": {
    "en": {
      "speakText": "Hello! Your delivery arrives today.",
      "gatherPrompt": "Press 1 to confirm."
    }
  }
}

Details: Localization and i18n.

TTS voices

Identifier	Language
`female-natural`	Portuguese (BR), default
`male-natural`	Portuguese (BR)
`female-natural-en`	English (US)
`male-natural-en`	English (US)

Voice

Voice: Chamadas

Voice: Fluxos IVR

Phone numbers

Números de Telefone

Phone Numbers

In short

Before you start

Request body structure (`POST /v1/voice/calls`)

1. Make a call

1A — Via dashboard

1B — Via API v1

2. List and query

3. Control a call in progress

4. Download recording

5. Inbound calls

6. Global webhooks vs webhook for this call

7. Schedule a dial

8. Translate spoken text

TTS voices

Next steps

​In short

​Before you start

​Request body structure (POST /v1/voice/calls)

​1. Make a call

​1A — Via dashboard

​1B — Via API v1

​2. List and query

​3. Control a call in progress

​4. Download recording

​5. Inbound calls

​6. Global webhooks vs webhook for this call

​7. Schedule a dial

​8. Translate spoken text

​TTS voices

​Next steps

In short

Before you start

Request body structure (`POST /v1/voice/calls`)

1. Make a call

1A — Via dashboard

1B — Via API v1

2. List and query

3. Control a call in progress

4. Download recording

5. Inbound calls

6. Global webhooks vs webhook for this call

7. Schedule a dial

8. Translate spoken text

TTS voices

Next steps