Inicio rápido

De cero a tu primera llamada en cola en pocos pasos. Antes de todo: contrata un número, déjalo activo en el workspace (la llamada sale de esa línea) y ten saldo o créditos — la voz se cobra por minuto.

En resumen

Contrata un número y actívalo — es la línea desde la que sale la llamada (campo from).
Elige quién llama y quién recibe (from y to). Al contestar, usa type + payload — igual que SMS y WhatsApp.
Sigue y controla el estado por API o webhooks.

Contexto: Introducción. Ámbitos: Ámbitos de la API Key. Número: Números de teléfono.

Antes de empezar

Item	Por qué
Número activo en el workspace	Sin línea contratada y activa, no hay origen para marcar
Clave con `voice:call`	Permiso para originar llamadas
`voice:read` / `voice:control`	Solo si vas a consultar historial o controlar una llamada en curso
Saldo o créditos	Cobro por minuto de llamada contestada

Autenticación: Authorization: Bearer sk_live_... o x-api-key. URL base: https://api.notifique.dev. Números de destino en formato internacional, solo dígitos, sin + (ej.: 5511999887766). La API normaliza internamente.

Estructura del body (`POST /v1/voice/calls`)

El contrato canónico sigue el mismo patrón que los otros canales: to, type, payload. Los campos extra van en la raíz del JSON o en options — no dentro de payload.

Campo	Dónde va	Qué hace
`from`	Raíz	Número o id de la línea de origen (activo en el workspace)
`to`	Raíz	Array de destinos (hasta 500)
`type`	Raíz	`speak`, `play`, `gather`, `ivr` o `template`
`payload`	Raíz	Contenido según el `type` (texto, audio, menú de teclas, IVR…)
`record`	Raíz	`true` graba la llamada (sobrecargo por minuto)
`amdMode`	Raíz	Detección de buzón de voz: `disabled`, `detect` o `premium`
`clientState`	Raíz	Texto tuyo para correlacionar con CRM o cola (vuelve en los webhooks)
`metadata`	Raíz	Etiquetas de campaña (clave-valor, strings)
`localization` / `i18n`	Raíz	Traducir texto hablado o prompt de teclas
`options.webhook`	Dentro de `options`	URL HTTPS solo para esta llamada
`schedule`	Raíz	Solo en el panel hoy — ver sección 7

La API aún acepta alias legados en la raíz (speakText, playAudioUrl, gather suelto), pero prefiere type + payload — es el patrón documentado e igual a los otros canales.

1. Hacer una llamada

1A — Por el panel

Voz → Nueva llamada
Desde qué número vas a llamar y quién va a recibir
Al contestar: mensaje automático (texto o audio) o llamada en vivo (WebRTC)
Opcional: traducir, programar, grabar o webhook solo de esta llamada
Dispara (o programa)

El IVR por panel fue descontinuado — usa type: ivr en la API (IVR y flujos).

1B — Por la API v1

Ámbito: voice:call. Ejemplo completo — hablar texto, grabar, correlacionar con CRM, webhook solo de esta llamada y metadatos:

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

{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": {
    "text": "¡Hola! Esta es una llamada de prueba de Notifique.",
    "voice": "female-natural"
  },
  "record": false,
  "amdMode": "disabled",
  "clientState": "campana-verificacion-42",
  "metadata": {
    "orderId": "8842",
    "source": "checkout"
  },
  "options": {
    "webhook": {
      "url": "https://api.tuempresa.com/hooks/voice-pedido-8842",
      "secret": "whsec_opcional"
    }
  }
}

Respuesta 202:

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

Guarda los messageIds para consultar y controlar cada destino. Otros type y payload (misma estructura — solo cambian type y el contenido de payload):

Lo que quieres	`type`	`payload`
Hablar texto (TTS)	`speak`	`{ "text": "...", "voice": "female-natural" }`
Reproducir audio por URL	`play`	`{ "audioUrl": "https://cdn.../aviso.mp3" }`
Menú “presione 1, 2…”	`gather`	`{ "gather": { "prompt": "...", "maxDigits": 1, "timeoutSecs": 15 } }`
IVR publicado	`ivr`	`{ "flowId": "flow_abc123" }`

El from acepta el id del número en el workspace o el E.164 — debe estar activo.

2. Listar y consultar

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

Ámbito: voice:read. Con includeEvents=true, la respuesta trae la línea de tiempo (marcó, contestó, colgó…).

3. Controlar llamada en curso

POST /v1/voice/calls/:id/actions/{action} — ámbito voice:control. La llamada debe estar contestada.

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

{
  "text": "Presione 1 para ventas o 2 para soporte.",
  "voice": "female-natural"
}

Acción	Qué hace
`speak`	Habla texto (TTS)
`play`	Reproduce audio por URL
`gather`	Pide que el cliente presione teclas
`transfer`	Transfiere a otro número
`record-start` / `record-stop`	Graba un tramo
`dtmf`	Envía tonos
`hangup`	Cuelga la llamada

4. Descargar grabación

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

Ámbito: voice:read. Webhook: voice.call.recording.ready.

5. Llamadas recibidas (inbound)

Cuando alguien llama a tu número, configura la línea en Números de teléfono: reenviar, hablar mensaje y colgar, o controlar vía webhook.

6. Webhooks globales vs webhook de esta llamada

Globales — registra en el workspace los eventos voice.call.* (Eventos de webhooks). Solo de esta llamada — usa options.webhook en el body (HTTPS pública + secret opcional). Los eventos de esta llamada van a esa URL en lugar de los webhooks globales del workspace para esta llamada.

7. Programar marcado

Panel — chip Programar en Nueva llamada (plan de pago, dentro del límite de días del workspace). La ruta API v1 POST /v1/voice/calls aún no acepta schedule — el agendamiento por API de voz está en el roadmap, alineado a los otros canales. En el panel, el body usa campos legados (speakText en la raíz); en la API v1, usa siempre type: "speak" y payload.text.

8. Traducir el texto hablado

En la raíz del body, igual que SMS y correo:

{
  "from": "5511987654321",
  "to": ["5511999887766", "14155552671"],
  "type": "speak",
  "payload": {
    "text": "¡Hola! Tu entrega llega hoy.",
    "voice": "female-natural"
  },
  "localization": { "mode": "ai", "sourceLocale": "pt-BR" }
}

Modo manual — textos por idioma en i18n (claves speakText y gatherPrompt):

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

Detalles: Localización e i18n.

Voces TTS

Identificador	Idioma
`female-natural`	Portugués (BR), predeterminado
`male-natural`	Portugués (BR)
`female-natural-en`	Inglés (US)
`male-natural-en`	Inglés (US)

Voz

Voice: Chamadas

Voice: Fluxos IVR

Números de teléfono

Números de Telefone

Números de teléfono

En resumen

Antes de empezar

Estructura del body (`POST /v1/voice/calls`)

1. Hacer una llamada

1A — Por el panel

1B — Por la API v1

2. Listar y consultar

3. Controlar llamada en curso

4. Descargar grabación

5. Llamadas recibidas (inbound)

6. Webhooks globales vs webhook de esta llamada

7. Programar marcado

8. Traducir el texto hablado

Voces TTS

Próximos pasos

​En resumen

​Antes de empezar

​Estructura del body (POST /v1/voice/calls)

​1. Hacer una llamada

​1A — Por el panel

​1B — Por la API v1

​2. Listar y consultar

​3. Controlar llamada en curso

​4. Descargar grabación

​5. Llamadas recibidas (inbound)

​6. Webhooks globales vs webhook de esta llamada

​7. Programar marcado

​8. Traducir el texto hablado

​Voces TTS

​Próximos pasos

En resumen

Antes de empezar

Estructura del body (`POST /v1/voice/calls`)

1. Hacer una llamada

1A — Por el panel

1B — Por la API v1

2. Listar y consultar

3. Controlar llamada en curso

4. Descargar grabación

5. Llamadas recibidas (inbound)

6. Webhooks globales vs webhook de esta llamada

7. Programar marcado

8. Traducir el texto hablado

Voces TTS

Próximos pasos