Enviar Llamada de Voz

Realiza una llamada telefónica con mensaje de voz usando plantillas TTS (Text-to-Speech).

post/voice/send

Para códigos de verificación, login o 2FA, usa POST /v2/otp con channel: "voice": la API genera el código, lo dicta por llamada y lo valida por ti. Este endpoint solo dicta un code que tú mismo generas y validas.

Convierte una plantilla en una llamada de voz TTS. template selecciona el guion, company inserta el nombre de tu organización y code es el valor que se lee por voz: se dicta carácter por carácter, acepta letras y números y debe tener entre 4 y 11 caracteres.

La plantilla k es la personalizada: requiere voice_message (máximo 160 caracteres; los caracteres fuera de letras, números, comas, puntos y espacios se eliminan automáticamente).

El catálogo de guiones de voz está en Plantillas de mensaje.

Autorización

apikeystringheaderrequerido

Cuerpo de la solicitud

application/json

numbersstringrequerido

Números de teléfono de los destinatarios, separados por coma. Ejemplo: 4771234567,4770987654

country_codestringrequerido

Código de país. Por estandarización, siempre se debe enviar 52, que es el código correspondiente a México.

templateenumrequerido

Letra de la plantilla de voz (de la a a la k). Cada letra es un guion pregrabado que se reproduce durante la llamada; las variables company y code se rellenan solas. La plantilla k permite un mensaje propio con el parámetro voice_message. Consulta el guion de cada plantilla en Plantillas de mensaje.

enum:abcdefghijk

sandboxenum

Modo de pruebas: 1 sandbox (no descuenta créditos), 0 producción. Por defecto 0.

enum:01

companystring

Nombre de la compañía para personalizar el mensaje de voz.

codestring

Código de verificación a comunicar en la llamada, de 4 a 11 caracteres. Acepta letras y números; se dicta carácter por carácter durante la llamada. No aplica con la plantilla k.

voice_messagestring

Mensaje de voz personalizado (máximo 160 caracteres). Solo compatible con la plantilla k, donde es obligatorio. Los caracteres fuera de letras, números, comas, puntos y espacios se eliminan automáticamente.

Respuesta

200Llamada realizada exitosamente

successboolean

messagestring

Mensaje de estado

statusinteger

codestring

Código de respuesta

total_messagesinteger

Número de mensajes enviados

referencesarray<object>

IDs de referencia de los mensajes

▸ Ver atributos del elemento▾ Ocultar atributos del elemento

referencestring

ID único de referencia del mensaje

numberstring

Número de teléfono del destinatario

creditnumber

Créditos consumidos

campaignIdinteger

ID de campaña (solo cuando showCampaignId=true)

400Error de validación (error_02: número, país, plantilla o código inválidos). Si tu integración aún requiere el comportamiento anterior, envía el header X-Api-Http-Semantics: 0 y la respuesta llegará con HTTP 200 y el error en el cuerpo.

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

Campo legado dentro del cuerpo. Conserva su valor histórico (normalmente 200) y NO coincide con el status HTTP real: la respuesta puede llegar con HTTP 400/402/404/409/502 mientras este campo sigue en su valor legado. Usa el status HTTP de transporte y el code, no este campo.

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

401No autorizado: API Key no provista, inválida o expirada

successboolean

Siempre false

messagestring

Descripción del error de autenticación en español

statusinteger

Campo legado en el cuerpo. Es el status HTTP de transporte; para autenticación coincide con el status real (401). Usa el status HTTP y el code, no este campo.

codestring

Código de error de autenticación (auth_01, auth_03, auth_05)

402Saldo insuficiente para completar la llamada (code: sms_07, compartido con el pipeline de envío).

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

403Prohibido: La dirección IP no está autorizada para acceder (IP whitelist)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Campo legado en el cuerpo. Puede NO coincidir con el status HTTP real: para auth_06 y auth_07 este campo vale 401 (valor histórico congelado) mientras el status HTTP de transporte es 403. Usa el status HTTP y el code, no este campo.

codestring

Código de error: auth_04 (IP no autorizada), auth_06 (cuenta deshabilitada), auth_07 (admin inválido)

429Demasiadas peticiones: Límite de rate limit excedido (100 mensajes/segundo producción, 1000 envíos de prueba por día en sandbox)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error de rate limit

500Error interno del servidor (error_03/err_03, o sms_12 heredado del pipeline de envío).

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Campo legado dentro del cuerpo. Conserva su valor histórico (p.ej. 200 o 401 según el endpoint) y NO coincide con el status HTTP real (500). Usa el status HTTP de transporte y el code, no este campo.

codestring

Código de error interno (p.ej. server_01, o auth_99 en un error interno de autenticación)

request_idstring· uuid

Identificador único de la petición. Inclúyelo al contactar a soporte.

502Falla aguas abajo al realizar la llamada (code: sms_23/sms_41, compartido con el pipeline de envío). Reintenta con backoff.

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

Código	Cuándo ocurre	Qué hacer
`error_02`	Cualquier validación fallida: número, país, plantilla, `code` (4–11 caracteres), `voice_message` ausente o de más de 160, `company` de más de 40.	El `message` indica el campo exacto; corrígelo y reintenta.
`error_03`	Error interno al procesar la llamada.	Reintenta; si persiste, contacta a soporte con el `request_id`.