Before you start
- An API connection created in the web panel (app.grupotecnophone.com), with its Bearer Token for sandbox or production.
- Your server’s public IP registered as authorized for that token.
- A User-Agent header that identifies your application, for example
MyCompany/1.0. - PHP 7.4 or later with the cURL extension enabled.
Store the token in an environment variable (in these examples, GTP_SMS_TOKEN) and never include it in the code of a mobile app or website: API calls must always come from your backend, from an authorized IP.
Send an SMS with PHP and cURL
The following script sends an SMS and processes the response. It requires no external dependencies:
<?php
declare(strict_types=1);
$token = getenv('GTP_SMS_TOKEN');
$payload = json_encode([
'to' => '+525512345678',
'body' => 'Your verification code is 482913. It expires in 5 minutes.',
], 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("Network error: {$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 "Not sent ({$code}): " . ($data['error']['message'] ?? $response) . "\n";
}API response
If the message was accepted, the API responds with HTTP 200 and a JSON body like this:
{
"sid": "sms_20261012143201_39bdafbd",
"status": "success",
"to": "+525512345678",
"body": "Your verification code is 482913. It expires in 5 minutes.",
"encoding": "GSM7",
"num_chars": 56,
"num_segments": 1,
"error": null
}Store the sid: it is the identifier you will use to reconcile the message’s delivery report. The num_segments field indicates how many segments will be billed; see how segments are calculated.
Send SMS to multiple recipients with PHP
To send bulk SMS from PHP, wrap the cURL call in a function and loop through your list. That way you store the sid of each message and keep errors separate.
<?php
function sendSms(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'] ?? ''));
}
$recipients = ['+525512345678', '+525598765432'];
foreach ($recipients as $number) {
try {
$r = sendSms($number, 'Your order 1234 is on its way.');
echo "$number -> {$r['sid']}\n";
} catch (RuntimeException $e) {
echo "$number -> error: {$e->getMessage()}\n";
}
usleep(100000); // moderate pace for large lists
}If you work with Laravel, see the example of sending SMS with Laravel and queues. Without coding, you can also send bulk SMS from Excel or CSV.
Send an OTP code with PHP
Generate the code with random_int, which is cryptographically secure, and store only its hash.
$otp = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);
sendSms('+525512345678', "Your verification code is $otp. It expires in 5 minutes.");
// Store only password_hash($otp, PASSWORD_DEFAULT) and the expiry dateMore details on the flow in the guide to SMS OTP authentication.
Common errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED | The connection requires to and body to be encrypted with RSA-OAEP |
| 400 | ENCRYPTION_NOT_ALLOWED | The connection operates in plain text and encrypted content was received |
| 400 | INPUT_PHONE_BLACKLISTED | The destination number is on the blacklist |
| 400 | INSUFFICIENT_BALANCE | Insufficient balance for the send |
| 401 | — | Missing or invalid token |
| 403 | — | The source IP is not authorized for the token |
| 500 | — | Unexpected internal error |
On 400 errors the response includes an error object with code, code_num and message.
Test in sandbox
Change the endpoint to https://api.grupotecnophone.com/test/v1/sms/send and use the sandbox token. That environment validates the token, IP, payload and encryption with the same logic as production, but does not send real SMS.
Best practices
- Set a timeout and log each response with its
sid. - After a network error with no response, do not resend blindly: check first so you don’t duplicate the message to the user.
- Retry only 500 errors, with progressive backoff and a maximum number of attempts.
- Queue bulk sends instead of sending them within a web request cycle.
- If the content is sensitive, enable connection encryption; the API documentation includes an RSA encryption example in PHP without external libraries.
See also the SMS API for Mexico, the SMPP connection and the guides for Laravel, Python, Node.js and Java. If you need test credentials, contact us.
