Llamadas con mensaje - Insurance Boosters API

El paso voice.message realiza hasta 100 llamadas salientes desde una línea de voz existente. Cada llamada tiene su propio número destino y su propio texto para leer.

Este paso no crea ni compra líneas. Antes de usarlo necesitas el identificador de una línea activa que ya pertenezca a tu cuenta y tenga habilitadas las llamadas.

Antes de empezar

Pide estos valores al administrador de tu cuenta:

phoneLineId: identificador de la línea desde la que saldrán las llamadas.
voice, si quieres elegir una voz: identificador habilitado para tu cuenta.

La API de automatizaciones no crea líneas ni enumera voces. Si omites voice, se usa la voz predeterminada de tu cuenta.

Ejemplo mínimo

{
  "name": "Recordar cita",
  "actionKey": "voice.message",
  "input": {
    "phoneLineId": "<phone-line-id>",
    "calls": [
      {
        "to": "+525512345678",
        "script": "Hola María. Te recordamos que tu cita es mañana a las diez."
      }
    ]
  }
}

script es texto plano, no JavaScript. El servicio lo convierte a voz durante la llamada. Usa puntuación para producir pausas naturales.

Campos de entrada

`input`

Campo	Tipo	Requerido	Descripción
`phoneLineId`	`string`	Sí	Identificador de una línea existente, activa y habilitada para llamadas.
`calls`	`array` o plantilla	Sí	Entre 1 y 100 llamadas, o una plantilla completa que resuelva a ese arreglo.
`defaults`	`object`	No	Configuración común. Cada llamada puede sobrescribir voz, idioma, pausa y tiempo de timbrado.

Cada elemento de `calls`

Campo	Tipo	Requerido	Descripción
`to`	`string`	Sí	Número destino. Se recomienda E.164, por ejemplo `+525512345678`.
`script`	`string`	Sí	Texto que se leerá. De 1 a 3,000 caracteres; acepta plantillas `{{...}}`.
`voice`	`string`	No	Identificador de voz habilitado para tu cuenta.
`language`	`string`	No	Idioma y región, por ejemplo `es-MX`.
`pauseAfterMessageSeconds`	`integer`	No	Silencio antes de colgar, de 0 a 60 segundos.
`ringTimeoutSeconds`	`integer`	No	Tiempo máximo de timbrado, de 5 a 600 segundos.

`defaults`

Campo	Tipo	Predeterminado	Rango
`voice`	`string`	Voz predeterminada de la cuenta	Identificador válido de voz
`language`	`string`	`es-MX`	Código como `es-MX` o `en-US`
`pauseAfterMessageSeconds`	`integer`	`2`	0–60
`ringTimeoutSeconds`	`integer`	`30`	5–600
`pollIntervalSeconds`	`integer`	`5`	2–300
`completionTimeoutSeconds`	`integer`	`3600`	30–86400

Define la configuración común en defaults y agrega campos dentro de una llamada solo cuando esa llamada necesite un valor diferente.

Personalizar cada llamada

Las plantillas se resuelven antes de marcar. Puedes combinar texto fijo con datos del trigger o de pasos anteriores:

{
  "name": "Avisar a clientes",
  "actionKey": "voice.message",
  "input": {
    "phoneLineId": "<phone-line-id>",
    "defaults": {
      "language": "es-MX",
      "voice": "<voice-id>",
      "pauseAfterMessageSeconds": 3,
      "ringTimeoutSeconds": 25
    },
    "calls": [
      {
        "to": "{{trigger.body.primaryPhone}}",
        "script": "Hola {{trigger.body.primaryName}}. Tu póliza {{trigger.body.policyNumber}} está lista."
      },
      {
        "to": "{{trigger.body.secondaryPhone}}",
        "script": "Hola {{trigger.body.secondaryName}}. Tenemos una actualización sobre la póliza {{trigger.body.policyNumber}}.",
        "voice": "<alternate-voice-id>"
      }
    ]
  }
}

No repitas el mismo número dentro del paso. Los destinos literales duplicados se rechazan al guardar la definición. Si los números provienen de plantillas, se comprueban al ejecutar, después de normalizarlos.

Usar una lista creada por otro paso

Si un paso anterior devuelve el arreglo completo, asigna una plantilla completa a calls. No la mezcles con texto adicional:

{
  "name": "Llamar a la lista preparada",
  "actionKey": "voice.message",
  "input": {
    "phoneLineId": "<phone-line-id>",
    "calls": "{{steps.0.output.calls}}",
    "defaults": {
      "language": "es-MX"
    }
  }
}

El valor de steps.0.output.calls debe tener esta forma:

[
  {
    "to": "+525512345678",
    "script": "Hola María. Tu pago vence mañana."
  },
  {
    "to": "+525587654321",
    "script": "Hola Luis. Tu pago vence el viernes."
  }
]

Qué ocurre durante la ejecución

El paso continúa activo mientras las llamadas se procesan. La automatización avanza al siguiente paso cuando todas llegan a un estado final o cuando se alcanza completionTimeoutSeconds. pollIntervalSeconds controla cada cuánto se consultan estados y se programan llamadas pendientes. Para listas grandes, configura completionTimeoutSeconds con margen para programar todas las llamadas, esperar el timbrado y reproducir los mensajes. Cada llamada también aparece en la sección Llamadas de la plataforma, asociada con la línea elegida. Desde ahí puedes consultar su destino, estado y duración disponible.

Publicar o ejecutar el mismo workflow de nuevo crea un nuevo grupo de llamadas. Usa tus propios controles de negocio si un evento no debe notificar dos veces al mismo contacto.

Salida

{
  "total": 3,
  "completed": 1,
  "failed": 2,
  "calls": [
    {
      "to": "+525512345678",
      "callSid": "<call-id>",
      "status": "completed",
      "durationSeconds": 18
    },
    {
      "to": "+525587654321",
      "callSid": "<call-id>",
      "status": "busy"
    },
    {
      "to": "+525500000000",
      "status": "dispatch-failed",
      "error": "Descripción del error"
    }
  ]
}

Campo	Descripción
`total`	Número de llamadas solicitadas.
`completed`	Llamadas que terminaron con estado `completed`.
`failed`	Todas las llamadas que no terminaron como `completed`.
`calls[].to`	Destino normalizado a E.164.
`calls[].callSid`	Identificador de la llamada, cuando llegó a crearse.
`calls[].status`	Resultado final o estado operativo de esa llamada.
`calls[].durationSeconds`	Duración reportada, cuando está disponible.
`calls[].error`	Explicación cuando la llamada no pudo despacharse o terminó por timeout.

Una llamada ocupada o sin respuesta no hace fallar por sí sola la ejecución del workflow. Revisa calls[].status o failed en el siguiente paso para decidir qué hacer.

Guardar un resumen en `context`

Agrega capture al mismo paso si varios pasos posteriores necesitan los contadores:

{
  "name": "Recordar citas",
  "actionKey": "voice.message",
  "input": {
    "phoneLineId": "<phone-line-id>",
    "calls": "{{steps.0.output.calls}}"
  },
  "capture": {
    "completedCalls": {
      "from": "response.body",
      "path": "completed"
    },
    "failedCalls": {
      "from": "response.body",
      "path": "failed"
    }
  }
}

Después puedes usar {{context.completedCalls}} y {{context.failedCalls}}.

Estados habituales

Estado	Significado
`completed`	La llamada terminó después de reproducir las instrucciones.
`busy`	El destino estaba ocupado.
`no-answer`	Nadie contestó dentro del tiempo configurado.
`failed`	El servicio de voz no pudo completar la llamada.
`canceled`	La llamada se canceló antes de completarse.
`dispatch-failed`	No fue posible solicitar la llamada. Consulta `error`.
`dispatch-unknown`	No se repitió una solicitud cuyo resultado era incierto, para evitar marcar dos veces.
`timed-out`	El workflow dejó de esperar antes de recibir un estado final. La llamada puede actualizarse después en Llamadas.

Mientras el paso sigue activo, la sección Llamadas también puede mostrar estados intermedios como queued, ringing o in-progress.

calls[].error es texto diagnóstico y puede estar en inglés. No automatices decisiones comparando ese texto; usa calls[].status.

Usar la salida en el siguiente paso

{
  "name": "Reportar resultado",
  "actionKey": "http.request",
  "input": {
    "method": "POST",
    "url": "https://ejemplo.com/hooks/resultado-llamadas",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "total": "{{steps.1.output.total}}",
      "completadas": "{{steps.1.output.completed}}",
      "fallidas": "{{steps.1.output.failed}}",
      "llamadas": "{{steps.1.output.calls}}"
    }
  }
}

En este ejemplo steps.1 supone que voice.message ocupa la posición 1 del arreglo steps. Ajusta el índice a la posición real de tu paso.

Errores frecuentes

Situación	Qué revisar
`VOICE_MESSAGE_INVALID_DESTINATION`	Incluye el código de país y usa E.164.
`VOICE_MESSAGE_DUPLICATE_DESTINATION`	Elimina números repetidos del arreglo.
`Phone line not found`	Confirma que `phoneLineId` existe y pertenece a tu cuenta.
`VOICE_MESSAGE_PHONE_LINE_UNAVAILABLE`	Confirma que la línea está activa y permite llamadas.
`VOICE_MESSAGE_TWIML_TOO_LARGE`	Reduce `script`; el límite aplica a las instrucciones generadas y los caracteres especiales pueden ocupar más espacio.
`Invalid voice.message step ... duplicate literal destinations`	Elimina números literales repetidos antes de guardar la automatización.
Voz o idioma inválidos	Usa una combinación de `voice` y `language` habilitada para tu cuenta.
Todas quedan en `timed-out`	Aumenta `completionTimeoutSeconds` si tu lista tarda en procesarse.

​Antes de empezar

​Ejemplo mínimo

​Campos de entrada

​input

​Cada elemento de calls

​defaults

​Personalizar cada llamada

​Usar una lista creada por otro paso

​Qué ocurre durante la ejecución

​Salida

​Guardar un resumen en context

​Estados habituales

​Usar la salida en el siguiente paso

​Errores frecuentes

​Relacionado

Antes de empezar

Ejemplo mínimo

Campos de entrada

`input`

Cada elemento de `calls`

`defaults`

Personalizar cada llamada

Usar una lista creada por otro paso

Qué ocurre durante la ejecución

Salida

Guardar un resumen en `context`

Estados habituales

Usar la salida en el siguiente paso

Errores frecuentes

Relacionado