VOICE Messages API (7.0)

Download OpenAPI specification:Download

INTRODUCTION

API to place voice calls from your applications over https requests. The system calls the recipient, reads out the message you provide converted to speech and, if you want, collects the answer of the recipient: key presses (IVR menu), a PIN or a transfer to another phone.

AUTHENTICATION

Your user account holds the API User and the API Token, and both are needed to make REST API requests to the functions of this API. For security reasons requests must be made with POST over HTTPS.

To use Basic Authentication include a header of the form: Authorization: Basic Base64StringAPI where Base64StringAPI is the Base64 encoding of the string APIUser:APIToken. You will find your API User and API Token in your account under Your data -> Configure account.

ACCEPTABLE USE — READ THIS BEFORE YOU INTEGRATE

BULK MARKETING CALLS ARE NOT ALLOWED. This API is designed for services that add value for the person receiving the call: PIN/OTP codes, urgent alerts, notices and confirmations, automated calls to employees and, in general, any transactional communication. Generating calls that the recipient may regard as spam is strictly forbidden.

Any complaint on those grounds may lead to the temporary blocking of the calling number and to an investigation. By using the service, the holder of the number (the owning company) undertakes not to use it for those purposes and takes full responsibility for its use.

THINGS TO KEEP IN MIND

Calling number: Calls ALWAYS go out from a voice number you have with the platform. You can get one from your panel (VOICE calls -> My numbers) in Spain, Portugal, Mexico and other countries. Showing a number that is not yours is not possible: regulation and the carrier reject it.

Credits: Calls are charged per minute started: the first minute is reserved when the call is queued and, when it ends, the charge is adjusted to how long it actually lasted. A call cancelled before it is placed returns its credits in full.

Calling hours: HORAINICIODIARIA and HORALIMITEDIARIA define the window in which calls MAY be placed. A call scheduled outside that window is not lost: it is rescheduled for the next start time. Please observe the rules of the destination country on business calling hours.

Recording: With GRABAR=1 the whole call is recorded from the moment it is answered; the recording is kept in your account (VOICE calls -> Recordings) and is charged per minute recorded. Telling the recipient that the call is being recorded is your responsibility: say so in the MENSAJE itself.

Empty connections: Repeatedly connecting with wrong data will be treated by the system as spam and may end up blocking the connection temporarily. Avoid repeated requests with wrong data or 'empty' queries of the same report.

Response of the requests: Every function accepts the 'RESP' parameter, which sets the format of the response: TXT, JSON or XML. We recommend always setting it; if you do not, the response comes back as plain text (TXT).

THE MESSAGE

The text of the MENSAJE parameter is converted to speech in the language you set in LENGUAJE. Besides plain text it accepts:

- Variables: write (Nombre) in the text and send its value in VARIABLES for each recipient. You may use any variable names you like.
- (PAUSA:n) n seconds of silence. Example: Your appointment is tomorrow (PAUSA:1) at ten. (WAIT:n) does the same.
- (SPELL:text) spells the text out character by character, for codes and references.
- (MP3:name.mp3) plays, at that point, an audio file from your account library (the ones you upload from the panel; get the list with GetPlantillasVOZ). An audio file that is not in your library is skipped and the message carries on: audio hosted on other websites is not accepted.

Markers go inside brackets and can be mixed with the text as many times as you need.

INTERACTIVE CALLS

With the IVR parameter you can ask the recipient for an answer:

IVR=1 (key menu): after the message, the menu prompt is read out ('press 1 to confirm, 2 to talk to an agent...') and, depending on the key pressed, the system runs the action you configured: repeat the message, notify a URL of yours, send an email, transfer the call to another phone, opt the recipient out or hang up. Each option can also carry a prompt before and after the action, and can return to the menu instead of hanging up.

IVR=2 (PIN request): the system asks for a code of several digits ending with the hash key and, once the recipient enters it, sends it to the URL or the email address you indicate. This is the usual way of validating an operation over the phone.

IVR=3 (AI assistant): as soon as the message ends, the call moves on to a conversation with the AI assistant trained with the information in your account: the recipient speaks normally, the assistant understands and answers. If it cannot solve the query, it transfers the call to the phone you indicate. Each minute of conversation with the AI has an additional cost in credits.

Key presses also reach you as a report (status 503), with the key or the PIN in the Digitos field.

REUSING WHAT YOU ALREADY HAVE IN YOUR ACCOUNT

You do not need to send the whole menu on every request, nor to record your audio files again:

- Saved menus: those you built with the IVR editor of the panel are used by giving their name or their identifier in PLANTILLAIVR.
- Scenarios: a scenario can be given in ESCENARIO, but bear in mind that scenarios belong to inbound calls (entry mode, opening hours, voicemail, hold music...): from a scenario, only its menu is used here, which is the only part that means the same thing on an outgoing call. The rest is ignored on purpose.
- Audio files: the mp3 files you uploaded to your account library are played by writing (MP3:name.mp3) inside the MENSAJE.

The GetPlantillasVOZ function returns all of that exactly as you have it saved and, on top of it, the numbers you can use as REMITENTE and the extensions and ring groups with their values already spelled out for menu actions 8 and 9. One call before you start and there is nothing left to guess.

CALLING FROM AN EXTENSION (CLICK-TO-CALL)

If you have the Virtual PBX, the LlamarVOZ function does something different from everything above: it does not play a message, it puts one of your agents through to a number. The phone of the agent rings first (every device of their extension) and, as soon as they pick up, the destination is dialled and both calls are bridged. This is what lets you call from your CRM without installing anything: the call goes out from the PBX with the company number, is kept in the call history and is charged like any other outgoing call. If the agent does not pick up, nobody is dialled and nothing is charged.

RECEIVING REPORTS

In your panel (Configuration -> Development API) set the URL of your server where you want to receive status changes. From then on you will get a POST request for every status change of every call you sent with REPORT=1: when it rings, when it is answered, when a key is pressed, when the message is left on an answering machine and when it ends, with the real duration. The format is described at the end of this document.

This is the way to follow your calls: set the URL up and leave it running before you start calling. Reports always go to that URL, so that there is a single place to look at when something does not arrive.

APPENDIX A: COLLECTION OF EXAMPLES

Every example is the JSON body of a POST request with basic authentication. They all go to https://api.mensatek.com/v7/EnviarVOZ except the last four, which state their function. The phone numbers are made up: use your own calling number and your own recipients.

A.1 The bare minimum: a notice and nothing else. An alert that is read out and hung up. This is how a whole call is sent, headers included:


curl -X POST https://api.mensatek.com/v7/EnviarVOZ \
  -u "APIUser:APIToken" \
  -H "Content-Type: application/json" \
  -d '{"RESP":"JSON","REMITENTE":"34910123456","LENGUAJE":"en-GB:1","MENSAJE":"Notice from your alarm system: an opening has been detected at the main door.","REPORT":"1","DESTINATARIOS":[{"Telefono":"34600123456"}]}'

And this is what comes back:


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

Keep the idMensaje of each recipient: it is the one that travels in every report of that call, and the one used to cancel it.

A.2 PIN / OTP code over the phone. The code is spelled out so that it is understood first time, and then repeated. No interactivity: the call hangs up when it ends.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "OTP-88421",
  "MENSAJE": "Your verification code is (PAUSA:1) (SPELL:481902) (PAUSA:1) I repeat: (SPELL:481902)",
  "DESTINATARIOS": [
    { "Telefono": "34600123456" }
  ]
}

A.3 Urgent alert with acknowledgement. The alert is read out and an answer is requested: key 1 notifies your URL so you can record who took notice, and key 2 repeats the alert in case it was not heard properly. With retries every five minutes and a short ring, to find out quickly that nobody is there.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "ALERT-DC-2026-09-15",
  "MENSAJE": "Attention (Nombre). Alert at the data centre: temperature out of range.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Press 1 to confirm that you are handling the alert, or 2 to hear it again",
    "1": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/alerts/ok", "LOCUCIONFINAL": "Thank you, it has been recorded" },
    "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" } ] }
  ]
}

With DETECTARCONTESTADOR=1 an answering machine does not count as a delivered notice: the call is hung up and tried again.

A.4 If a person does not take it, leave it on the answering machine. With DETECTARCONTESTADOR=3 the system waits for the beep and leaves the message after it; you will get report 511.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "This is your garage calling: your vehicle is ready for collection.",
  "DETECTARCONTESTADOR": "3",
  "DESTINATARIOS": [
    { "Telefono": "34600123456" }
  ]
}

A.5 Make sure a person hears the message. The opposite of the previous one: with DETECTARCONTESTADOR=2 the call is hung up when an answering machine is detected and tried again; only if the machine answers again once the retries are exhausted is the message left on it.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "Hello (Nombre), we need to confirm your appointment with the specialist tomorrow.",
  "DETECTARCONTESTADOR": "2",
  "REINTENTOS": "4",
  "INTERVALO": "30",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}

A.6 Validating an operation with a PIN. The recipient types the code your application gave them and you receive it at your URL right away, on top of report 503.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "SIGN-TRANSFER-7781",
  "MENSAJE": "We are calling to confirm a transfer of (Importe).",
  "IVR": "2",
  "MENUIVR": {
    "LOCUCION": "Enter your six digit code and finish with the hash key",
    "LONGPIN": 6,
    "ACCIONPIN": 2,
    "VALORACCIONPIN": "https://www.yourdomain.com/pin/received",
    "LOCUCIONFINALPIN": "Thank you, we have received your code"
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Importe", "Valor": "1,250 euros" } ] }
  ]
}

A.7 One question answered from 1 to 5. Each key notifies a different URL (or the same one with another parameter) and the key also reaches you in report 503, in the Digitos field.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "REFERENCIAUSUARIO": "SURVEY-SEP",
  "MENSAJE": "Hello (Nombre), thank you for trusting us.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Please rate the service from 1 to 5, where 5 is very satisfied",
    "1": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/survey?score=1" },
    "2": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/survey?score=2" },
    "3": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/survey?score=3" },
    "4": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/survey?score=4" },
    "5": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/survey?score=5", "LOCUCIONFINAL": "Many thanks for your feedback" }
  },
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}

A.8 Letting them ask not to be called again. Action 5 puts the recipient on your blacklist: they will not be called again in any of your calls, and those left out are counted in ListaNegra. An exit like this is good practice in any automated notice.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "This is a reminder that your policy expires on (Dia).",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Press 1 to have an agent call you, or 9 if you do not wish to receive further notices",
    "1": { "ACCION": 4, "VALOR": "34910654321", "LOCUCIONPREVIA": "I am putting you through to an agent" },
    "9": { "ACCION": 5, "LOCUCIONFINAL": "Understood, we will not call you again" }
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Dia", "Valor": "the 30th of September" } ] }
  ]
}

A.9 A notice that can end up talking to a person. Key 1 passes the call to extension 101 of your PBX (all of its devices ring and the first one to pick up keeps the call) and key 2 to ring group 4, the support team. Whatever is said with the sales rep is recorded.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "Hello (Nombre), your order (Pedido) leaves our warehouse today.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Press 1 to talk to your sales rep, 2 for technical support, or 3 if you need nothing else",
    "1": { "ACCION": 8, "VALOR": "ext:101", "LOCUCIONPREVIA": "I am putting you through to your sales rep", "GRABAR": 1 },
    "2": { "ACCION": 9, "VALOR": "grupo:4", "LOCUCIONPREVIA": "I am putting you through to technical support" },
    "3": { "ACCION": 6, "LOCUCIONFINAL": "Thank you for your business" }
  },
  "MAXDURACION": "1800",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" }, { "Nombre": "Pedido", "Valor": "A-4421" } ] }
  ]
}

If nobody answers the extension, its configured destination for when it is unavailable applies; the call is never left in silence. When a person takes it you get a report with status 512 and the extension in Detalle. The values for actions 8 and 9 (ext:101, grupo:4) are handed to you ready made by GetPlantillasVOZ.

A.10 Recording the whole call. GRABAR=1 records from the moment the call is answered, the answers of the recipient included. Warning them that the call is recorded is up to you: say it in the message itself, as here.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "GRABAR": "1",
  "MENSAJE": "This is (Empresa) calling to confirm your order. This call is being recorded.",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Press 1 to confirm the order or 2 to cancel it",
    "1": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/order/confirmed" },
    "2": { "ACCION": 2, "VALOR": "https://www.yourdomain.com/order/cancelled" }
  },
  "DESTINATARIOS": [
    { "Telefono": "34600123456", "Variables": [ { "Nombre": "Empresa", "Valor": "Aguado Furniture" } ] }
  ]
}

A.11 A conversation with the AI assistant. Once the message ends, the recipient speaks normally and the assistant, trained with the information in your account, answers; if it cannot solve the query, it passes the call to the phone you set in VALORFALLBACK.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "Hello (Nombre), we are calling about the renewal of your service.",
  "IVR": "3",
  "MENUIVR": {
    "LOCUCION": "Tell me, how can I help you",
    "VALORFALLBACK": "34910654321"
  },
  "MAXDURACION": "900",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}

A.12 Calling a company and dialling the extension. If a switchboard answers asking for an extension, EXTENSION dials it with tones and the message is played afterwards, already at the right desk. With a longer ring, because offices take their time to pick up.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "EXTENSION": "204",
  "TIMBRADO": "60",
  "MENSAJE": "Notice for the accounts department: your invoice (Factura) is available.",
  "DESTINATARIOS": [
    { "Telefono": "34911223344", "Variables": [ { "Nombre": "Factura", "Valor": "F-2026-118" } ] }
  ]
}

A.13 A scheduled reminder, with retries and calling hours. Scheduled for a date, retried every hour up to four times and only placed between 09:00 and 20:00: whatever falls outside waits for the next day. A phone repeated in the list is called only once.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "Hello (Nombre), this is a reminder of your appointment on (Dia) at (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": "Monday the 21st" }, { "Nombre": "Hora", "Valor": "ten" } ] }
  ]
}

A.14 Spreading a large list over time. Notices whose menu can pass the call to a team of five: at 20 calls per minute the team can keep up. Whatever does not fit at that rate before 20:00 is not queued (it comes back in NoEncoladas and counted in FueraDeHorario).


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "Hello (Nombre), your annual service is due this month.",
  "VELOCIDAD": "20",
  "HORALIMITEDIARIA": "20:00",
  "IVR": "1",
  "MENUIVR": {
    "LOCUCION": "Press 1 if you would like an agent to take your call now",
    "1": { "ACCION": 9, "VALOR": "grupo:4", "LOCUCIONPREVIA": "I am putting you through to an agent" }
  },
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}

A.15 Reusing a menu and an audio file you already have. No need to send the menu on every request nor to write the prompt text: the saved menu is given by its name and your own audio with its marker.


{
  "RESP": "JSON",
  "REMITENTE": "34910123456",
  "LENGUAJE": "en-GB:1",
  "REPORT": "1",
  "MENSAJE": "(MP3:welcome.mp3) (PAUSA:1) Hello (Nombre), you have a pending matter with us.",
  "PLANTILLAIVR": "Appointment confirmation",
  "DESTINATARIOS": [
    { "Nombre": "Ana", "Telefono": "34600123456", "Variables": [ { "Nombre": "Nombre", "Valor": "Ana" } ] }
  ]
}

A.16 The same notice in another language. The language and the gender of the voice go in LENGUAJE; the text, in that language. One request per language.


{
  "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 Asking for the configuration of your account. To https://api.mensatek.com/v7/GetPlantillasVOZ, once when your integration starts: this is where the REMITENTE you may use and the values for actions 8 and 9 come from.


{
  "RESP": "JSON"
}

Response (trimmed):


{
  "Res": 1,
  "Numeros": [
    { "Numero": "34910123456", "Alias": "Customer care", "Pais": "ES", "Tipo": "local" }
  ],
  "PlantillasIVR": [
    { "idPlantilla": 12, "Nombre": "Appointment confirmation", "Tipo": "MENU", "IVR": 1, "Teclas": [ "1", "2" ] }
  ],
  "Audios": [
    { "Fichero": "welcome.mp3", "Marcador": "(MP3:welcome.mp3)" }
  ],
  "Extensiones": [
    { "idExtension": 7, "Extension": "101", "Nombre": "James", "Valor": "ext:101", "Presencia": "disponible" }
  ],
  "Grupos": [
    { "idGrupo": 4, "Nombre": "Technical support", "Numero": "600", "Valor": "grupo:4", "Estrategia": "todos" }
  ]
}

A.18 Cancelling what has not gone out yet. To https://api.mensatek.com/v7/CancelarVOZ, with the idEnvio of the batch (or the idMensaje of a single call). What already went out is not cancelled and comes back with its status.


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

Response:


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

A.19 Calling from the CRM (click-to-call). To https://api.mensatek.com/v7/LlamarVOZ: the extension of the agent rings and, as soon as they pick up, the customer is dialled and both calls are bridged. If the agent does not pick up, nobody is called.


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

Response:


{
  "Res": 1,
  "Extension": "101",
  "Destino": "34600123456",
  "idLlamada": "9f2c41a7b8d05e6a",
  "Info": "We are calling your extension 101. When you pick up, we dial the number.",
  "Cred": 1249.5
}

A.20 What to do with errors. A negative Res always carries the reason in Error. It pays to tell three cases apart in your integration: -2 (out of credits) is one to warn whoever runs the account about, -19 (the calling number is not yours) and -3 (bad data) are programming mistakes that repeating the request will not fix, and a 5XX can indeed be retried later.

APPENDIX B: WHICH REPORTS ARRIVE IN EACH CASE

What you receive at your URL, in order, depending on how the call ends (with REPORT=1):

HOW IT ENDS	SEQUENCE OF RESULTADO
Answered, message heard, hung up	501 → 502 → 510
Answered and a menu key pressed	501 → 502 → 503 (one per key press) → 510
Answered, key pressed and taken by an agent of your PBX	501 → 502 → 503 → 512 (Detalle `ext:101`) → 510
The PIN is entered	501 → 502 → 503 (Detalle `pin`, the code in Digitos) → 510
An answering machine picks up and you asked to leave the message	501 → 502 → 511 → 510
An answering machine picks up, you asked not to leave it, with retries	501 → 502 → 1004 (Detalle `machine`) → ... and the whole sequence again on the retry
No answer and retries left	501 → 1004 → ... and again on the retry
No answer and no retries left	501 → 551
The number gives no line	553 (no further events: it is not retried)

Status 510 is the only one that carries the real Duracion and the final Creditos. If you only care about the outcome, process 510, 511, 551 and 553.

Bear this in mind when writing your receiver: events may arrive more than once if your server did not answer in time (discard them by idReport, which is unique), and a call with retries repeats the whole sequence on every attempt (always with the same idMensaje).

basicAuth

HTTP Basic authentication. Use your API User as the username and your API Token as the password (you will find them in your panel, under Your Data → Configure Account). The resulting header is Authorization: Basic base64(APIUser:APIToken). Most HTTP libraries build it automatically (curl -u, requests auth=, Ruby's basic_auth, etc.) without needing to encode the base64 by hand.

Security Scheme Type: HTTP

HTTP Authorization Scheme: basic

Send voice call

/EnviarVOZ

Function to place voice calls from your applications. It queues one call per recipient and returns the identifier of each one.

PLEASE NOTE: set the reception of reports up in your panel if you want to receive the status of the calls and the key presses of the recipient in real time on a script of your website.

Authorizations:

basicAuth

query Parameters

Mensaje required	string Example: Mensaje=Hello (Nombre), this is a reminder of your appointment tomorrow (PAUSA:1) at ten in the morning. Text that is converted to speech and read out to the recipient. It accepts variables of the form `(Nombre)` and the markers `(PAUSA:n)` or `(WAIT:n)` (n seconds of silence), `(SPELL:text)` (spell out character by character) and `(MP3:name.mp3)` (play, at that point, an audio file from your account library).
Remitente required	string Example: Remitente=34910123456 Number shown as the caller, in international format without the + sign and without spaces. It must be a voice number of your account (VOICE calls -> My numbers). If the number is not yours the request is rejected with Res=-19.
Destinatarios required	Array of arrays Example: Destinatarios=[{"Nombre":"Peter Perez","Telefono":"34600123456","Variables":[{"Nombre":"Nombre","Valor":"Peter"},{"Nombre":"Importe","Valor":"120 euros"}]}] JSON array with the recipients of the call. Each element accepts NOMBRE (optional), TELEFONO (required, in international format without + and without spaces) and VARIABLES (optional) to personalise the message for each recipient.
Fecha	string Example: Fecha=2026-09-15 10:30 Date the call is scheduled for. Empty by default, which means call right away. Format Year-Month-day hour:minute. The time reference is CET/CEST (time zone of Spain).
Lenguaje	string Example: Lenguaje=en-GB:1 Language and voice of the speech, in the form `locale:gender` where gender is 1 (female) or 2 (male). Available locales: es-ES, es-MX, es-US, pt-PT, pt-BR, en-US, en-GB, fr-FR, de-DE, it-IT and ca-ES. If the locale is not supported the request is rejected with Res=-20.
Detectarcontestador	string Enum: 0 1 2 3 Example: Detectarcontestador=0 What to do when the call is answered by an answering machine: `0` Carry on and leave the message (default). `1` Hang up and try again later, as many times as set in REINTENTOS. `2` Hang up and try again; if a machine answers again once the retries are exhausted, leave the message. `3` Wait for the beep and leave the message after it.
Reintentos	integer Example: Reintentos=3 Number of times the call is retried when there is no answer (0 to 10). With 0 it is not retried.
Intervalo	integer Example: Intervalo=60 Minutes to wait between retries (5 to 1440).
Fechalimite	string Example: Fechalimite=2026-09-30 20:00 Deadline for the retries: after that date the number is not called again. One month from the request by default. Format Year-Month-day hour:minute.
Horainiciodiaria	string Example: Horainiciodiaria=10:00 Time from which calls MAY be placed each day, in HH:MM format. A call falling outside the allowed window is rescheduled for this time.
Horalimitediaria	string Example: Horalimitediaria=22:00 Time from which calls are NOT placed each day, in HH:MM format.
Ivr	string Enum: 0 1 2 3 Example: Ivr=0 Interactivity of the call: `0` The message is read out and the call is hung up. `1` Key menu: MENUIVR must be sent with the menu prompt and the options. `2` PIN request: MENUIVR must be sent with the prompt and what to do with the PIN. `3` AI assistant: once the message ends, the recipient talks to the assistant.
Menuivr	Array of strings Example: Menuivr={"LOCUCION":"Press 1 to confirm the appointment or 2 to talk to an agent","1":{"ACCION":2,"VALOR":"https://www.yourdomain.com/confirmed","LOCUCIONFINAL":"Thank you, your appointment is confirmed"},"2":{"ACCION":4,"VALOR":"34910654321"}} Definition of the key menu (IVR=1) or of the PIN request (IVR=2). With IVR=1 you send LOCUCION (the menu text) and one key per option, whose value is an object with: `ACCION` 1 repeat the message, 2 notify a URL, 3 send an email, 4 transfer the call to another phone, 5 opt the recipient out (blacklist), 6 hang up, 7 hand the conversation over to the AI assistant, 8 pass the call to an extension of your PBX, 9 pass the call to a ring group. `VALOR` the URL (action 2), the email address (action 3), the destination phone (action 4), the phone to pass the call to when the AI cannot solve the query (action 7, optional), the extension (action 8: its number, for example 101; the SIP address of your own PBX is accepted too) or the identifier of the ring group (action 9). `LOCUCIONPREVIA` text read out before running the action (optional). `LOCUCIONFINAL` text read out before hanging up (optional). `REPETIRMENU` 1 to play the menu again after the action instead of hanging up. `GRABAR` 1 to record the conversation only when this option runs, that is, when the call is passed to another phone (action 4) or to an extension (action 8). If you want to record the whole call from the moment it is answered, use the GRABAR parameter of the request instead of this one. The recording is kept in your account and is charged per minute recorded. `PALABRA` word the recipient may SAY instead of pressing the key (optional): the prompt would be of the form 'say sales or press 1'. The first answer wins, spoken or pressed. Passing the call to an extension (ACCION 8): every device of the extension rings at the same time (softphone, mobile app and browser) while the recipient hears a ringing tone, and the call stays with the first one to pick up. If the extension is paused or nobody answers, the destination configured for when it is unavailable applies (another extension, a ring group or a phone); if there is none, or the one configured is a voicemail box, the recipient is said goodbye to and the call is hung up. The call is never left in silence. When a person takes it you receive a report with status 512. AI assistant (ACCION 7): the call moves on to a conversation with the assistant trained with the information in your account, which understands what the recipient says and answers. The text of LOCUCIONFINAL is used as the greeting of the assistant ('how can I help you?' if you do not set it). If the assistant cannot solve the query, it transfers to the phone you put in VALOR; if there is none, it says goodbye and hangs up. Each minute of conversation with the AI has an additional cost in credits. With IVR=2 you send LOCUCION (the text asking for the PIN), ACCIONPIN (2 notify a URL, 3 send an email), VALORACCIONPIN (the URL or the email address), LONGPIN (number of digits, 4 by default) and LOCUCIONFINALPIN (text read out before hanging up). With IVR=3 you send LOCUCION (the greeting of the assistant, for example 'how can I help you?') and, optionally, VALORFALLBACK (phone to transfer the call to if the assistant cannot solve the query).
Plantillaivr	string Example: Plantillaivr=Appointment confirmation Name or identifier of a menu saved in your account with the IVR editor of the panel. It is used instead of MENUIVR and saves you from sending the menu on every request; if you send both, MENUIVR wins. If you do not set IVR, the type (menu, PIN or assistant) is taken from the saved menu itself. Get the list with GetPlantillasVOZ.
Escenario	string Example: Escenario=vip-support Key or identifier of a scenario of your account. Scenarios belong to inbound calls: on an outgoing call only their menu is used (entry mode, opening hours, voicemail or hold music make no sense when you are the one calling). If the scenario has no menu, the request is rejected. Get the list with GetPlantillasVOZ.
Referenciausuario	string Example: Referenciausuario=APPOINTMENTS-2026-09-15 Free reference you assign to the batch. You will get it back in every report in the Referencia field, so that you can match it with your own system.
Extension	string Example: Extension=204 Digits dialled with tones (DTMF) as soon as the call is answered, before the message is played. It is there to get through the switchboard of the recipient and leave the notice at a specific desk: if the switchboard answers with a 'please dial the extension you want', put that number here. Digits only.
Timbrado	integer Example: Timbrado=30 Seconds the phone rings before the call is given up as unanswered, from 5 to 180. With 0 the value of the system is used: 30 seconds, or 25 if you asked for answering machine detection. Raise it when you call landlines of large offices (they take their time to pick up) and lower it when what you want is to find out quickly that nobody is there, for example in an alert retried every few minutes.
Maxduracion	integer Example: Maxduracion=0 Safety cut: maximum seconds the call may last, from 30 to 14400 (four hours). When it is reached, the call is hung up and you receive the finished report with `time_limit_reached` in Detalle. With 0 there is no limit. It is the safety net of calls that may end up in a conversation (passed to an extension, to a ring group or to the AI assistant): it stops a call left open by mistake from burning credits for hours.
Grabar	string Enum: 0 1 Example: Grabar=0 1 to record the whole call from the moment it is answered, including the answers of the recipient and the conversation if the call ends up with an agent. The recording is kept in your account (VOICE calls -> Recordings) and is charged per minute recorded. Warning the recipient that the call is being recorded is your responsibility: say so in the MENSAJE.
Velocidad	integer Example: Velocidad=0 Calls per minute: instead of placing the whole list at once, the output is spread over time from the FECHA of the request. It is there so that you do not overwhelm your team when the menu ends up passing calls to an extension or to a ring group. With 0 (default) there is no limit. The spread does not go past HORALIMITEDIARIA: calls that at that rate do not fit before that time are not queued, they come back in NoEncoladas and are counted in FueraDeHorario. If you send 5,000 calls at 10 per minute, reckon on needing a window of a little over eight hours.
Eliminaduplicados	string Enum: 0 1 Example: Eliminaduplicados=0 1 to call only once a phone number that appears more than once in DESTINATARIOS. The repeated ones that were not called come back in the Duplicados counter. With 0 it is called as many times as it appears.
Pais	string Example: Pais=ES Two letter country code of the destination, used as a reference of the batch.
Timezone	string Example: Timezone=Europe/Madrid Time zone HORAINICIODIARIA and HORALIMITEDIARIA refer to.
Report	string Enum: 0 1 Example: Report=1 1 to receive the status changes of the calls at the URL configured in your panel (Configuration -> Development API). 0 not to receive them.
Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Format of the response: TXT, JSON or XML.

Request Body schema:
application/json

Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.

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:
application/json

Array

Res required	integer <int32> Response of the requested function `>0` Number of calls queued. `-1` Authentication error. `-2` Not enough credits. `-3` Error in the data of the call. You will get an additional parameter named Error with the description of the problem. `-4` The PLANTILLAIVR or the ESCENARIO given do not exist in your account (or the scenario has no menu). `-19` The REMITENTE is not a voice number of your account. `-20` The LENGUAJE given is not supported.
Error	string When Res is negative, description of the problem.
idEnvio	integer Identifier of the batch. You will get it in every report and it lets you query or cancel the whole batch.
Destinatarios	integer Number of recipients processed.
Encoladas	Array of arrays Calls queued successfully. The idMensaje identifies each call: it is the one that travels in the reports and the one used in CancelarVOZ.
NoEncoladas	Array of arrays Recipients that could not be queued (invalid number, no voice coverage, no credits or, if you used VELOCIDAD, because they did not fit in the calling window).
FueraDeHorario	integer Calls not queued because, at the rate asked for in VELOCIDAD, they do not fit before HORALIMITEDIARIA. Raise the rate, widen the window or split the batch into several requests.
Duplicados	integer Repeated phone numbers that were not called twice. It can only be other than 0 if you sent ELIMINADUPLICADOS=1.
ListaNegra	integer Recipients not called because they are on your blacklist (they opted out on a previous call).
Cred	number Credits left in your account after the operation.

Request samples

Content type

application/json

"{\n  \"RESP\": \"JSON\",\n  \"MENSAJE\": \"Hello (Nombre), this is a reminder of your appointment tomorrow (PAUSA:1) at ten.\",\n  \"REMITENTE\": \"34910123456\",\n  \"LENGUAJE\": \"en-GB:1\",\n  \"REPORT\": \"1\",\n  \"REFERENCIAUSUARIO\": \"APPOINTMENTS-2026-09-15\",\n  \"DETECTARCONTESTADOR\": \"0\",\n  \"REINTENTOS\": \"2\",\n  \"INTERVALO\": \"60\",\n  \"IVR\": \"1\",\n  \"MENUIVR\": {\n    \"LOCUCION\": \"Press 1 to confirm the appointment or 2 to talk to an agent\",\n    \"1\": {\"ACCION\": 2, \"VALOR\": \"https://www.yourdomain.com/confirmed\", \"LOCUCIONFINAL\": \"Thank you, your appointment is confirmed\"},\n    \"2\": {\"ACCION\": 4, \"VALOR\": \"34910654321\"}\n  },\n  \"DESTINATARIOS\": [\n    {\"Nombre\": \"Peter Perez\", \"Telefono\": \"34600123456\", \"Variables\": [{\"Nombre\": \"Nombre\", \"Valor\": \"Peter\"}]},\n    {\"Nombre\": \"Anne Aguado\", \"Telefono\": \"34600123457\", \"Variables\": [{\"Nombre\": \"Nombre\", \"Valor\": \"Anne\"}]}\n  ]\n}\n"

Response samples

Content type

application/json

[{"Res": "2",
"Error": "REMITENTE is not a voice number of this account",
"idEnvio": "1228853777",
"Destinatarios": "2",
"Encoladas": "[{\"Telefono\": \"34600123456\",\"idMensaje\": \"108366478\"}]",
"NoEncoladas": "[{\"Telefono\": \"34600123457\",\"Nombre\": \"Anne Aguado\",\"Res\": -2}]",
"FueraDeHorario": "0",
"Duplicados": "0",
"ListaNegra": "0",
"Cred": "1250.50"
}
]

List what you can use in a call

/GetPlantillasVOZ

Returns everything you have saved in your account and can use in your calls, so that you do not have to guess: the numbers valid as REMITENTE, the menus built with the IVR editor (for PLANTILLAIVR), the scenarios (for ESCENARIO, of which only the menu is used), the audio files of your library (to write them in the MENSAJE as (MP3:name.mp3)) and the extensions and ring groups with the value already built for menu actions 8 and 9.

Call it once when your integration starts and keep the result: this is configuration data, it does not change from call to call.

Authorizations:

basicAuth

query Parameters

Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Format of the response: TXT, JSON or XML.

Request Body schema:
application/json

Resp

string

Responses

Response Schema:
application/json

Array

Res required	integer <int32> Response of the requested function `1` Query successful. `-1` Authentication error.
Numeros	Array of arrays Numbers you can put in REMITENTE: the voice numbers of your account and the numeric senders already validated. This is exactly what EnviarVOZ accepts, so any other number will give you Res=-19. Tipo `REMITENTE` means it is a validated sender and not a number bought on the platform.
PlantillasIVR	Array of arrays Menus saved with the IVR editor. Use the Nombre or the idPlantilla in the PLANTILLAIVR parameter of EnviarVOZ; the IVR field tells you which value matches that menu (1 key menu, 2 PIN, 3 assistant).
Escenarios	Array of arrays Scenarios of your account. Use the Clave or the idEscenario in the ESCENARIO parameter of EnviarVOZ. Only those with TieneMenu = 1 are of any use: from a scenario, on an outgoing call, only the menu is used.
Audios	Array of arrays Audio files of your account library. Write the Marcador inside the MENSAJE at the point where you want it to play.
Extensiones	Array of arrays Active extensions of your PBX. Copy the Valor field into MENUIVR[key][VALOR] with ACCION=8, and use them in LlamarVOZ as well. Presencia tells you whether the extension is available or paused: a paused extension does not ring, the call would go to its destination for when it is unavailable.
Grupos	Array of arrays Active ring groups. Copy the Valor field into MENUIVR[key][VALOR] with ACCION=9. The Estrategia is the one configured in the panel (all at once, one after another, and so on).

Request samples

Content type

application/json

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

Response samples

Content type

application/json

[{"Res": "1",
"Numeros": "[{\"Numero\":\"34910123456\",\"Alias\":\"Customer care\",\"Pais\":\"ES\",\"Tipo\":\"local\"}]",
"PlantillasIVR": "[{\"idPlantilla\":12,\"Nombre\":\"Appointment confirmation\",\"Tipo\":\"MENU\",\"IVR\":1,\"Teclas\":[\"1\",\"2\"]}]",
"Escenarios": "[{\"idEscenario\":3,\"Clave\":\"vip-support\",\"Nombre\":\"VIP support\",\"TieneMenu\":1}]",
"Audios": "[{\"Fichero\":\"welcome.mp3\",\"Marcador\":\"(MP3:welcome.mp3)\"}]",
"Extensiones": "[{\"idExtension\":7,\"Extension\":\"101\",\"Nombre\":\"James\",\"Valor\":\"ext:101\",\"Presencia\":\"disponible\"}]",
"Grupos": "[{\"idGrupo\":4,\"Nombre\":\"Technical support\",\"Numero\":\"600\",\"Valor\":\"grupo:4\",\"Estrategia\":\"todos\"}]"
}
]

Cancel scheduled calls

/CancelarVOZ

Cancels scheduled calls that have not been placed yet, one by one or the whole batch. Calls that already went out or are in progress are not cancelled: they come back in NoCanceladas with their status. The credits reserved for the calls actually cancelled go back to your balance.

Authorizations:

basicAuth

query Parameters

Idmensaje	integer Example: Idmensaje=108366478 Identifier of the call to cancel. You must give either IDMENSAJE or IDENVIO.
Idenvio	integer Example: Idenvio=1228853777 Identifier of the batch: cancels all of its pending calls.
Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Format of the response: TXT, JSON or XML.

Request Body schema:
application/json

Idmensaje	integer
Idenvio	integer
Resp	string

Responses

Response Schema:
application/json

Array

Res required	integer <int32> Response of the requested function `>0` Number of calls cancelled. `0` There was nothing left to cancel (see NoCanceladas). `-1` Authentication error. `-3` Error in the parameters, or the call/batch does not belong to your account.
Canceladas	Array of arrays Calls cancelled.
NoCanceladas	Array of arrays Calls that could no longer be cancelled, with the status they are in.
CreditosDevueltos	number Credits returned to your balance for the cancelled calls.
Cred	number Credits left in your account after the operation.

Request samples

Content type

application/json

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

Response samples

Content type

application/json

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

Call from an extension

/LlamarVOZ

Puts one of your agents through to a number (what is known as click-to-call). The phone of the agent rings first - every device of their extension at the same time: softphone, mobile app and browser - and, as soon as any of them picks up, the destination is dialled and both calls are bridged.

The call goes out from your PBX showing the number of the company (never the mobile of the agent), is kept in the call history and is charged like any other outgoing call, per minute started. If the agent does not pick up, nobody is called and nothing is charged.

The destination may be a phone number or another extension of the account, which is the way to put two colleagues through to each other.

Requires the Virtual PBX with extensions created (VOICE calls -> Extensions); get the list with GetPlantillasVOZ. An authorised user can only call from the extensions assigned to them.

Authorizations:

basicAuth

query Parameters

Extension required	string Example: Extension=101 Extension of the agent the call is made from: it is the one that rings first. The number of the extension only.
Destino required	string Example: Destino=34600123456 Who is called: a phone number in international format without the + sign and without spaces, or the number of another extension of your account (internal call).
Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Format of the response: TXT, JSON or XML.

Request Body schema:
application/json

Extension required	string
Destino required	string
Resp	string

Responses

Response Schema:
application/json

Array

Res required	integer <int32> Response of the requested function `1` The call has been placed: the phone of the agent is ringing. `-1` Authentication error. `-2` Not enough credits. `-3` The extension does not exist in your account (or does not belong to the authorised user making the request), the destination is not valid, the extension has no device set up yet, or the call could not be placed. The exact reason comes in Error.
Error	string When Res is negative, description of the problem.
Extension	string Extension the call is being made from.
Destino	string Destination that will be dialled once the agent picks up.
idLlamada	string Internal identifier of this call. Keep it in your log: it is what allows us to find the call if you ever need to ask us about it.
Info	string Text ready to be shown to the agent in your application.
Cred	number Credits left in your account.

Request samples

Content type

application/json

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

Response samples

Content type

application/json

[{"Res": "1",
"Error": "That extension does not exist or is not active.",
"Extension": "101",
"Destino": "34600123456",
"idLlamada": "9f2c41a7b8d05e6a",
"Info": "We are calling your extension 101. When you pick up, we dial the number.",
"Cred": "1250.50"
}
]

Reception of reports and call events

https://{YourDomain}/path/to/your/report/reception/script

REAL TIME RECEPTION OF THE STATUS OF YOUR CALLS ON A SCRIPT OF YOUR SERVER.

By setting the URL of your script in your user panel (Configuration -> Development API), you will receive a POST request every time a call sent with REPORT=1 changes status.

You can choose to receive the requests with basic authentication and in JSON or FORM-DATA format.

You will get one request per status change, not only at the end of the call: that way you know whether it rang, whether it was answered, which key was pressed and how it ended. All of them carry Servicio = VOZ.

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

The numeric status code travels in the Resultado field. If you only care about the outcome of the call, process statuses 510, 511, 551 and 553 and ignore the rest.

Authorizations:

basicAuth

Request Body schema:
application/json

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

Type of report you are receiving, so that you can tell it apart from the ones of the other services. On voice calls it is always VOZ.

Resultado

required

integer

Status of the call at the moment of the event. The possible statuses are:

STATUS	DESCRIPTION	MEANING
`501`	Ringing	The call has been placed and the phone of the recipient is ringing.
`502`	Answered	The recipient picked up and the message starts.
`503`	Key press received	The recipient pressed a key of the menu or entered the PIN. The key or the PIN come in the Digitos field, and Detalle says whether it is `dtmf` (menu) or `pin`.
`510`	Finished	The call is complete. The Duracion field carries the seconds of conversation.
`511`	Message on the answering machine	An answering machine picked up and the message has been left recorded on it.
`512`	Taken by a person	The call was passed to an extension of your PBX and an agent took it. Detalle carries the extension, for example `ext:104`.
`551`	Not answered	Nobody answered, the line was busy or the call was rejected, and there are no retries left. If the reason was an answering machine you did not want, Detalle carries `machine`.
`553`	No line	The number does not exist or gives no line. It is not retried.
`1004`	Rescheduled	Nobody answered and the call is rescheduled for the next retry.

Fecha

required

string

Date and time of the event (CET/CEST).

Movil

required

string

Phone number of the recipient of the call.

Prefijo

string

International dialling code of the recipient.

Remitente

string

Calling number the call was made from.

idMensaje

required

integer

Identifier of the call, the one EnviarVOZ returned in Encoladas.

idReport

integer

Unique identifier of this event. Use it to discard duplicates if your server did not answer in time and the delivery was retried.

idEnvio

integer

Identifier of the batch the call belongs to.

Duracion

integer

Seconds of conversation. It is only filled in on the final event (status 510).

Digitos

string

Key pressed or PIN entered in this event (status 503). One report arrives per key press, with the key of that press.

Detalle

string

Nuance of the event. What it carries depends on the status:

DETALLE	STATUSES	MEANING
`dtmf`	503	A key of the menu was pressed. The key comes in Digitos.
`pin`	503	The recipient entered the complete PIN. The PIN comes in Digitos.
`ext:NNN`	512	Extension of your PBX that took the call, for example `ext:104`.
`machine`	551, 1004	An answering machine picked up and you had asked not to leave a message (DETECTARCONTESTADOR 1 or 2).
`completed`	510	The call ended and the carrier reported no particular cause.
`normal_clearing`	510	One of the two parties hung up normally. This is the usual one on a call that ran to the end.
`no_answer`, `timeout`	551, 1004	The phone rang and nobody answered.
`busy`, `user_busy`	551, 1004	The line was busy.
`call_rejected`	551, 1004	The recipient rejected the call.
`originator_cancel`	551, 1004	The call was cut from the system before it was answered.
`time_limit_reached`	510	The call reached the limit set in MAXDURACION and was hung up.
`invalid_number`, `unallocated_number`, `no_route_destination`	553	The number does not exist, is not allocated or there is no route to it.

On statuses 501, 502 and 511 this field comes empty. The hangup causes are reported by the carrier, so others may show up now and then (unspecified, and so on): treat it as free text for your log and take your decisions with the Resultado field, which is a closed list.

Creditos

string

Credits used by the call. They are known when the call ends, so on intermediate events it may come as 0; the final event carries the definitive cost.

Referencia

string

The REFERENCIAUSUARIO you set when sending the call.

Request samples

Payload

Content type

application/json

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

VOICE Messages API (7.0)

INTRODUCTION

AUTHENTICATION

ACCEPTABLE USE — READ THIS BEFORE YOU INTEGRATE

THINGS TO KEEP IN MIND

THE MESSAGE

INTERACTIVE CALLS

REUSING WHAT YOU ALREADY HAVE IN YOUR ACCOUNT

CALLING FROM AN EXTENSION (CLICK-TO-CALL)

RECEIVING REPORTS

APPENDIX A: COLLECTION OF EXAMPLES

APPENDIX B: WHICH REPORTS ARRIVE IN EACH CASE

basicAuth

Send voice call

/EnviarVOZ

Authorizations:

query Parameters

Request Body schema: application/jsonapplication/x-www-form-urlencodedapplication/json

Responses

Response Schema: application/jsonapplication/xmltext/plainapplication/json

Request samples

Response samples

List what you can use in a call

/GetPlantillasVOZ

Authorizations:

query Parameters

Request Body schema: application/jsonapplication/x-www-form-urlencodedapplication/json

Responses

Response Schema: application/jsonapplication/xmltext/plainapplication/json

Request samples

Response samples

Cancel scheduled calls

/CancelarVOZ

Authorizations:

query Parameters

Request Body schema: application/jsonapplication/x-www-form-urlencodedapplication/json

Responses

Response Schema: application/jsonapplication/xmltext/plainapplication/json

Request samples

Response samples

Call from an extension

/LlamarVOZ

Authorizations:

query Parameters

Request Body schema: application/jsonapplication/x-www-form-urlencodedapplication/json

Responses

Response Schema: application/jsonapplication/xmltext/plainapplication/json

Request samples

Response samples

Reception of reports and call events

https://{YourDomain}/path/to/your/report/reception/script

Authorizations:

Request Body schema: application/jsonapplication/x-www-form-urlencodedapplication/json

Request samples

Request Body schema:
application/json

Response Schema:
application/json

Request Body schema:
application/json

Response Schema:
application/json

Request Body schema:
application/json

Response Schema:
application/json

Request Body schema:
application/json

Response Schema:
application/json

Request Body schema:
application/json