VOZ

API Mensajes de VOZ (7.0)

Download OpenAPI specification:Download

URL: /contacto.php Terms of Service

INTRODUCCION

API de integración de llamadas de voz desde aplicaciones mediante peticiones https. El sistema llama al destinatario, reproduce el mensaje que usted indica convertido a voz y, si lo desea, recoge la respuesta del destinatario: pulsaciones de teclas (menú IVR), un PIN o una transferencia a otro teléfono.


Al final de este documento, después de las funciones, tiene dos anexos: el Anexo A, con una colección de ejemplos completos por tipo de uso, y el Anexo B, con los reports que llegan según cómo acabe cada llamada.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las peticiones, por seguridad, deben realizarse en POST y con protocolo HTTPS seguro.



Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.

USO PERMITIDO — LEA ESTO ANTES DE INTEGRAR


NO SE PERMITEN LLAMADAS MASIVAS DE MARKETING. Esta API está diseñada para servicios con valor añadido para quien recibe la llamada: códigos PIN/OTP, alertas urgentes, avisos y confirmaciones, llamadas automáticas a empleados y, en general, cualquier comunicación transaccional. Está terminantemente prohibido generar llamadas que el destinatario pueda considerar spam.


Cualquier denuncia por este motivo podrá suponer el bloqueo temporal del número llamante y la apertura de una investigación. Al utilizar el servicio, el titular del número (la empresa propietaria) se compromete a no emplearlo con esos fines y se hace totalmente responsable de su utilización.

A TENER EN CUENTA


Número llamante: Las llamadas salen SIEMPRE desde un número de voz contratado en la plataforma. Puede contratarlo desde su panel (Llamadas de VOZ -> Mis Números) en España, Portugal, México y otros países. No es posible llamar mostrando un número que no sea suyo: la normativa y el operador lo rechazan.


Créditos: Las llamadas se cobran por minuto iniciado: al encolarse se reserva el primer minuto y al terminar se ajusta al tiempo real que ha durado. Una llamada cancelada antes de cursarse devuelve los créditos íntegros.


Horario de llamada: HORAINICIODIARIA y HORALIMITEDIARIA definen la franja en la que SE PUEDE llamar. Una llamada programada fuera de esa franja no se pierde: se reprograma para la hora de inicio siguiente. Respete la normativa del país de destino sobre horarios de llamadas comerciales.


Grabación: Con GRABAR=1 se graba la llamada completa desde el descuelgue; la grabación queda en su cuenta (Llamadas de VOZ -> Grabaciones) y se cobra por minuto grabado. Informar al destinatario de que la llamada se graba es responsabilidad suya: hágalo en el propio MENSAJE.


Conexiones en vacío: Una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión. Evite conexiones repetidas con datos erróneos o consultas 'en vacío' del mismo report.


Respuesta de las peticiones: Todas las funciones disponen del parámetro 'RESP', que define el formato de la respuesta: TXT, JSON o XML. Se recomienda definirlo siempre; si no lo define, la respuesta sale en texto plano (TXT).

EL MENSAJE

El texto del parámetro MENSAJE se convierte a voz en el idioma que indique en LENGUAJE. Además del texto, admite:


- Variables: escriba (Nombre) en el texto y envíe su valor en VARIABLES para cada destinatario. Puede usar los nombres de variable que quiera.
- (PAUSA:n) silencio de n segundos. Ejemplo: Su cita es mañana (PAUSA:1) a las diez. (WAIT:n) hace lo mismo.
- (SPELL:texto) deletrea el texto carácter a carácter, para códigos y referencias.
- (MP3:nombre.mp3) reproduce en ese punto un audio de la biblioteca de su cuenta (los que suba desde el panel; obtenga la lista con GetPlantillasVOZ). Un audio que no esté en su biblioteca se ignora y la locución sigue: no se admiten audios de otras webs.


Los marcadores van entre paréntesis y se pueden mezclar con el texto tantas veces como quiera.

LLAMADAS INTERACTIVAS

Con el parámetro IVR puede pedir una respuesta al destinatario:


IVR=1 (menú de teclas): tras el mensaje se reproduce la locución del menú ('pulse 1 para confirmar, 2 para hablar con un agente...') y, según la tecla pulsada, el sistema ejecuta la acción que usted haya configurado: repetir el mensaje, avisar a una URL suya, enviar un email, transferir la llamada a otro teléfono, dar de baja al destinatario o colgar. Cada opción puede llevar además una locución previa y otra final, y puede volver al menú en lugar de colgar.


IVR=2 (solicitud de PIN): el sistema pide un código de varios dígitos terminado en almohadilla y, cuando el destinatario lo introduce, lo envía a la URL o al correo que usted indique. Es la forma habitual de validar una operación por teléfono.


IVR=3 (asistente de IA): en cuanto termina el mensaje, la llamada pasa a una conversación con el asistente de IA entrenado con la información de su cuenta: el destinatario habla con normalidad, el asistente le entiende y le responde. Si no sabe resolver la consulta, transfiere la llamada al teléfono que usted indique. El minuto de conversación con IA tiene un coste adicional en créditos.


Las pulsaciones se le comunican además como report (estado 503), con la tecla o el PIN en el campo Digitos.

REUTILIZAR LO QUE YA TIENE EN SU CUENTA

No hace falta mandar el menú entero en cada petición ni volver a grabar los audios:


- Menús guardados: los que haya creado con el editor de IVR del panel se usan indicando su nombre o su identificador en PLANTILLAIVR.
- Escenarios: un escenario se puede indicar en ESCENARIO, pero tenga en cuenta que los escenarios son de recepción (modo de entrada, horario, buzón, música de espera...): de un escenario aquí sólo se aprovecha su menú, que es la única parte que significa lo mismo en una llamada saliente. El resto se ignora.
- Audios: los mp3 que haya subido a la biblioteca de su cuenta se reproducen escribiendo (MP3:nombre.mp3) dentro del MENSAJE.


Con la función GetPlantillasVOZ obtiene todo eso tal y como lo tiene guardado y, además, los números que puede usar como REMITENTE y las extensiones y grupos de salto con sus valores ya escritos para las acciones 8 y 9 del menú. Una sola llamada antes de empezar y no hay que adivinar nada.

LLAMAR DESDE UNA EXTENSIÓN (CLICK-TO-CALL)

Si tiene la Centralita Virtual, la función LlamarVOZ hace otra cosa distinta a todo lo anterior: no reproduce un mensaje, sino que pone en contacto a un agente suyo con un número. Suena primero el teléfono del agente (todos los aparatos de su extensión) y, en cuanto descuelga, se marca el destino y se puentean las dos. Es lo que permite llamar desde su CRM sin instalar nada: la llamada sale de la centralita con el número de la empresa, queda en el historial y se cobra como cualquier saliente. Si el agente no descuelga, no se marca a nadie y no cuesta nada.

RECEPCIÓN DE REPORTS

Active en su panel (Configuración -> API de desarrollo) la URL de su servidor donde desea recibir los cambios de estado. A partir de ese momento recibirá una petición POST por cada cambio de estado de cada llamada que haya enviado con REPORT=1: cuando suena, cuando descuelgan, cuando pulsan una tecla, cuando se deja el mensaje en el contestador y cuando termina, con la duración real. El formato está descrito en la función «Recepción de reports y eventos de las llamadas», y en el Anexo B tiene qué reports llegan según cómo acabe cada llamada.


Ésta es la forma de seguir sus llamadas: configure la URL y déjela funcionando antes de empezar a llamar. Los reports salen siempre a esa URL, para que haya un único sitio donde mirar cuando algo no llega.

basicAuth

Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Enviar llamada de voz

/EnviarVOZ

Función de envío de llamadas de voz desde aplicaciones. Encola una llamada por destinatario y devuelve el identificador de cada una.

ATENCIÓN: configure la recepción de reports en su panel si desea recibir el estado de las llamadas y las pulsaciones del destinatario en tiempo real en un script de su web.

Authorizations:
basicAuth
query Parameters
Mensaje
required
string
Example: Mensaje=Hola (Nombre), le recordamos su cita de mañana (PAUSA:1) a las diez de la mañana.

Texto que se convierte a voz y se reproduce al destinatario. Admite variables del tipo (Nombre) y los marcadores (PAUSA:n) o (WAIT:n) (silencio de n segundos), (SPELL:texto) (deletrear carácter a carácter) y (MP3:nombre.mp3) (reproducir en ese punto un audio de la biblioteca de su cuenta).

Remitente
required
string
Example: Remitente=34910123456

Número que aparece como llamante, en formato internacional sin el signo + ni espacios. Debe ser un número de voz contratado en su cuenta (Llamadas de VOZ -> Mis Números). Si el número no es suyo la petición se rechaza con Res=-19.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Nombre":"Pedro Pérez","Telefono":"34600000001","Variables":[{"Nombre":"Nombre","Valor":"Pedro"},{"Nombre":"Importe","Valor":"120 euros"}]}]

Array JSON con los destinatarios de la llamada. Cada elemento admite NOMBRE (opcional), TELEFONO (obligatorio, en formato internacional sin + ni espacios) y VARIABLES (opcional) para personalizar el mensaje por destinatario.

Fecha
string
Example: Fecha=2026-09-15 10:30

Fecha en la que queda programada la llamada. Por defecto "", que significa llamar inmediatamente. Formato Año-Mes-día hora:minuto. La referencia horaria es CET/CEST (zona horaria de España).

Lenguaje
string
Example: Lenguaje=es-ES:1

Idioma y voz de la locución, en formato locale:genero donde género es 1 (mujer) o 2 (hombre). Locales disponibles: es-ES, es-MX, es-US, pt-PT, pt-BR, en-US, en-GB, fr-FR, de-DE, it-IT y ca-ES. Si el locale no está soportado la petición se rechaza con Res=-20.

Detectarcontestador
string
Enum: 0 1 2 3
Example: Detectarcontestador=0

Qué hacer cuando la llamada la contesta un contestador automático:
0 Continuar y dejar el mensaje (opción por defecto).
1 Colgar y reintentar más tarde las veces indicadas en REINTENTOS.
2 Colgar y reintentar; si tras agotar los reintentos vuelve a responder un contestador, dejar el mensaje.
3 Esperar la señal del contestador y dejar el mensaje después del pitido.

Reintentos
integer
Example: Reintentos=3

Número de veces que se reintenta la llamada si no contestan (de 0 a 10). Con 0 no se reintenta.

Intervalo
integer
Example: Intervalo=60

Minutos de espera entre reintentos (de 5 a 1440).

Fechalimite
string
Example: Fechalimite=2026-09-30 20:00

Fecha límite de los reintentos: pasada esa fecha ya no se vuelve a llamar. Por defecto, un mes desde el envío. Formato Año-Mes-día hora:minuto.

Horainiciodiaria
string
Example: Horainiciodiaria=10:00

Hora a partir de la cual SE PUEDE llamar cada día, en formato HH:MM. Una llamada que caiga fuera de la franja permitida se reprograma para esta hora.

Horalimitediaria
string
Example: Horalimitediaria=22:00

Hora a partir de la cual NO se llama cada día, en formato HH:MM.

Ivr
string
Enum: 0 1 2 3
Example: Ivr=0

Interactividad de la llamada:
0 Solo se reproduce el mensaje y se cuelga.
1 Menú de teclas: hay que enviar MENUIVR con la locución del menú y las opciones.
2 Solicitud de PIN: hay que enviar MENUIVR con la locución y la acción a realizar con el PIN.
3 Asistente de IA: terminado el mensaje, el destinatario conversa con el asistente.

Menuivr
Array of strings
Example: Menuivr={"LOCUCION":"Pulse 1 para confirmar la cita o 2 para hablar con un agente","1":{"ACCION":2,"VALOR":"https://www.sudominio.com/confirmada","LOCUCIONFINAL":"Gracias, su cita queda confirmada"},"2":{"ACCION":4,"VALOR":"34910654321"}}

Definición del menú de teclas (IVR=1) o de la solicitud de PIN (IVR=2).

Con IVR=1 se envía LOCUCION (el texto del menú) y una clave por cada tecla, cuyo valor es un objeto con:
ACCION 1 repetir el mensaje, 2 avisar a una URL, 3 enviar un email, 4 transferir la llamada a otro teléfono, 5 dar de baja al destinatario (lista negra), 6 colgar, 7 pasar la conversación al asistente de IA, 8 pasar la llamada a una extensión de su centralita, 9 pasar la llamada a un grupo de salto.
VALOR la URL (acción 2), el correo (acción 3), el teléfono destino (acción 4), el teléfono al que pasar la llamada si la IA no sabe resolver (acción 7, opcional), la extensión (acción 8: su número, por ejemplo 101; también se admite la dirección SIP de una centralita propia) o el identificador del grupo de salto (acción 9).
LOCUCIONPREVIA texto que se reproduce antes de ejecutar la acción (opcional).
LOCUCIONFINAL texto que se reproduce antes de colgar (opcional).
REPETIRMENU 1 para volver a reproducir el menú tras la acción en lugar de colgar.
GRABAR 1 para grabar la conversación sólo cuando se ejecuta esta opción, es decir, cuando la llamada se pasa a otro teléfono (acción 4) o a una extensión (acción 8). Si quiere grabar la llamada entera desde el descuelgue, use el parámetro GRABAR del envío en lugar de éste. La grabación queda guardada en su cuenta y tiene un coste en créditos por minuto grabado.
PALABRA palabra que el destinatario puede DECIR en lugar de pulsar la tecla (opcional): la locución sería del tipo 'diga comercial o pulse 1'. Gana la primera respuesta, la hablada o la pulsada.

Pasar a una extensión (ACCION 8): suenan a la vez todos los aparatos de la extensión (softphone, aplicación del móvil y navegador) mientras el destinatario oye tono de llamada, y la llamada se queda con el primero que descuelgue. Si la extensión está en pausa o no contesta nadie, se aplica el destino que tenga configurado para cuando no está disponible (otra extensión, un grupo de salto o un teléfono); si no tiene ninguno, o el que tiene es un buzón, se despide del destinatario y cuelga. Nunca se queda la llamada en silencio. Cuando la coge una persona recibe un report con estado 512.

Asistente de IA (ACCION 7): la llamada pasa a una conversación con el asistente entrenado con la información de su cuenta, que entiende lo que dice el destinatario y le responde. El texto de LOCUCIONFINAL se usa como saludo del asistente ('¿En qué puedo ayudarle?' si no lo indica). Si el asistente no sabe resolver la consulta, transfiere al teléfono que haya puesto en VALOR; si no hay ninguno, se despide y cuelga. El minuto de conversación con IA tiene un coste adicional en créditos.

Con IVR=2 se envía LOCUCION (el texto que pide el PIN), ACCIONPIN (2 avisar a una URL, 3 enviar un email), VALORACCIONPIN (la URL o el correo), LONGPIN (número de dígitos, 4 por defecto) y LOCUCIONFINALPIN (texto que se reproduce antes de colgar).

Con IVR=3 se envía LOCUCION (el saludo del asistente, por ejemplo '¿En qué puedo ayudarle?') y, opcionalmente, VALORFALLBACK (teléfono al que transferir la llamada si el asistente no sabe resolver la consulta).

Plantillaivr
string
Example: Plantillaivr=Confirmacion de citas

Nombre o identificador de un menú guardado en su cuenta con el editor de IVR del panel. Se usa en lugar de MENUIVR y evita tener que enviar el menú en cada petición; si envía los dos, manda MENUIVR. Si no indica IVR, el tipo (menú, PIN o asistente) se deduce del propio menú guardado. Obtenga la lista con GetPlantillasVOZ.

Escenario
string
Example: Escenario=soporte-vip

Clave o identificador de un escenario de su cuenta. Los escenarios son de recepción: en una llamada saliente sólo se aprovecha su menú (el modo de entrada, el horario, el buzón o la música de espera no tienen sentido llamando usted). Si el escenario no tiene menú, la petición se rechaza. Obtenga la lista con GetPlantillasVOZ.

Referenciausuario
string
Example: Referenciausuario=AVISO-CITAS-2026-09-15

Referencia libre que usted asigna a la campaña. La recibirá de vuelta en cada report en el campo Referencia, para poder casarlo con su sistema.

Extension
string
Example: Extension=204

Dígitos que se marcan por tonos (DTMF) en cuanto descuelgan, antes de reproducir el mensaje. Sirve para atravesar la centralita del destinatario y dejar el aviso en una extensión concreta: si la centralita contesta con un 'marque la extensión con la que desea hablar', ponga aquí ese número. Sólo dígitos.

Timbrado
integer
Example: Timbrado=30

Segundos que suena el teléfono antes de dar la llamada por no contestada, de 5 a 180. Con 0 se usa el valor del sistema: 30 segundos, o 25 si pidió detección de contestador.

Súbalo si llama a fijos de oficinas grandes (tardan en coger) y bájelo si lo que quiere es enterarse rápido de que no hay nadie, por ejemplo en una alerta con reintentos cada pocos minutos.

Maxduracion
integer
Example: Maxduracion=0

Corte de seguridad: segundos máximos que puede durar la llamada, de 30 a 14400 (cuatro horas). Al alcanzarse, la llamada se cuelga y recibe el report de finalizada con time_limit_reached en Detalle. Con 0 no hay límite.

Es la red de seguridad de las llamadas que pueden acabar en una conversación (paso a una extensión, a un grupo o al asistente de IA): evita que una llamada abierta por error se quede horas consumiendo créditos.

Grabar
string
Enum: 0 1
Example: Grabar=0

1 para grabar la llamada completa desde el momento del descuelgue, incluidas las respuestas del destinatario y la conversación si la llamada acaba pasando a un agente. La grabación queda en su cuenta (Llamadas de VOZ -> Grabaciones) y se cobra por minuto grabado. Advertir al destinatario de que la llamada se graba es responsabilidad suya: dígalo en el MENSAJE.

Velocidad
integer
Example: Velocidad=0

Llamadas por minuto: en vez de lanzar toda la lista de golpe, la salida se reparte en el tiempo desde la FECHA de envío. Sirve para no desbordar a su equipo cuando el menú acaba pasando llamadas a una extensión o a un grupo. Con 0 (por defecto) no hay límite.

El reparto no pasa de HORALIMITEDIARIA: las llamadas que a ese ritmo no caben antes de esa hora no se encolan, se devuelven en NoEncoladas y se cuentan en FueraDeHorario. Si envía 5.000 llamadas a 10 por minuto, calcule que necesita algo más de ocho horas de franja.

Eliminaduplicados
string
Enum: 0 1
Example: Eliminaduplicados=0

1 para llamar una sola vez a un teléfono que aparezca repetido en DESTINATARIOS. Los repetidos no llamados se devuelven en el contador Duplicados. Con 0 se llama tantas veces como aparezca.

Pais
string
Example: Pais=ES

Código de país de dos letras del destino, usado como referencia de la campaña.

Timezone
string
Example: Timezone=Europe/Madrid

Zona horaria a la que se refieren HORAINICIODIARIA y HORALIMITEDIARIA.

Report
string
Enum: 0 1
Example: Report=1

1 para recibir los cambios de estado de las llamadas en la URL que tenga configurada en su panel (Configuración -> API de desarrollo). 0 para no recibirlos.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Formato de la respuesta: TXT, JSON o XML.

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Mensaje
required
string
Remitente
required
string
Destinatarios
required
Array of any
Fecha
string
Lenguaje
string
Detectarcontestador
string
Reintentos
integer
Intervalo
integer
Fechalimite
string
Horainiciodiaria
string
Horalimitediaria
string
Ivr
string
Menuivr
Array of any
Plantillaivr
string
Escenario
string
Referenciausuario
string
Extension
string
Timbrado
integer
Maxduracion
integer
Grabar
string
Velocidad
integer
Eliminaduplicados
string
Pais
string
Timezone
string
Report
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de llamadas encoladas.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 Error en los datos de la llamada. Obtendrá un parámetro adicional denominado Error con la descripción del problema.
-4 La PLANTILLAIVR o el ESCENARIO indicados no existen en su cuenta (o el escenario no tiene menú).
-19 El REMITENTE no es un número de voz de su cuenta.
-20 El LENGUAJE indicado no está soportado.

Error
string

En caso de Res negativo, descripción del problema.

idEnvio
integer

Identificador de la campaña. Lo recibirá en cada report y le sirve para consultar o cancelar la campaña entera.

Destinatarios
integer

Número de destinatarios procesados.

Encoladas
Array of arrays

Llamadas encoladas correctamente. El idMensaje identifica cada llamada: es el que viaja en los reports y el que se usa en CancelarVOZ.

NoEncoladas
Array of arrays

Destinatarios que no se han podido encolar (número no válido, sin cobertura de voz, sin créditos o, si usó VELOCIDAD, porque no cabían en la franja horaria).

FueraDeHorario
integer

Llamadas que no se han encolado porque, al ritmo pedido en VELOCIDAD, no caben antes de HORALIMITEDIARIA. Suba la velocidad, amplíe la franja o reparta la campaña en varios envíos.

Duplicados
integer

Teléfonos repetidos que no se han llamado dos veces. Sólo puede ser distinto de 0 si envió ELIMINADUPLICADOS=1.

ListaNegra
integer

Destinatarios no llamados por estar en su lista negra (se dieron de baja en una llamada anterior).

Cred
number

Créditos restantes en su cuenta tras la operación.

Request samples

Content type
"{\n \"RESP\": \"JSON\",\n \"MENSAJE\": \"Hola (Nombre), le recordamos su cita de mañana (PAUSA:1) a las diez.\",\n \"REMITENTE\": \"34910123456\",\n \"LENGUAJE\": \"es-ES:1\",\n \"REPORT\": \"1\",\n \"REFERENCIAUSUARIO\": \"AVISO-CITAS-2026-09-15\",\n \"DETECTARCONTESTADOR\": \"0\",\n \"REINTENTOS\": \"2\",\n \"INTERVALO\": \"60\",\n \"IVR\": \"1\",\n \"MENUIVR\": {\n \"LOCUCION\": \"Pulse 1 para confirmar la cita o 2 para hablar con un agente\",\n \"1\": {\"ACCION\": 2, \"VALOR\": \"https://www.sudominio.com/confirmada\", \"LOCUCIONFINAL\": \"Gracias, su cita queda confirmada\"},\n \"2\": {\"ACCION\": 4, \"VALOR\": \"34910654321\"}\n },\n \"DESTINATARIOS\": [\n {\"Nombre\": \"Pedro Pérez\", \"Telefono\": \"34600000001\", \"Variables\": [{\"Nombre\": \"Nombre\", \"Valor\": \"Pedro\"}]},\n {\"Nombre\": \"Ana Aguado\", \"Telefono\": \"34600000002\", \"Variables\": [{\"Nombre\": \"Nombre\", \"Valor\": \"Ana\"}]}\n ]\n}\n"

Response samples

Content type
[
  • {
    }
]

Listar lo que puede usar en una llamada

/GetPlantillasVOZ

Devuelve todo lo que tiene guardado en su cuenta y puede usar en las llamadas, para no tener que adivinarlo: los números válidos como REMITENTE, los menús creados con el editor de IVR (para PLANTILLAIVR), los escenarios (para ESCENARIO, del que sólo se aprovecha el menú), los audios de su biblioteca (para escribirlos en el MENSAJE como (MP3:nombre.mp3)) y las extensiones y grupos de salto con el valor ya montado para las acciones 8 y 9 del menú.

Llámela una vez al arrancar su integración y guárdese el resultado: es información de configuración, no cambia en cada llamada.

Authorizations:
basicAuth
query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Formato de la respuesta: TXT, JSON o XML.

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 Consulta correcta.
-1 Error de autenticación.

Numeros
Array of arrays

Números que puede poner en REMITENTE: los números de voz de su cuenta y los remitentes numéricos ya validados. Es exactamente lo que acepta EnviarVOZ, así que cualquier otro número le devolverá Res=-19. Tipo REMITENTE significa que es un remitente validado y no un número contratado en la plataforma.

PlantillasIVR
Array of arrays

Menús guardados con el editor de IVR. Use el Nombre o el idPlantilla en el parámetro PLANTILLAIVR de EnviarVOZ; el campo IVR indica el valor que corresponde a ese menú (1 menú de teclas, 2 PIN, 3 asistente).

Escenarios
Array of arrays

Escenarios de su cuenta. Use la Clave o el idEscenario en el parámetro ESCENARIO de EnviarVOZ. Sólo sirven los que tienen TieneMenu = 1: de un escenario, en una llamada saliente, únicamente se aprovecha el menú.

Audios
Array of arrays

Audios de la biblioteca de su cuenta. Escriba el Marcador dentro del MENSAJE en el punto donde quiera que suene.

Extensiones
Array of arrays

Extensiones activas de su centralita. Copie el campo Valor en MENUIVR[tecla][VALOR] con ACCION=8, y úselas también en LlamarVOZ. Presencia dice si la extensión está disponible o en pausa: una extensión en pausa no suena, la llamada iría a su destino de no disponible.

Grupos
Array of arrays

Grupos de salto activos. Copie el campo Valor en MENUIVR[tecla][VALOR] con ACCION=9. La Estrategia es la que tenga configurada en el panel (todos a la vez, por orden, etc.).

Request samples

Content type
"{\n \"RESP\": \"JSON\"\n}\n"

Response samples

Content type
[
  • {
    }
]

Cancelar llamadas programadas

/CancelarVOZ

Cancela llamadas programadas que todavía no se han cursado, de una en una o la campaña entera. Las llamadas que ya han salido o están en curso no se cancelan: se devuelven en NoCanceladas con su estado. Los créditos reservados de las llamadas efectivamente canceladas vuelven a su saldo.

Authorizations:
basicAuth
query Parameters
Idmensaje
integer
Example: Idmensaje=108366478

Identificador de la llamada a cancelar. Debe indicar IDMENSAJE o IDENVIO.

Idenvio
integer
Example: Idenvio=1228853777

Identificador de la campaña: cancela todas sus llamadas pendientes.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Formato de la respuesta: TXT, JSON o XML.

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idmensaje
integer
Idenvio
integer
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de llamadas canceladas.
0 No había ninguna llamada cancelable (consulte NoCanceladas).
-1 Error de autenticación.
-3 Error en los parámetros o la llamada/campaña no pertenece a su cuenta.

Canceladas
Array of arrays

Llamadas canceladas.

NoCanceladas
Array of arrays

Llamadas que ya no se podían cancelar, con el estado en el que están.

CreditosDevueltos
number

Créditos devueltos a su saldo por las llamadas canceladas.

Cred
number

Créditos restantes en su cuenta tras la operación.

Request samples

Content type
"{\n \"RESP\": \"JSON\",\n \"IDENVIO\": \"1228853777\"\n}\n"

Response samples

Content type
[
  • {
    }
]

Llamar desde una extensión

/LlamarVOZ

Pone en contacto a un agente suyo con un número (lo que se conoce como click-to-call). Suena primero el teléfono del agente —todos los aparatos de su extensión a la vez: softphone, aplicación del móvil y navegador— y, en cuanto descuelga cualquiera de ellos, se marca el destino y se puentean las dos llamadas.

La llamada sale de su centralita mostrando el número de la empresa (nunca el móvil del agente), queda en el historial de llamadas y se cobra como cualquier otra saliente, por minuto iniciado. Si el agente no descuelga no se llama a nadie y no cuesta nada.

El destino puede ser un teléfono o otra extensión de la cuenta, que es la forma de poner a hablar a dos compañeros.

Requiere la Centralita Virtual con extensiones creadas (Llamadas de VOZ -> Extensiones); obtenga la lista con GetPlantillasVOZ. Un usuario autorizado sólo puede llamar desde las extensiones que tenga asignadas.

Authorizations:
basicAuth
query Parameters
Extension
required
string
Example: Extension=101

Extensión del agente desde la que se llama: es la que suena primero. Sólo el número de la extensión.

Destino
required
string
Example: Destino=34600123456

A quién se llama: un teléfono en formato internacional sin el signo + ni espacios, o el número de otra extensión de su cuenta (llamada interna).

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Formato de la respuesta: TXT, JSON o XML.

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Extension
required
string
Destino
required
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 La llamada se ha lanzado: el teléfono del agente está sonando.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 La extensión no existe en su cuenta (o no es del autorizado que llama), el destino no es válido, la extensión no tiene ningún aparato preparado todavía, o no se pudo lanzar la llamada. El motivo concreto viene en Error.

Error
string

En caso de Res negativo, descripción del problema.

Extension
string

Extensión desde la que se está llamando.

Destino
string

Destino al que se marcará cuando el agente descuelgue.

idLlamada
string

Identificador interno de esta llamada. Guárdelo en su traza: es lo que permite localizarla si tiene que consultar algo con nosotros.

Info
string

Texto listo para mostrar al agente en su aplicación.

Cred
number

Créditos restantes en su cuenta.

Request samples

Content type
"{\n \"RESP\": \"JSON\",\n \"EXTENSION\": \"101\",\n \"DESTINO\": \"34600123456\"\n}\n"

Response samples

Content type
[
  • {
    }
]

Recepción de reports y eventos de las llamadas

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DEL ESTADO DE LAS LLAMADAS EN UN SCRIPT DE SU SERVIDOR.

Configurando la URL de su script en su panel de usuario (Configuración -> API de desarrollo), recibirá una petición POST cada vez que una llamada enviada con REPORT=1 cambie de estado.

Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA.

Recibirá una petición por cada cambio de estado, no solo al final de la llamada: así sabe si sonó, si descolgaron, qué tecla pulsaron y cómo terminó. Todas llevan Servicio = VOZ.

{"Servicio":"VOZ","Resultado":"510","Fecha":"2026-09-15 10:31:04","Movil":"34600000001","Prefijo":"34","Remitente":"34910123456","idMensaje":"108366478","idReport":"3497","idEnvio":"1228853777","Duracion":"34","Digitos":"1","Detalle":"completed","Referencia":"AVISO-CITAS-2026-09-15"}

El código numérico de estado viaja en el campo Resultado. Si solo le interesa el desenlace de la llamada, procese los estados 510, 511, 551 y 553 e ignore el resto.

Authorizations:
basicAuth
Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo, para distinguirlo del de los demás servicios. En las llamadas de voz siempre es VOZ.

Resultado
required
integer

Estado de la llamada en el momento del evento. Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`501` Sonando La llamada se ha cursado y está sonando en el teléfono del destinatario.
`502` Descolgada El destinatario ha descolgado y comienza la locución.
`503` Pulsación recibida El destinatario ha pulsado una tecla del menú o ha introducido el PIN. La tecla o el PIN vienen en el campo Digitos, y Detalle indica si es `dtmf` (menú) o `pin`.
`510` Finalizada La llamada se ha completado. El campo Duracion trae los segundos de conversación.
`511` Mensaje en el buzón Respondió un contestador automático y se ha dejado el mensaje grabado.
`512` Atendida por una persona La llamada se ha pasado a una extensión de su centralita y la ha cogido un agente. Detalle trae la extensión, por ejemplo `ext:104`.
`551` No contestada No han contestado, comunicaba o se rechazó la llamada, y ya no quedan reintentos. Si el motivo fue un contestador automático que usted no quería, Detalle trae `machine`.
`553` Sin línea El número no existe o no da línea. No se reintenta.
`1004` Reprogramada No han contestado y la llamada queda reprogramada para el siguiente reintento.
Fecha
required
string

Fecha y hora del evento (CET/CEST).

Movil
required
string

Teléfono del destinatario de la llamada.

Prefijo
string

Prefijo internacional del destinatario.

Remitente
string

Número llamante desde el que se realizó la llamada.

idMensaje
required
integer

Identificador de la llamada, el que devolvió EnviarVOZ en Encoladas.

idReport
integer

Identificador único de este evento. Le sirve para descartar duplicados si su servidor no respondió a tiempo y se reintentó el envío.

idEnvio
integer

Identificador de la campaña a la que pertenece la llamada.

Duracion
integer

Segundos de conversación. Solo viene informado en el evento final (estado 510).

Digitos
string

Tecla pulsada o PIN introducido en este evento (estado 503). Llega un report por cada pulsación, con la tecla de esa pulsación.

Detalle
string

Matiz del evento. Lo que trae depende del estado:

DETALLE ESTADOS SIGNIFICADO
`dtmf`503Pulsación de una tecla del menú. La tecla viene en Digitos.
`pin`503PIN completo introducido por el destinatario. El PIN viene en Digitos.
`ext:NNN`512Extensión de su centralita que ha atendido la llamada, por ejemplo `ext:104`.
`machine`551, 1004Respondió un contestador automático y usted había pedido no dejar mensaje (DETECTARCONTESTADOR 1 o 2).
`completed`510La llamada terminó y el operador no informó de ninguna causa concreta.
`normal_clearing`510Colgó una de las dos partes con normalidad. Es lo habitual en una llamada que se ha desarrollado hasta el final.
`no_answer`, `timeout`551, 1004Sonó el teléfono y nadie contestó.
`busy`, `user_busy`551, 1004El teléfono estaba ocupado.
`call_rejected`551, 1004El destinatario rechazó la llamada.
`originator_cancel`551, 1004La llamada se cortó desde el sistema antes de que contestaran.
`invalid_number`, `unallocated_number`, `no_route_destination`553El número no existe, no está asignado o no hay ruta hacia él.

En los estados 501, 502 y 511 este campo viaja vacío. Las causas de finalización las informa el operador, así que pueden aparecer otras menos frecuentes (time_limit_reached, unspecified...): trátelo como texto libre para su traza y tome las decisiones con el campo Resultado, que sí es una lista cerrada.

Creditos
string

Créditos consumidos por la llamada. Se conocen al terminar la llamada, así que en los eventos intermedios puede venir a 0; en el evento final trae el coste definitivo.

Referencia
string

La REFERENCIAUSUARIO que usted indicó al enviar la llamada.

Request samples

Content type
{
  • "Servicio": "VOZ",
  • "Resultado": "510",
  • "Fecha": "2026-09-15 10:31:04",
  • "Movil": "34600000001",
  • "Prefijo": "34",
  • "Remitente": "34910123456",
  • "idMensaje": "108366478",
  • "idReport": "3497",
  • "idEnvio": "1228853777",
  • "Duracion": "34",
  • "Digitos": "1",
  • "Detalle": "normal_clearing",
  • "Creditos": "2",
  • "Referencia": "AVISO-CITAS-2026-09-15"
}

Anexo A - Colección de ejemplos

Todos los ejemplos son el cuerpo JSON de una petición POST con autenticación básica. Van a https://api.mensatek.com/v7/EnviarVOZ salvo A.17, A.18 y A.19, que indican a qué función van. Los teléfonos son inventados: ponga su número llamante y sus destinatarios.


A.1 Lo mínimo: un aviso y nada más. Una alerta que se escucha y se cuelga. Así es como se manda una llamada completa, cabeceras incluidas:


curl -X POST https://api.mensatek.com/v7/EnviarVOZ \
  -u "UsuarioAPI:APIToken" \
  -H "Content-Type: application/json" \
  -d '{"RESP":"JSON","REMITENTE":"34910123456","MENSAJE":"Aviso de su sistema de alarma: se ha detectado una apertura en la puerta principal.","REPORT":"1","DESTINATARIOS":[{"Telefono":"34600123456"}]}'


Y esto es lo que contesta:


{
  "Res": 1,
  "idEnvio": 1228853777,
  "Destinatarios": 1,
  "Encoladas": [
    { "Telefono": "34600123456", "idMensaje": 108366478 }
  ],
  "NoEncoladas": "",
  "FueraDeHorario": 0,
  "Duplicados": 0,
  "ListaNegra": 0,
  "Cred": 1250.5
}


Guarde el idMensaje de cada destinatario: es el que viaja en todos los reports de esa llamada, y el que sirve para cancelarla.


A.2 Código PIN / OTP por teléfono. El código se deletrea para que se entienda a la primera y se repite. Sin interactividad: se cuelga al terminar.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "es-ES:1",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "OTP-88421",
  "MENSAJE": "Su codigo de verificacion es (PAUSA:1) (SPELL:481902) (PAUSA:1) Repito: (SPELL:481902)",
  "DESTINATARIOS": [
    { "Telefono": "34600123456" }
  ]
}


A.3 Alerta urgente con acuse de recibo. Se avisa y se pide confirmación: la tecla 1 llama a su URL para que usted anote quién se ha enterado, y la tecla 2 repite el aviso por si no se ha oído bien. Con reintentos cada cinco minutos y un timbre corto, para enterarse pronto de que no hay nadie.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "ALERTA-CPD-2026-09-15",
  "MENSAJE": "Atencion (Nombre). Alerta en el centro de datos: temperatura fuera de rango.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Pulse 1 para confirmar que atiende la alerta o 2 para volver a oirla",
    "1": { "ACCION": 2, "VALOR": "https://www.sudominio.com/alertas/ok", "LOCUCIONFINAL": "Gracias, queda registrado" },
    "2": { "ACCION": 1, "REPETIRMENU": 1 }
  },
  "TIMBRADO": "20",
  "DETECTARCONTESTADOR": "1",
  "REINTENTOS": "3",
  "INTERVALO": "5",
  "DESTINATARIOS": [
    { "Nombre": "Luis", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Luis" } ] },
    { "Nombre": "Marta", "Telefono": "34600123457", "Variables": [ { "Nombre": "Nombre", "Valor": "Marta" } ] }
  ]
}


Con DETECTARCONTESTADOR=1 un contestador no cuenta como aviso entregado: se cuelga y se vuelve a intentar.


A.4 Si no lo coge una persona, dejarlo en el contestador. Con DETECTARCONTESTADOR=3 el sistema espera la señal del contestador y deja el mensaje después del pitido; recibirá el report 511.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Le llamamos de su taller: su vehiculo esta listo para recoger.",
  "DETECTARCONTESTADOR": "3",
  "DESTINATARIOS": [
    { "Telefono": "34600123456" }
  ]
}


A.5 Que el mensaje lo escuche una persona, sí o sí. Lo contrario del anterior: con DETECTARCONTESTADOR=2 se cuelga al detectar el contestador y se reintenta; sólo si al agotar los reintentos vuelve a salir el contestador, se le deja el mensaje.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Hola (Nombre), necesitamos confirmar su cita de manana con el especialista.",
  "DETECTARCONTESTADOR": "2",
  "REINTENTOS": "4",
  "INTERVALO": "30",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}


A.6 Validar una operación con un PIN. El destinatario teclea el código que le ha dado su aplicación y usted lo recibe en su URL en el momento, además del report 503.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "FIRMA-TRANSFER-7781",
  "MENSAJE": "Le llamamos para confirmar una transferencia de (Importe).",
  "IVR": "2",
  "MENUIVR": {
    "LOCUCION": "Marque su clave de seis digitos y termine con almohadilla",
    "LONGPIN": 6,
    "ACCIONPIN": 2,
    "VALORACCIONPIN": "https://www.sudominio.com/pin/recibido",
    "LOCUCIONFINALPIN": "Gracias, hemos recibido su clave"
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Importe", "Valor": "1.250 euros" } ] }
  ]
}


A.7 Una pregunta con respuesta del 1 al 5. Cada tecla avisa a una URL distinta (o a la misma con otro parámetro) y la tecla queda además en el report 503, en el campo Digitos.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "ENCUESTA-SEP",
  "MENSAJE": "Hola (Nombre), gracias por confiar en nosotros.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Valore del 1 al 5 la atencion recibida, donde 5 es muy satisfecho",
    "1": { "ACCION": 2, "VALOR": "https://www.sudominio.com/encuesta?nota=1" },
    "2": { "ACCION": 2, "VALOR": "https://www.sudominio.com/encuesta?nota=2" },
    "3": { "ACCION": 2, "VALOR": "https://www.sudominio.com/encuesta?nota=3" },
    "4": { "ACCION": 2, "VALOR": "https://www.sudominio.com/encuesta?nota=4" },
    "5": { "ACCION": 2, "VALOR": "https://www.sudominio.com/encuesta?nota=5", "LOCUCIONFINAL": "Muchas gracias por su valoracion" }
  },
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}


A.8 Dejar que pidan no volver a ser llamados. La acción 5 apunta al destinatario en su lista negra: no se le vuelve a llamar en ningún envío suyo, y los que caigan ahí se cuentan en ListaNegra. Una salida así es una buena práctica en cualquier aviso automático.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Le recordamos que su poliza vence el (Dia).",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Pulse 1 para que le llame un agente o 9 si no desea recibir mas avisos",
    "1": { "ACCION": 4, "VALOR": "34910654321", "LOCUCIONPREVIA": "Le paso con un agente" },
    "9": { "ACCION": 5, "LOCUCIONFINAL": "De acuerdo, no volveremos a llamarle" }
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Dia", "Valor": "30 de septiembre" } ] }
  ]
}


A.9 Aviso que puede acabar hablando con una persona. La tecla 1 pasa la llamada a la extensión 101 de su centralita (suenan todos sus aparatos y se queda con el primero que descuelgue) y la tecla 2 al grupo de salto 4, el equipo de soporte. Lo que se hable con el comercial se graba.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Hola (Nombre), su pedido (Pedido) sale hoy de nuestro almacen.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Pulse 1 para hablar con su comercial, 2 para soporte tecnico, o 3 si no necesita nada mas",
    "1": { "ACCION": 8, "VALOR": "ext:101", "LOCUCIONPREVIA": "Le paso con su comercial", "GRABAR": 1 },
    "2": { "ACCION": 9, "VALOR": "grupo:4", "LOCUCIONPREVIA": "Le paso con soporte tecnico" },
    "3": { "ACCION": 6, "LOCUCIONFINAL": "Gracias por su confianza" }
  },
  "MAXDURACION": "1800",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" }, { "Nombre": "Pedido", "Valor": "A-4421" } ] }
  ]
}


Si nadie coge la extensión se aplica el destino que tenga configurado para cuando no está disponible; la llamada nunca se queda en silencio. Cuando la coge una persona recibe un report con estado 512 y la extensión en Detalle. Los valores de las acciones 8 y 9 (ext:101, grupo:4) se los da GetPlantillasVOZ ya montados.


A.10 Grabar la llamada completa. GRABAR=1 graba desde el descuelgue, respuestas del destinatario incluidas. Avisar de que la llamada se graba es cosa suya: dígalo en el propio mensaje, como aquí.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "GRABAR": "1",
  "MENSAJE": "Le llamamos de (Empresa) para confirmar su pedido. Esta llamada se graba.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Pulse 1 si confirma el pedido o 2 para anularlo",
    "1": { "ACCION": 2, "VALOR": "https://www.sudominio.com/pedido/confirmado" },
    "2": { "ACCION": 2, "VALOR": "https://www.sudominio.com/pedido/anulado" }
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Empresa", "Valor": "Muebles Aguado" } ] }
  ]
}


A.11 Conversación con el asistente de IA. Terminado el mensaje, el destinatario habla con normalidad y el asistente —entrenado con la información de su cuenta— le responde; si no sabe resolver, pasa la llamada al teléfono que indique en VALORFALLBACK.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Hola (Nombre), le llamamos por la renovacion de su servicio.",
  "IVR": "3",
  "MENUIVR": {
    "LOCUCION": "Digame, en que puedo ayudarle",
    "VALORFALLBACK": "34910654321"
  },
  "MAXDURACION": "900",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}


A.12 Llamar a una empresa y marcar la extensión. Si al descolgar contesta una centralita que pide la extensión, EXTENSION la marca por tonos y el mensaje se reproduce después, ya en el puesto correcto. Con el timbre más largo, que en una oficina tardan en coger.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "EXTENSION": "204",
  "TIMBRADO": "60",
  "MENSAJE": "Aviso para el departamento de administracion: su factura (Factura) esta disponible.",
  "DESTINATARIOS": [
    { "Telefono": "34911223344", "Variables": [ { "Nombre": "Factura", "Valor": "F-2026-118" } ] }
  ]
}


A.13 Recordatorio programado, con reintentos y horario. Se programa para una fecha, se reintenta cada hora hasta cuatro veces y sólo se llama entre las 9:00 y las 20:00: lo que caiga fuera espera al día siguiente. Un teléfono repetido en la lista se llama una sola vez.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Hola (Nombre), le recordamos su cita del (Dia) a las (Hora).",
  "FECHA": "2026-09-20 09:30",
  "REINTENTOS": "4",
  "INTERVALO": "60",
  "FECHALIMITE": "2026-09-21 20:00",
  "HORAINICIODIARIA": "09:00",
  "HORALIMITEDIARIA": "20:00",
  "ELIMINADUPLICADOS": "1",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" }, { "Nombre": "Dia", "Valor": "lunes 21" }, { "Nombre": "Hora", "Valor": "las diez" } ] }
  ]
}


A.14 Repartir una lista grande en el tiempo. Avisos cuyo menú puede pasar la llamada a un equipo de cinco personas: a 20 llamadas por minuto el equipo puede seguir el ritmo. Lo que a ese ritmo no quepa antes de las 20:00 no se encola (sale en NoEncoladas y contado en FueraDeHorario).


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "Hola (Nombre), su revision anual vence este mes.",
  "VELOCIDAD": "20",
  "HORALIMITEDIARIA": "20:00",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Pulse 1 si quiere que le atienda un agente ahora",
    "1": { "ACCION": 9, "VALOR": "grupo:4", "LOCUCIONPREVIA": "Le paso con un agente" }
  },
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}


A.15 Reutilizar un menú y un audio que ya tiene en su cuenta. No hace falta mandar el menú en cada petición ni escribir el texto de la locución: se indica el menú guardado por su nombre y el audio propio con su marcador.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "REPORT": "1",
  "MENSAJE": "(MP3:bienvenida.mp3) (PAUSA:1) Hola (Nombre), tiene una gestion pendiente.",
  "PLANTILLAIVR": "Confirmacion de citas",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}


A.16 El mismo aviso en otro idioma. El idioma y el sexo de la voz van en LENGUAJE; el texto, en ese idioma. Un envío por idioma.


{
  "RESP": "JSON",
  "REMITENTE": "351210123456",
  "LENGUAJE": "pt-PT:2",
  "REPORT": "1",
  "MENSAJE": "Ola (Nombre), a sua encomenda sai hoje do nosso armazem.",
  "PAIS": "PT",
  "TIMEZONE": "Europe/Lisbon",
  "DESTINATARIOS": [
    { "Nombre": "Joao", "Telefono": "351910123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Joao" } ] }
  ]
}


A.17 Pedir la configuración de su cuenta. A https://api.mensatek.com/v7/GetPlantillasVOZ, una vez al arrancar su integración: de aquí salen el REMITENTE que puede usar y los valores de las acciones 8 y 9.


{
  "RESP": "JSON"
}


Respuesta (recortada):


{
  "Res": 1,
  "Numeros": [
    { "Numero": "34910123456", "Alias": "Atencion al cliente", "Pais": "ES", "Tipo": "local" }
  ],
  "PlantillasIVR": [
    { "idPlantilla": 12, "Nombre": "Confirmacion de citas", "Tipo": "MENU", "IVR": 1, "Teclas": [ "1", "2" ] }
  ],
  "Audios": [
    { "Fichero": "bienvenida.mp3", "Marcador": "(MP3:bienvenida.mp3)" }
  ],
  "Extensiones": [
    { "idExtension": 7, "Extension": "101", "Nombre": "Javier", "Valor": "ext:101", "Presencia": "disponible" }
  ],
  "Grupos": [
    { "idGrupo": 4, "Nombre": "Soporte tecnico", "Numero": "600", "Valor": "grupo:4", "Estrategia": "todos" }
  ]
}


A.18 Cancelar lo que todavía no ha salido. A https://api.mensatek.com/v7/CancelarVOZ, con el idEnvio de la campaña (o el idMensaje de una llamada suelta). Lo que ya salió no se cancela y se devuelve con su estado.


{
  "RESP": "JSON",
  "IDENVIO": "1228853777"
}


Respuesta:


{
  "Res": 1,
  "Canceladas": [
    { "idMensaje": 108366479, "Movil": "34600123457" }
  ],
  "NoCanceladas": [
    { "idMensaje": 108366478, "Movil": "34600123456", "Resultado": 510, "Estado": "Finalizada" }
  ],
  "CreditosDevueltos": 1,
  "Cred": 1249.5
}


A.19 Llamar desde el CRM (click-to-call). A https://api.mensatek.com/v7/LlamarVOZ: suena la extensión del agente y, en cuanto descuelga, se marca al cliente y se puentean las dos. Si el agente no coge, no se llama a nadie.


{
  "RESP": "JSON",
  "EXTENSION": "101",
  "DESTINO": "34600123456"
}


Respuesta:


{
  "Res": 1,
  "Extension": "101",
  "Destino": "34600123456",
  "idLlamada": "9f2c41a7b8d05e6a",
  "Info": "Te estamos llamando a la extension 101. Al descolgar, marcamos el numero.",
  "Cred": 1249.5
}


A.20 Qué hacer con los errores. Un Res negativo trae siempre el motivo en Error. Merece la pena distinguir tres casos en su integración: -2 (sin créditos) es para avisar a quien lleve la cuenta, -19 (el remitente no es suyo) y -3 (datos mal) son fallos de programación que no se arreglan repitiendo la petición, y un 5XX sí se puede reintentar más tarde.

Anexo B - Qué reports llegan en cada caso

Lo que recibe en su URL, en orden, según cómo acabe la llamada (con REPORT=1):

CÓMO ACABA SECUENCIA DE RESULTADO
Contesta, oye el mensaje y cuelga501 → 502 → 510
Contesta y pulsa una tecla del menú501 → 502 → 503 (una por pulsación) → 510
Contesta, pulsa y la atiende un agente de su centralita501 → 502 → 503 → 512 (Detalle `ext:101`) → 510
Teclea el PIN501 → 502 → 503 (Detalle `pin`, el código en Digitos) → 510
Salta el contestador y usted pidió dejar el mensaje501 → 502 → 511 → 510
Salta el contestador y usted pidió no dejarlo, con reintentos501 → 502 → 1004 (Detalle `machine`) → ... y la secuencia entera otra vez en el reintento
No contesta y quedan reintentos501 → 1004 → ... y otra vez en el reintento
No contesta y ya no quedan reintentos501 → 551
El número no da línea553 (sin más eventos: no se reintenta)


El estado 510 es el único que trae la Duracion real y los Creditos definitivos. Si sólo le interesa el desenlace, procese 510, 511, 551 y 553.


Tenga en cuenta al programar su receptor: los eventos pueden llegar repetidos si su servidor no respondió a tiempo (descártelos por idReport, que es único), y una llamada con reintentos repite la secuencia completa en cada intento (siempre con el mismo idMensaje).