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
| Elemento | Valor |
|---|---|
| Método | POST |
| Endpoint de producción | https://api.grupotecnophone.com/prod/v1/sms/send |
| Endpoint de sandbox | https://api.grupotecnophone.com/test/v1/sms/send |
| Encabezados | Authorization: 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 |
| Respuesta | sid, status, encoding, num_chars, num_segments y error |
Errores frecuentes
| HTTP | Código | Qué significa |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED | La conexión exige que to y body viajen cifrados con RSA-OAEP |
| 400 | ENCRYPTION_NOT_ALLOWED | La conexión opera en texto plano y se recibió contenido cifrado |
| 400 | INPUT_PHONE_BLACKLISTED | El número de destino está en lista negra |
| 400 | INSUFFICIENT_BALANCE | Saldo 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.


