GUÍA PARA DESARROLLADORES

Cómo enviar SMS desde PHP con la API de Grupo Tecnophone

Integre el envío de SMS en su aplicación PHP con una petición HTTPS: autenticación por token, IP autorizada y respuesta JSON con el identificador de cada mensaje.

Antes de empezar

  • Una conexión API creada en el panel web (app.grupotecnophone.com), con su Bearer Token de sandbox o de producción.
  • La IP pública de su servidor registrada como autorizada para ese token.
  • Un User-Agent que identifique a su aplicación, por ejemplo MiEmpresa/1.0.
  • PHP 7.4 o superior con la extensión cURL habilitada.

Guarde el token en una variable de entorno (en estos ejemplos, GTP_SMS_TOKEN) y nunca lo incluya en el código de una app móvil o de un sitio web: las llamadas a la API deben salir siempre de su backend, desde una IP autorizada.

Enviar un SMS con PHP y cURL

El siguiente script envía un SMS y procesa la respuesta. No requiere dependencias externas:

<?php
declare(strict_types=1);

$token   = getenv('GTP_SMS_TOKEN');
$payload = json_encode([
    'to'   => '+525512345678',
    'body' => 'Su codigo de verificacion es 482913. Vence en 5 minutos.',
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$ch = curl_init('https://api.grupotecnophone.com/prod/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'User-Agent: MiEmpresa/1.0',
    ],
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error    = curl_error($ch);
curl_close($ch);

if ($response === false) {
    throw new RuntimeException("Error de red: {$error}");
}

$data = json_decode($response, true) ?? [];

if ($httpCode === 200 && ($data['status'] ?? null) === 'success') {
    echo "Enviado. SID: {$data['sid']} - segmentos: {$data['num_segments']}\n";
} else {
    $code = $data['error']['code'] ?? "HTTP_{$httpCode}";
    echo "No enviado ({$code}): " . ($data['error']['message'] ?? $response) . "\n";
}

Respuesta de la API

Si el mensaje fue aceptado, la API responde con HTTP 200 y un JSON como este:

{
  "sid": "sms_20261012143201_39bdafbd",
  "status": "success",
  "to": "+525512345678",
  "body": "Su codigo de verificacion es 482913. Vence en 5 minutos.",
  "encoding": "GSM7",
  "num_chars": 56,
  "num_segments": 1,
  "error": null
}

Guarde el sid: es el identificador con el que podrá conciliar el reporte de entrega del mensaje. El campo num_segments indica cuántos segmentos se cobrarán; vea cómo se calculan los segmentos.

Enviar SMS a varios destinatarios con PHP

Para enviar SMS masivos desde PHP conviene envolver la llamada de cURL en una función y recorrer su lista. Así guarda el sid de cada mensaje y separa los errores.

<?php
function enviarSms(string $to, string $body): array
{
    $ch = curl_init('https://api.grupotecnophone.com/prod/v1/sms/send');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('GTP_SMS_TOKEN'),
            'Content-Type: application/json',
            'User-Agent: MiEmpresa/1.0',
        ],
        CURLOPT_POSTFIELDS     => json_encode(['to' => $to, 'body' => $body]),
    ]);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode((string) $response, true) ?? [];
    if ($httpCode === 200 && ($data['status'] ?? '') === 'success') {
        return $data; // sid, encoding, num_chars, num_segments
    }
    throw new RuntimeException(($data['error']['code'] ?? "HTTP_$httpCode") . ': ' . ($data['error']['message'] ?? ''));
}

$destinatarios = ['+525512345678', '+525598765432'];
foreach ($destinatarios as $numero) {
    try {
        $r = enviarSms($numero, 'Su pedido 1234 ya va en camino.');
        echo "$numero -> {$r['sid']}\n";
    } catch (RuntimeException $e) {
        echo "$numero -> error: {$e->getMessage()}\n";
    }
    usleep(100000); // ritmo moderado para listas grandes
}

Si trabaja con Laravel, vea el ejemplo de envío de SMS con Laravel y colas. Sin programar, también puede enviar SMS masivos desde Excel o CSV.

Para códigos de verificación, siga la guía paso a paso para implementar OTP por SMS en PHP y Laravel.

Enviar un código OTP con PHP

Genere el código con random_int, que es criptográficamente seguro, y guarde solo su hash.

$codigo = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);
enviarSms('+525512345678', "Su codigo de verificacion es $codigo. Vence en 5 minutos.");
// Guarde solo password_hash($codigo, PASSWORD_DEFAULT) y la fecha de vencimiento

Más detalles del flujo en la guía de autenticación OTP por SMS.

Enviar SMS con PHP usando Guzzle

Si su proyecto ya usa Composer, Guzzle simplifica los tiempos de espera y el manejo de errores. Instálelo con composer require guzzlehttp/guzzle y envíe el mismo JSON:

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client([
    'base_uri'    => 'https://api.grupotecnophone.com/prod/v1/',
    'timeout'     => 30,
    'http_errors' => false,
    'headers'     => [
        'Authorization' => 'Bearer ' . getenv('GTP_SMS_TOKEN'),
        'User-Agent'    => 'MiEmpresa/1.0',
    ],
]);

try {
    $res = $client->post('sms/send', ['json' => [
        'to'   => '+525512345678',
        'body' => 'Su pedido 1234 ya va en camino.',
    ]]);
    $data = json_decode((string) $res->getBody(), true) ?? [];

    if ($res->getStatusCode() === 200 && ($data['status'] ?? '') === 'success') {
        echo "Enviado. SID: {$data['sid']}\n";
    } else {
        echo 'No enviado: ' . ($data['error']['code'] ?? 'HTTP_' . $res->getStatusCode()) . "\n";
    }
} catch (GuzzleException $e) {
    echo 'Error de red: ' . $e->getMessage() . "\n";
}

Con http_errors en false, Guzzle no lanza una excepción en los errores 400, 401 o 403, y su código puede leer el objeto error de la respuesta.

Enviar SMS con PHP sin cURL

En servidores donde la extensión cURL no está disponible, puede hacer la misma petición con file_get_contents y un contexto HTTP. Requiere que allow_url_fopen esté activo:

<?php
$context = stream_context_create(['http' => [
    'method'        => 'POST',
    'header'        => implode("\r\n", [
        'Authorization: Bearer ' . getenv('GTP_SMS_TOKEN'),
        'Content-Type: application/json',
        'User-Agent: MiEmpresa/1.0',
    ]),
    'content'       => json_encode(['to' => '+525512345678', 'body' => 'Su cita es manana a las 10:00.']),
    'timeout'       => 30,
    'ignore_errors' => true, // permite leer el JSON de error en respuestas 4xx y 5xx
]]);

$response = file_get_contents('https://api.grupotecnophone.com/prod/v1/sms/send', false, $context);
$data = json_decode((string) $response, true) ?? [];

echo ($data['status'] ?? '') === 'success'
    ? "Enviado. SID: {$data['sid']}\n"
    : 'No enviado: ' . ($data['error']['code'] ?? 'sin respuesta') . "\n";

Resumen de la petición

ElementoValor
MétodoPOST
Endpoint de producciónhttps://api.grupotecnophone.com/prod/v1/sms/send
Endpoint de sandboxhttps://api.grupotecnophone.com/test/v1/sms/send
EncabezadosAuthorization: Bearer con su token, Content-Type: application/json y User-Agent
Cuerpo (JSON)to: número de destino con código de país; body: texto del mensaje
Respuestasid, status, encoding, num_chars, num_segments y error

Errores frecuentes

HTTPCódigoQué significa
400ENCRYPTION_REQUIREDLa conexión exige que to y body viajen cifrados con RSA-OAEP
400ENCRYPTION_NOT_ALLOWEDLa conexión opera en texto plano y se recibió contenido cifrado
400INPUT_PHONE_BLACKLISTEDEl número de destino está en lista negra
400INSUFFICIENT_BALANCESaldo insuficiente para el envío
401—Token ausente o inválido
403—La IP de origen no está autorizada para el token
500—Error interno no esperado

En los errores 400 la respuesta incluye un objeto error con code, code_num y message.

Probar en sandbox

Cambie el endpoint por https://api.grupotecnophone.com/test/v1/sms/send y use el token de sandbox. Ese entorno valida token, IP, payload y cifrado con la misma lógica que producción, pero no envía SMS reales.

Buenas prácticas

  • Defina un timeout y registre cada respuesta con su sid.
  • Ante un error de red sin respuesta, no reenvíe a ciegas: verifique primero para no duplicar el mensaje al usuario.
  • Reintente solo errores 500, con espera progresiva y un número máximo de intentos.
  • Encole los envíos masivos en lugar de enviarlos en el ciclo de una petición web.
  • Si el contenido es sensible, active el cifrado de la conexión; la documentación de la API incluye un ejemplo de cifrado RSA en PHP sin librerías externas.

Vea también la API SMS México, la conexión SMPP y las guías para Laravel, Python, Node.js, Java, C# (.NET) y cURL. Si necesita credenciales de prueba, contáctenos.

Preguntas frecuentes: Enviar SMS con PHP

Scroll al inicio