Enviar SMS
Si deseas enviar notificaciones y SMS de marketing de forma automatizada, puedes llamar a esta interfaz. Indica el ID de la plantilla de SMS y los destinatarios, y el sistema enviará automáticamente los SMS según el contenido de la plantilla.
Consejo de configuración de la plataforma Antes de realizar la llamada, debes completar la siguiente configuración en la consola de SMS de EngageLab:
- Configuración de la plantilla de SMS: antes de llamar a la API, ve primero a Gestión de plantillas, personaliza y envía una plantilla de SMS. La plantilla debe pasar la revisión antes de poder usar su ID.
- Configuración de la clave de API: ve a API Key y crea una clave de autenticación API Basic.
Dirección de la llamada
POST https://smsapi.engagelab.com/v1/messages
Verificación de la llamada
Consulta Verificación de la llamada para saber cómo autenticar las solicitudes a la API.
Ejemplo de solicitud
Cabecera de la solicitud
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Este bloque de código se muestra en una ventana flotante
Cuerpo de la solicitud
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
Este bloque de código se muestra en una ventana flotante
Parámetros de solicitud
Un objeto de solicitud se expresa en formato JSON, por lo que la cabecera de la solicitud debe incluir Content-Type: application/json.
| Parámetro | Tipo | Opción | Descripción |
|---|---|---|---|
| to | Array[String] | Sí | Lista de números de teléfono de destino del envío, como ["923700056581"] |
| plan_name | String | No | Nombre del plan; si no se indica, se muestra "-" por defecto |
| schedule_time | Integer | No | Hora del envío programado. No se incluye en los envíos no programados. Marca de tiempo Unix, en «segundos». Reglas de validación: debe ser un número positivo; debe ser estrictamente posterior al momento actual en al menos 3 minutos; no puede superar los 30 días a partir del momento actual. |
| template | JSON Object | Sí | Información de la plantilla; los parámetros de segundo nivel que contiene se indican a continuación |
| |_ id | String | Sí | ID de la plantilla |
| |_ params | JSON Object | Sí | Valores de las claves (Key) de las variables personalizadas de la plantilla Si definiste variables personalizadas al crear la plantilla, asígnales aquí sus valores; si no las indicas, se enviarán directamente con la clave (Key) de la variable, como {{var1}} |
| custom_args | JSON Object | No | Parámetros personalizados |
Descripción de params
Todos los campos de variables personalizadas del contenido de la plantilla definidos al crearla deben recibir un valor mediante params. Por ejemplo, si el contenido de la plantilla es Hi {{name}}, welcome to EngageLab, en este caso es necesario asignar el parámetro params: {"name": "Bob"}.
Más ejemplos de solicitud
1. Enviar contenido de notificación personalizado:
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
Este bloque de código se muestra en una ventana flotante
2. Enviar contenido de marketing personalizado:
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
Este bloque de código se muestra en una ventana flotante
Parámetros de respuesta
Respuesta correcta
El código de estado HTTP es 200 y el cuerpo de la respuesta contiene los siguientes campos:
| Campo | Tipo | Opción | Descripción |
|---|---|---|---|
| plan_id | String | Sí | ID del plan |
| total_count | Integer | Sí | Número de destinos recibidos |
| accepted_count | Integer | Sí | Número de destinos válidos recibidos |
| message_id | String | No | En un envío individual se devuelve el message_id correspondiente |
| schedule_info | JSON Object | No | Información relacionada con la tarea programada (solo se devuelve en los envíos programados) |
| |_ task_id | Integer | Sí | ID de la tarea programada |
Ejemplo correcto (destino único)
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
Este bloque de código se muestra en una ventana flotante
Ejemplo correcto (varios destinos)
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
Este bloque de código se muestra en una ventana flotante
Ejemplo correcto (tarea programada)
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
Este bloque de código se muestra en una ventana flotante
Respuesta de error
El código de estado HTTP es 200 (en algunas situaciones excepcionales) o 4xx/5xx, y el cuerpo de la respuesta contiene los siguientes campos:
| Campo | Tipo | Opción | Descripción |
|---|---|---|---|
| plan_id | String | Sí | ID del plan |
| total_count | Integer | Sí | Número de destinos recibidos |
| accepted_count | Integer | Sí | Número de destinos válidos recibidos |
| code | Integer | Sí | Código de error, consulta la descripción de los códigos de error |
| message | String | Sí | Detalle del error |
Ejemplo de excepción
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
Este bloque de código se muestra en una ventana flotante
Códigos de error
| Código de error | http code | Descripción |
|---|---|---|
| 1000 | 500 | Error interno |
| 2001 | 401 | Error de autenticación: no se incluyó un token correcto |
| 2002 | 401 | Error de autenticación: el token ha caducado o ha sido deshabilitado |
| 2004 | 403 | Sin permiso para llamar a esta API |
| 3001 | 400 | El formato de los parámetros de la solicitud no es válido; comprueba que el contenido JSON cumpla con el formato de los parámetros |
| 3002 | 400 | Parámetros de la solicitud incorrectos; comprueba que cumplan los requisitos |
| 3003 | 400 | Parámetros de la solicitud incorrectos: fallo en la validación de negocio correspondiente; consulta la descripción del error en el campo message |
| 3004 | 400 | Se ha superado el límite de frecuencia; para una misma plantilla y un mismo usuario de destino, no se puede volver a enviar dentro del periodo de validez del código de verificación |
| 4001 | 400 | El recurso correspondiente no existe; por ejemplo, se usó una plantilla inexistente al enviar el mensaje de plantilla |
| 5001 | 400 | Fallo en el envío del mensaje; consulta la descripción del error en el campo message |
