Envío de OTP

Esta interfaz hace que la plataforma EngageLab genere el código de verificación y lo envíe según la estrategia de canales especificada en la plantilla.

Si desea generar el código de verificación por su cuenta en lugar de hacerlo a través de la plataforma EngageLab, puede llamar a la interfaz Envío de OTP personalizado de EngageLab.

Dirección de la llamada

POST https://otp.api.engagelab.cc/v1/messages

Autenticación de llamadas

Consulte Autenticación de llamadas para saber cómo autenticar la API.

Ejemplo de solicitud

Encabezados de la solicitud

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

Cuerpo de la solicitud

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

Parámetros de la solicitud

Un objeto de solicitud se expresa en formato JSON, por lo que el encabezado de la solicitud debe incluir Content-Type: application/json.

Acerca de params

1. Para los campos preestablecidos de la plantilla, como from_id, si no se pasa el valor del campo params, al enviar el mensaje se usa el from_id preestablecido de la plantilla;
2. Si se pasa el valor del campo params, como params:{"from_id":"12345"}, al enviar el mensaje el from_id de la plantilla se sustituirá por 12345;
3. Asimismo, para los campos de variables personalizadas del contenido de la plantilla definidos al crearla, también se asignan sus valores mediante params; por ejemplo, si el contenido de la plantilla es Hi {{name}}, your verify code is {{code}}, deberá asignar el parámetro params:{"name":"Bob"}
4. Variables especiales del canal Email: para el canal Email, se admite sobrescribir dinámicamente mediante params el asunto del correo (subject), el nombre del remitente (from_name), el correo del remitente (from_mail), etc. Para el uso avanzado detallado, consulte Crear plantilla - Uso avanzado de las variables de plantilla de Email.

Parámetros de la respuesta

Respuesta exitosa

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

Tenga en cuenta que el valor de**send_channel**devuelto no representa el canal final por el que se entrega al usuario, sino únicamente el canal usado en la etapa actual; por ejemplo, si en la estrategia configurada en la plantilla se establece que, ante un fallo de entrega por el canal WhatsApp, se reenvíe automáticamente por el canal SMS, la interfaz devolverá el valor whatsapp y, tras detectar el fallo de entrega pasado un tiempo, el sistema enviará por el canal SMS.

Respuesta de error

El código de estado HTTP es 4xx o 5xx, y el cuerpo de la respuesta contiene los siguientes campos:

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

Códigos de error

La siguiente tabla solo describe los errores que esta API devuelve durante la autenticación, la validación previa al envío y el envío sincrónico. Los fallos de entrega asincrónicos tras la aceptación del proveedor no se devuelven por esta API; obténgalos mediante consultas de estado del mensaje o callbacks.

El llamador debe usar code para determinar el tipo de error. Use message para mostrar el motivo concreto o para el diagnóstico; no confíe en un texto fijo de message para la lógica de negocio.

Notas sobre errores de límite de frecuencia y volumen de envío

• 3004 es el control de frecuencia de envío de OTP por plantilla; la ventana de límite se basa en la configuración de la plantilla y puede no coincidir con el periodo de validez del código.
• 6001 y 6002 son controles de frecuencia de seguridad a nivel de número o IP del usuario final.
• 6003 y 6008 indican que esta solicitud alcanzó un límite de volumen de envío; tras alcanzar el límite y entrar en estado suspendido, las solicitudes posteriores pueden devolver 6007.
• Al recibir HTTP 429, no reintente de inmediato de forma continua; reintente más tarde y, si persiste, contacte al administrador o al soporte técnico.
• 5011 a 5019 solo cubren fallos identificables en la fase de envío sincrónico. Estados como número vacío, teléfono apagado o rechazo del operador tras la aceptación del proveedor aún pueden devolverse mediante el estado asincrónico del mensaje o callbacks.