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

Librería PHP para el envío SMS

La Librería PHP 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 PHP. Esta librería es compatible con php v5.4 y versiones superiores.
  • Instalar Composer. Se recomienda utilizar Composer 2.2.22.
  • Instalar esta librería labsmobile/sms-php vía composer.
  • 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 Documentacion API SMS HTTP/POST

A tener en cuenta

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

Librería PHP

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 cualquier integración:

  • 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 Composer es necesario seguir las indicaciones según el sistema operativo.

  • Instalación de composer en Linux / Unix / macOS. Más información en getcomposer.org
  • Instalación de Composer en Windows. Más información en getcomposer.org

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

  • Desde la línea de comandos, estando dentro del directorio del proyecto
Instalación desde línea de comandos 
composer require labsmobile/sms-php
  • Creando un archivo composer.json. En este archivo, se debe incluir:
Instalación desde archivo composer.json 
"require": {
	"labsmobile/sms-php": "1.0.1"
}

Es indispensable importar las clases necesarias del espacio de nombres Labsmobile\SmsPhp. 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.

Consejo Recomendamos incluir el archivo de carga automática vendor/autoload.php, que es comúnmente utilizado en aplicaciones que utilizan Composer para gestionar sus dependencias.

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 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\LabsMobileModelTextMessage;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileSendSms
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function sendSms()
 {
   try {
     $message = 'Your verification code is 123';
     $phone = ['12015550123'];
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $bodySms = new LabsMobileModelTextMessage($phone,$message);
     $bodySms->setScheduled("2024-12-02 09:00:00");
     $bodySms->setLong(1);
     $labsMobileClient = $labsMobileClient->sendSms($bodySms);
     $body = $labsMobileClient->getBody();
     $json = json_decode($body);
     echo 'Status ', $json->code . " " . $json->message;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileSendSms();
$smsSender->sendSms();
Envío masivo a múltiples destinatarios 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\LabsMobileModelTextMessage;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileSendSms
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function sendSms()
 {
   try {
     $message = 'Do not miss our Sale! Use code XXXX123 for 20% off.';
     $phone = ['12015550123','12015550124','12015550125'];
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $bodySms = new LabsMobileModelTextMessage($phone,$message);
     $bodySms->setScheduled("2024-12-02 09:00:00");
     $bodySms->setUcs2(1);
     $bodySms->setShortlink(1);
     $bodySms->setTest(1);
     $labsMobileClient = $labsMobileClient->sendSms($bodySms);
     $body = $labsMobileClient->getBody();
     $json = json_decode($body);
     echo 'Status ', $json->code . " " . $json->message;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileSendSms();
$smsSender->sendSms();
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 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileGetCredits
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function getCredits()
 {
   try {
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $response = $labsMobileClient->getCredit();
     $body = $response->getBody();
     echo 'Status ', $body;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileGetCredits();
$smsSender->getCredits();
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:

Gestión de envíos programados 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\LabsMobileModelScheduledSendings;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileScheduledSendings
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function scheduledSendings()
 {
   try {
     $subid="XXXXXXXXXX";  //Identificador de la solicitud de envío
     $cmd="XXXX"; //Comando a ejecutar. Los valores posibles son cancely send
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $bodyScheduled = new LabsMobileModelScheduledSendings($subid, $cmd);
     $labsMobileClient = $labsMobileClient->scheduledSendings($bodyScheduled);
     $body = $labsMobileClient->getBody();
     echo 'Status ', $body;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileScheduledSendings();
$smsSender->scheduledSendings();
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 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\LabsMobileModelCountryPrice;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileCountryPrice
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function countryPrice()
 {
   try {
     $countries = ["CO","ES"];
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $bodyContries = new LabsMobileModelCountryPrice($countries);
     $labsMobileClient = $labsMobileClient->getpricesCountry($bodyContries);
     $body = $labsMobileClient->getBody();
     echo 'Status ', $body;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileCountryPrice();
$smsSender->countryPrice();
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 HLR 
<?php 
require __DIR__ . '/../vendor/autoload.php';

use Labsmobile\SmsPhp\LabsMobileClient;
use Labsmobile\SmsPhp\LabsMobileModelHlrRequest;
use Labsmobile\SmsPhp\Exception\RestException;

class LabsMobileHlr
{
 public $username = 'myUsername';
 public $token = 'myToken';

 public function hlr()
 {
   try {
     $numbers = [];//[34XXXXXXXX,34XXXXXXXX]
     $labsMobileClient = new LabsMobileClient($this->username, $this->token);
     $bodyHlr = new LabsMobileModelHlrRequest(json_encode($numbers));
     $labsMobileClient = $labsMobileClient->hlrRequest($bodyHlr);
     $body = $labsMobileClient->getBody();
     echo 'Status ', $body;
   } catch (RestException $exception) {
     echo 'Error ', $exception->getStatus() ." ". $exception->getMessage();
   }
 }
}

$smsSender = new LabsMobileHlr();
$smsSender->hlr();
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.

Recursos de soporte

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