Regístrate y prueba GRATIS sin compromisos ➜
 ES
Iniciar sesión Regístrate
EN
  • Inicio
  • API SMS

Librería Node.js para el envío SMS

La Librería Node.js de la API SMS está diseñada para técnicos y clientes que quieran conectar sus aplicaciones con la plataforma de mensajería SMS de LabsMobile.

Las funcionalidades de esta librería son:

  • El envío de mensajes SMS de forma individual o masivo en tiempo real
  • Envío programado de mensajes SMS
  • Envío de mensajes SMS Unicode, SMS Concatenados y SMS Certificados
  • Consulta de saldo de créditos de una cuenta
  • Consulta de precios por país
  • Consulta HLR de estado y disponibilidad de un número móvil

Esta documentación explica detalladamente el proceso de integración y automatización de estas funcionalidades.

Requisitos

  • Una versión compatible de Node.js. Esta librería es compatible con Node.js v16.19.0 y versiones superiores.
  • Instalar npm compatible con la versión Node.js instalada.
  • Instalar esta librería labsmobile-sms vía npm.
  • Una cuenta de LabsMobile asociada con un nombre de usuario (correo electrónico de registro). Crea una cuenta aquí.
  • Token API utilizado como contraseña y generado desde la sección Configuración API de tu cuenta.
  • Validación de esta documentación. Más información en la Documentación API SMS HTTP/POST

Para obtener más detalles sobre la librería Node.js, consulta el repositorio oficial en Github.

Librería Node.js

Autenticación

El método de autenticación utilizado es Auth Basic HTTP a través de unas credenciales (username de la cuenta y un tokenapi) que se incluyen en la configuración e inicialización de la librería.

Antes de llamar a cualquier función de esta librería es necesario inicializar las credenciales como se muestra en los ejemplos de código.

Recomendación Se pueden generar tokens API desde la Configuración API de la cuenta. Recomendamos cambiar el token frecuentemente y utilizar diferentes tokens para cada uso, conexión o integración.

Configuración y filtros

A continuación se detallan variables de configuración y aspectos de seguridad importantes en una integración con la API de envío SMS http/GET:

  • Dirección IP desde donde se enviarán los mensajes. Si se activa esta opción, sólo se admitirán peticiones de la lista de dirección IPs introducida. Esta funcionalidad es opcional, por defecto se aceptarán mensajes de cualquier IP.
  • Remitente por defecto (por defecto LABSMOBILE). Sólo algunos operadores permiten la asignación dinámica y con valor alfanumérico del campo remitente.
  • Límite de mensajes diario, por defecto 100.000 sms/día.
  • Límite de mensajes por batch, por defecto 10.000 sms/petición.
  • Filtro por países, para que sólo se procesen mensajes de una lista de países.
  • Filtro anti-duplicados, para evitar enviar mensajes iguales a un mismo destinatario.

Todos estos parámetros se pueden activar y modificar en la Configuración API y Preferencias de la cuenta.

Importante Se establece un máximo de 10 peticiones por segundo. Malos usos, abusos o un mayor volumen de peticiones provocarán un bloqueo temporal o permanente de la cuenta y/o dirección IP.

Recomendación Recomendamos activar las Recargas automáticas para que siempre existan créditos disponibles en la cuenta y no se interrumpa el servicio de envío SMS.

Instalación de composer y la librería SMS de LabsMobile

Para instalar npm es necesario seguir las indicaciones según el sistema operativo.

La librería PHP de LabsMobile se puede instalar de dos formas:

  • Utilizar la siguiente instrucción desde la línea de comandos, estando dentro del directorio del proyecto
Instalación desde línea de comandos 
npm i labsmobile-sms
  • Crear un archivo denominado package.json. En dicho archivo, incluir:
Instalación desde archivo package.json 
"dependencies": {
	"labsmobile-sms": "1.0.1"
}

Es indispensable importar las clases necesarias del espacio de nombres labsmobile-sms. Estas clases proporcionan las funciones y clases para interactuar con la API de LabsMobile.

Se deben indicar las credenciales de autenticación en las variables username y token al inicializar la clase LabsMobileClient.

Envío de mensajes SMS

Función para el envío básico y múltiple de mensajes SMS.

FUNCIÓN

sendSMS(new LabsMobileModelTextMessage(numbers, message))

Para realizar un envío de mensajes SMS se deben seguir estos pasos:

  1. Inicializar la clase LabsMobileModelTextMessage con los parámetros obligatorios (los números de destino y el texto del mensaje).
  2. Incluir los parámetros opciones como la programación, modo simulado, etc.
  3. Finalmente llamar a la función sendSMS() para realizar el envío efectivo.
  4. Por último se recomienda examinar el resultado de la petición.
  • Ampliar todo

    PARÁMETROS

    A continuación se describen todos los parámetros posibles en el envío SMS.

  • RESULTADO

    El resultado se obtiene en formato JSON con los siguientes elementos:

Envío básico a un único destinatario 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const LabsMobileModelTextMessage = require("labsmobile-sms/src/LabsMobileModelTextMessage");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function sendSmsTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const message = "Your verification code is 123";
   const phone = ["12015550123"];
   const clientLabsMobile = new LabsMobileClient(username, token);
   const bodySms = new LabsMobileModelTextMessage(phone, message);
   bodySms.scheduled = "2024-12-02 09:00:00";
   bodySms.long = 1;
   const response = await clientLabsMobile.sendSms(bodySms);
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

sendSmsTest()
Envío masivo a múltiples destinatarios 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const LabsMobileModelTextMessage = require("labsmobile-sms/src/LabsMobileModelTextMessage");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function sendSmsTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const message = "Don't miss our Sale! Use code XXXX123 for 20% off.";
   const phone = ["12015550123","12015550124","12015550125"];
   const clientLabsMobile = new LabsMobileClient(username, token);
   const bodySms = new LabsMobileModelTextMessage(phone, message);
   bodySms.scheduled = "2024-12-02 09:00:00";
   bodySms.ucs2 = 1;
   bodySms.long = 1;
   const response = await clientLabsMobile.sendSms(bodySms);
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

sendSmsTest()
Resultado positivo 
{
  "subid": "65f33a88ceb3d",
  "code": "0",
  "message": "Message has been successfully sent."
}
Resultado erróneo 
{
  "subid": "65f7f7041385d",
  "code": "35",
  "message": "The account has no enough credit for this sending"
}

Consulta de saldo

Función para obtener el saldo de créditos disponibles de una cuenta.

FUNCIÓN

getCredit()

Esta función no tiene parámetros y devuelve el siguiente resultado.

  • RESULTADO

    El resultado de cualquier petición se obtiene en formato JSON con los siguientes elementos:

Consulta de saldo de una cuenta 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function getCreditTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const clientLabsMobile = new LabsMobileClient(username, token);
   const response = await clientLabsMobile.getCredit();
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

getCreditTest()
Resultado 
{"code":0,"credits":"10"}

Gestión de envíos programados

Función para cancelar o enviar mensajes programados.

Para indicar los parámetros se debe inicializar la clase LabsMobileModelScheduledSendings() con los siguientes parámetros y posteriormente llamar a la función scheduledSendings().

FUNCIÓN

scheduledSendings(new LabsMobileModelScheduledSendings(subid, cmd))

  • PARÁMETROS

  • RESULTADO

    El resultado se obtiene en formato JSON con los siguientes elementos:

Gestionar envíos programados 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const LabsMobileModelScheduledSendings = require("labsmobile-sms/src/LabsMobileModelScheduledSendings");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function scheduledSendingsTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const subid = "mysubid";
   const cmd = "XXXXXX"; // send or cancel
   const clientLabsMobile = new LabsMobileClient(username, token);
   const scheduledSendings = new LabsMobileModelScheduledSendings(subid, cmd);
   const response = await clientLabsMobile.scheduledSendings(
     scheduledSendings
   );
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

scheduledSendingsTest()
Resultado positivo send 
{
  "code": 0,
  "message": "Scheduled messages successfully sent."
}
Resultado positivo cancel 
{
    "code": 0,
    "message": "Scheduled messages successfully cancelled."
}
Resultado erróneo 
{
    "code": 52,
    "message": "Scheduled messages not found."
}

Consulta de precios

Función para consultar los precios de un SMS estándar en créditos de cada país.

Para indicar los parámetros se debe inicializar la clase LabsMobileModelCountryPrice() con los siguientes parámetros y posteriormente llamar a la función getpricesCountry().

FUNCIÓN

getpricesCountry(new LabsMobileModelCountryPrice(countries))

  • PARÁMETROS

  • Ampliar todo

    RESULTADO

    El resultado se obtiene en formato JSON con los siguientes elementos:

Consulta precios por país 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const LabsMobileModelCountryPrice = require("labsmobile-sms/src/LabsMobileModelCountryPrice");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function getpricesCountryTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const countries = ["CO", "ES"];
   const clientLabsMobile = new LabsMobileClient(username, token);
   const countriesPrice = new LabsMobileModelCountryPrice(countries);
   const response = await clientLabsMobile.getpricesCountry(countriesPrice);
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

getpricesCountryTest()
Resultado positivo 
{
    "CO": {
        "isocode": "CO",
        "prefix": "57",
        "name": "Colombia",
        "credits": 0.043
    },
    "ES": {
        "isocode": "ES",
        "prefix": "34",
        "name": "Spain",
        "credits": 1
    }
}

Consulta HLR Lookup

Función para consultar el estado y disponibilidad de uno o varios números móviles.

Para indicar los parámetros se debe inicializar la clase LabsMobileModelHlrRequest() con los números a consultar y posteriormente llamar a la función hlrRequest().

FUNCIÓN

hlrRequest(new LabsMobileModelHlrRequest(numbers))

  • PARÁMETROS

  • Ampliar todo

    RESULTADO

    El resultado de cualquier petición HLR se obtiene en formato JSON con los valores que se detallan a continuación:

  • Ampliar todo

    RESULTADO POR NÚMERO

Consulta de estado del teléfono móvil 
const LabsMobileClient = require("labsmobile-sms/src/LabsMobileClient");
const LabsMobileModelHlrRequest = require("labsmobile-sms/src/LabsMobileModelHlrRequest");
const ParametersException = require("labsmobile-sms/src/Exception/ParametersException");
const RestException = require("labsmobile-sms/src/Exception/RestException");

async function hlrRequestTest() {
 try {
   const username = "myusername";
   const token = "mytoken";
   const numbers = [];
   const clientLabsMobile = new LabsMobileClient(username, token);
   const hlr = new LabsMobileModelHlrRequest(numbers);
   const response = await clientLabsMobile.hlrRequest(hlr);
   console.log(response);
 } catch (error) {
   if (error instanceof ParametersException) {
     console.log(error.message);
   } else if (error instanceof RestException) {
     console.log(`Error: ${error.status} - ${error.message}`);
   } else {
     throw new Error("Error: " + error);
   }
 }
}

hlrRequestTest()
Resultado positivo 
{
  "result":"ok",
  "error":"",
  "numbers":[
    {
      "msisdn":"573051155514",
      "status":"active",
      "country_name":"Colombia",
      "country_code":"57",
      "country_iso":"CO",
      "network":"Colombia Movil SA(TIGO)",
      "mcc":"732",
      "mnc":"103",
      "format":"valid",
      "type":"mobile"
    }],
    "count":1,
    "credits":0.1
  }

Errores

A continuación se describen los códigos de error HTTP que puede devolver una petición.

Códigos HTTP
Código HTTPDescripción
200 OKPetición procesada correctamente.
400 Bad RequestError en los parámetros de la petición. Se detalla y especifica el error en el código devuelto en el formato JSON.
401 UnauthorizedError en las credenciales o método de autenticación.
402 Payment RequiredError por falta de créditos en la cuenta.
403 ForbiddenPetición bloqueada por el filtro IP o por infringir alguna política de uso de la plataforma.
500 Internal Server ErrorError temporal o incidencia en el servicio

Esta es la lista completa de códigos de respuesta en el formato JSON:

Códigos de resultado en el JSON de respuesta
Código JSONDescripción
0Message has been successfully sent
10Missing XML data in request
11Badly formed XML in request
20The message element must be present in the request
21The message element cannot be empty
23There are no recipients
24Too many recipients
27This message contained one or more invalid character(s)
28Subid is exceeding maximum length
30There was an error while sending the message
35The account has no enough credit for this sending
39The value of the scheduled field is not a valid datetime format
41Scheduled messages cannot be send in test mode
51Compulsary fields not defined.
52Scheduled messages not found.

Recomendamos consultes y tengas en cuenta los siguientes recursos de soporte en tu integración: