Envoyer un SMS par API : exemples Python, Node.js, PHP et cURL

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "447700900123",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

// Node.js 18+ (fetch intégré)
const res = await fetch("https://api.broadnet.me/sms/sendSms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "OmniDemo",
    destinationNumber: "447700900123",
    message: "Your OmniDemo code is 482913",
    messageType: "TEXT",
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const messageId = await res.text(); // identifiant du message en texte brut

import os
import requests

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "447700900123",
        "message": "Your OmniDemo code is 482913",
        "messageType": "TEXT",
    },
    timeout=15,
)
r.raise_for_status()
message_id = r.text  # identifiant du message en texte brut, pas du JSON

<?php
$payload = json_encode([
    "senderId" => "OmniDemo",
    "destinationNumber" => "447700900123",
    "message" => "Your OmniDemo code is 482913",
    "messageType" => "TEXT",
]);

$ch = curl_init("https://api.broadnet.me/sms/sendSms");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BROADNET_TOKEN"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$messageId = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status . " " . $messageId . PHP_EOL;

2603121407537573731

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "971500000000",
        "message": "رمز التحقق الخاص بك هو 482913",
        "messageType": "UNICODE",
        "campaignName": "login-otp",
    },
    timeout=15,
)

Comment compter les segments avant l'envoi ?

Appelez POST /sms/identify avec le message. Il renvoie l'encodage détecté, le nombre de caractères, le nombre de segments et la limite par segment.

curl -X POST https://api.broadnet.me/sms/identify \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your OmniDemo code is 482913" }'

{
  "message": "Your OmniDemo code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 28,
  "charLimit": 160
}

Vous pouvez transmettre smsParts (issu de smscount), charCount et charLimit dans une requête d'envoi. Le texte GSM-7 peut être étiqueté GSM-7 dans la réponse ; envoyez-le en TEXT.

Comment envoyer à de nombreux numéros ?

Utilisez POST /sms/sendbulk, une requête multipart/form-data avec un fichier de destinataires et une chaîne JSON de paramètres.

curl -X POST https://api.broadnet.me/sms/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F destinationNumberFile=@recipients.csv \
  -F 'bulkRequest={"senderId":"OmniDemo","message":"Your statement is ready in the app.","messageType":"TEXT","campaignName":"oct-statements","allowDuplicate":false}'

import json
import os
import requests

bulk_request = {
    "senderId": "OmniDemo",
    "message": "Your statement is ready in the app.",
    "messageType": "TEXT",
    "campaignName": "oct-statements",
    "allowDuplicate": False,
}

with open("recipients.csv", "rb") as f:
    r = requests.post(
        "https://api.broadnet.me/sms/sendbulk",
        headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
        files={"destinationNumberFile": ("recipients.csv", f, "text/csv")},
        data={"bulkRequest": json.dumps(bulk_request)},
        timeout=60,
    )
print(r.json())

La réponse comprend bulkSessionId et un objet bulkListInfo avec total, validCount, invalidCount et duplicate. Stockez bulkSessionId avec la campagne. Les tâches peuvent être listées, mises en pause, reprises et abandonnées via les points de terminaison de la référence. Vous pouvez aussi vérifier les numéros avant un gros envoi avec POST /sms/lookup ; voir notre guide du HLR lookup.

Comment recevoir le statut de livraison ?

Les statuts de livraison sont poussés vers l'URL de webhook configurée sur votre compte. Un message passe par SUBMITTED et SENT jusqu'à DELIVERED, ou se termine en FAILED ou REJECTED. Vous communiquez à notre équipe l'URL HTTPS publique, et les revendeurs peuvent avoir un webhook par sous-compte.

Les champs de la charge utile varient selon le canal et la spécification de l'API ne définit pas de schéma de webhook unique : journalisez d'abord le corps brut et associez les champs à partir d'un événement réel de votre compte. Un récepteur minimal stocke l'événement et accuse réception rapidement :

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // votre stockage ; traitement asynchrone
  res.sendStatus(200);             // accuser réception rapidement
});

app.listen(3000);

Rendez le traitement idempotent, car le même statut peut arriver deux fois, et ne laissez jamais un SENT tardif écraser un DELIVERED déjà stocké. Si votre point de terminaison était indisponible, POST /sms/resendDlr renvoie les accusés pour une plage de dates :

curl -X POST https://api.broadnet.me/sms/resendDlr \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-10-09",
    "endDate": "2026-10-10",
    "senderId": "OmniDemo",
    "messageStatus": "DELIVERED"
  }'

Pour en savoir plus, consultez le guide des webhooks et les statuts de livraison des messages expliqués.

Comment gérer les erreurs et éviter les doublons ?

Traitez d'abord le statut HTTP, puis le corps de l'erreur. Ne réessayez que sur les erreurs réseau, 429 et 5xx.

Les erreurs levées par l'API utilisent un corps JSON à cinq champs : status, error, message, errorCode et requestUri. La limite REST documentée par défaut est de 200 requêtes par seconde en continu ; les limites de votre compte sont confirmées avec vos identifiants.

L'API n'accepte aucune clé d'idempotence. Une requête peut aboutir alors que sa réponse est perdue, et un nouvel essai à l'aveugle envoie alors deux fois. Écrivez une ligne « en attente » portant votre propre identifiant d'opération avant l'appel, stockez l'identifiant de message renvoyé et, après un délai d'attente dépassé, cherchez un statut de webhook avant de renvoyer. Pour les envois en masse, réglez allowDuplicate sur false. Les détails figurent dans Erreurs et limites.

Exemple concret : des codes de connexion pour une application régionale

« Souq Rafiq » (société fictive), enseigne de distribution aux Émirats arabes unis, envoie des codes de connexion par SMS.

1. Le service d'authentification génère un code à six chiffres, stocke un hash avec une expiration de cinq minutes et écrit une ligne d'envoi pending.
2. Il appelle /sms/sendSms avec messageType=UNICODE pour les utilisateurs arabophones et TEXT pour les anglophones.
3. Sur un 200, il stocke l'identifiant du message.
4. Le gestionnaire de webhook marque la ligne DELIVERED, FAILED ou REJECTED.
5. Si le statut n'est pas DELIVERED après une courte attente, l'application propose un renvoi et, si c'est configuré, un autre canal. Voir le repli entre canaux.
6. Des limites sur les demandes de code par numéro et par IP protègent contre les abus ; voir prévention du SMS pumping.

Quelles sont les erreurs courantes ?

• Appeler r.json() sur la réponse d'envoi. C'est du texte brut.
• Mauvais noms de champs. Utilisez senderId, destinationNumber et message ; des champs comme to, from ou text ne font pas partie de ce point de terminaison.
• Signes plus et zéros initiaux dans les numéros.
• Oublier UNICODE pour l'arabe, ce qui déforme le texte.
• Sender ID non enregistrés. Certains pays les bloquent ou les remplacent ; consultez les règles de sender ID de votre destination et demandez-nous de gérer l'enregistrement.
• Considérer 200 comme « délivré ».
• Jeton dans une application mobile ou un navigateur, où n'importe qui peut l'extraire.
• Limites : ce guide présente la requête courante. Les champs facultatifs comme les formats de planification doivent être confirmés avec notre équipe.

Comment OmniChannels.ai vous aide

OmniChannels.ai envoie du SMS A2P via la connectivité opérateur directe de BroadNet, avec SMS bidirectionnel, sender ID, Unicode et arabe, HLR lookup et SMPP 3.4 pour les volumes élevés. L'API REST disponible sur https://api.broadnet.me utilise un jeton Bearer et couvre aussi WhatsApp, RCS et d'autres canaux, avec des statuts de livraison normalisés dans un format de webhook unique. Notre équipe prépare avec vous les enregistrements de sender ID. Consultez la référence de l'API SMS ou le canal SMS.