Aperçu
L'API BroadNet est une API REST utilisant HTTPS. Vous vous authentifiez à l'aide d'un jeton Bearer, envoyez une requête JSON ou multipart à un point de terminaison de canal et recevez en retour un identifiant de message ou un résumé du lot. L'état de la livraison est transmis à l'URL du webhook configurée sur votre compte. L'API complète, comprenant 329 chemins et 376 opérations réparties sur huit canaux, est publiée sous la forme d'une spécification OpenAPI 3.1. Les exemples présentés sur cette page utilisent curl, Node.js, Python, Java, C#, Go, Ruby et le SDK TypeScript officiel.
Environnements
Les exemples de cette page appellent l'URL de base de la production. Les identifiants de test, et l'adresse où envoyer le trafic de test, sont fournis avec votre accès de test : demandez-le sur /signup, nous répondons sous un jour ouvré.
| Environnement | URL de base |
|---|---|
| Production | https://api.broadnet.me |
Authentification
Chaque requête contient votre jeton d'accès dans un en-tête HTTP. Ce jeton est émis par compte et provient de votre compte BroadNet. Les exemples de cette page le lisent à partir d'une variable d'environnement appelée BROADNET_TOKEN.
Authorization: Bearer $BROADNET_TOKENSi le jeton est manquant ou invalide, l'API renvoie une erreur HTTP 401 et un corps d'erreur JSON au format standard décrit ci-dessous. Aucun appel ne permet d'échanger un nom d'utilisateur et un mot de passe contre un jeton.
Envoyer un SMS
Envoyez un SMS avec un corps JSON. Les quatre champs obligatoires sont l'expéditeur, le destinataire, le texte et l'encodage.
Champs obligatoires
| Champ | Type de données | Description |
|---|---|---|
| senderId | string | Votre identifiant d'expéditeur approuvé, affiché au destinataire comme étant l'expéditeur. |
| destinationNumber | string | Numéro du destinataire avec l'indicatif du pays, uniquement des chiffres, sans signe plus. |
| message | string | Le texte du message. |
| messageType | string | Encodage : TEXT pour le texte GSM-7, UNICODE pour l’arabe, les émojis et autres scripts. |
Champs facultatifs
| Champ | Type de données | Description |
|---|---|---|
| charCount | integer | Nombre de caractères, tel que renvoyé par /sms/identify. |
| smsParts | integer | Nombre de segments, tel que renvoyé par /sms/identify. |
| charLimit | integer | Caractères par segment, tels que renvoyés par /sms/identify. |
| expiryHour | integer | Période de validité en heures. |
| isSchedule | boolean | Définissez cette option sur « vrai » pour programmer l'envoi du message au lieu de l'envoyer immédiatement. |
| delay | number | Attendez avant d'envoyer. |
| gmt | string | Décalage horaire GMT utilisé pour la planification. |
| time | — | Heure d'envoi programmée (avec isSchedule). |
| repeat | — | Paramétrage de répétition pour les envois programmés. |
| peId | string | Identifiant principal de l'entité, lorsqu'un organisme de réglementation l'exige. |
| templateId | string | Identifiant du modèle enregistré, lorsqu'un organisme de réglementation l'exige. |
| telemarketerId | string | Identification du télévendeur, lorsque la réglementation l'exige. |
| campaignName | string | Votre étiquette pour le signalement. |
curl -X POST https://api.broadnet.me/sms/sendSms \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}'
# 200 OK → response body is the message ID, e.g. 2603121407537573731// Node.js 18+ (fetch)
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: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
}),
});
console.log(await res.text()); // message IDimport os, requests
r = requests.post(
"https://api.broadnet.me/sms/sendSms",
headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
json={
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT",
},
)
print(r.status_code, r.text) # message ID// Java 11+ — java.net.http is built in, nothing to install
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendSms {
public static void main(String[] args) throws Exception {
String json = "{"
+ "\"senderId\": \"BroadNet\", "
+ "\"destinationNumber\": \"447700900123\", "
+ "\"message\": \"Your verification code is 482913\", "
+ "\"messageType\": \"TEXT\""
+ "}";
HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.broadnet.me/sms/sendSms"))
.header("Authorization", "Bearer " + System.getenv("BROADNET_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.statusCode() + " " + res.body()); // 200 + message ID
}
}// .NET 6+ console app (Program.cs) — HttpClient is built in, no NuGet package
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("BROADNET_TOKEN"));
// PostAsJsonAsync sends Content-Type: application/json
var res = await http.PostAsJsonAsync("https://api.broadnet.me/sms/sendSms", new
{
senderId = "BroadNet",
destinationNumber = "447700900123",
message = "Your verification code is 482913",
messageType = "TEXT",
});
var id = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode} {id}"); // 200 + message IDpackage main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body := []byte(`{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}`)
req, err := http.NewRequest(http.MethodPost, "https://api.broadnet.me/sms/sendSms", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BROADNET_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
id, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(id)) // 200 + message ID
}require "net/http"
require "json"
uri = URI("https://api.broadnet.me/sms/sendSms")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('BROADNET_TOKEN')}"
req["Content-Type"] = "application/json"
req.body = {
senderId: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts "#{res.code} #{res.body}" # 200 + message ID// npm install @broadnet/cpaas-sdk axios
import { Configuration, SMSSMSApi } from "@broadnet/cpaas-sdk";
const sms = new SMSSMSApi(
new Configuration({
basePath: "https://api.broadnet.me",
accessToken: process.env.BROADNET_TOKEN!,
}),
);
const res = await sms.smsSendsmsPost({
sMSSmsRequest: {
senderId: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
},
});
console.log(res.data); // message IDUn appel réussi renvoie HTTP 200 et l'identifiant du message comme corps de la réponse, sans enveloppe JSON :
HTTP/1.1 200 OK
2603121407537573731Encodage et segments
Le champ messageType définit l'encodage, qui détermine le nombre de caractères contenus dans un segment SMS. Les messages longs sont divisés en segments puis réassemblés sur le téléphone.
| messageType | SMS unique | Par segment (message long) | Utilisation pour |
|---|---|---|---|
| TEXT | 160 | 153 | Caractères GSM-7 uniquement. |
| UNICODE | 70 | 67 | Tout autre système d'écriture : arabe, cyrillique, émoji, caractères accentués hors GSM-7. |
Vous ne savez pas quel encodage utiliser ? Demandez à l’API. Le point de terminaison « identify » analyse un message et renvoie son encodage, le nombre de caractères, le nombre de segments et le nombre de caractères par segment, que vous pouvez transmettre directement dans la requête d’envoi.
curl -X POST https://api.broadnet.me/sms/identify \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "message": "Your verification code is 482913" }'{
"message": "Your verification code is 482913",
"messageType": "TEXT",
"smscount": 1,
"charCount": 32,
"charLimit": 160
}Essayez sans écrire de code dans le Compteur de caractères SMS.
Formats de numéros de téléphone
Les numéros de destination sont composés de l'indicatif du pays suivi du numéro national, en chiffres uniquement. N'ajoutez pas de signe plus au début, de préfixe 00, d'espaces, de tirets ni de parenthèses.
| Exemple | Résultat | Pourquoi |
|---|---|---|
| 447700900123 | Valide | Indicatif pays 44 plus le numéro national, chiffres uniquement. |
| +44 7700 900123 | Rejeter | Contient un signe plus et des espaces. Supprimez-les d'abord. |
| 07700900123 | Rejeter | Format national avec un zéro initial et sans indicatif de pays. |
SMS en masse
Pour envoyer un message à plusieurs destinataires, téléchargez un fichier de numéros via une requête multipart. Cette requête comporte deux parties : la première, destinationNumberFile, est un fichier CSV ou TXT contenant des numéros ; la seconde, bulkRequest, est une chaîne JSON incluant l’expéditeur, le texte, l’encodage et le nom de la campagne.
curl -X POST https://api.broadnet.me/sms/sendbulk \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-F destinationNumberFile=@recipients.csv \
-F 'bulkRequest={"senderId":"BroadNet","message":"Your statement is ready","messageType":"TEXT","campaignName":"statements"}'{
"status": "success",
"bulkSessionId": "1_20260228105000887",
"credits": "9966465.42850",
"deductcredits": "0.60000",
"bulkListInfo": {
"total": 4,
"validCount": 3,
"invalidCount": 0,
"duplicate": 1
}
}L'objet bulkListInfo indique le nombre de nombres acceptés, invalides et en double. Une fois la tâche lancée, vous pouvez la gérer par son ID de lot :
| Méthode HTTP | Chemin du point de terminaison | Description |
|---|---|---|
| GET | /sms/list | Listez vos tâches groupées avec le nombre de tâches traitées et en attente. |
| GET | /sms/pause?batch_Id=… | Mettre en pause une tâche en cours. |
| GET | /sms/resume?batch_Id=… | Reprendre un travail mis en pause. |
| DELETE | /sms/abort?batch_Id=… | Annulation d'une tâche ; les messages en attente ne sont pas envoyés. |
| POST | /sms/resend | Renvoyer les messages d'une tâche précédente. |
| POST | /sms/send-now | Déclenchez immédiatement une tâche planifiée. |
| POST | /sms/auto-schedule | Planifiez automatiquement une tâche en masse. |
# List your bulk jobs (each entry's id is the batch_Id below)
curl https://api.broadnet.me/sms/list \
-H "Authorization: Bearer $BROADNET_TOKEN"
# Pause, then resume, a running job
curl "https://api.broadnet.me/sms/pause?batch_Id=1024" \
-H "Authorization: Bearer $BROADNET_TOKEN"
curl "https://api.broadnet.me/sms/resume?batch_Id=1024" \
-H "Authorization: Bearer $BROADNET_TOKEN"Recherche de numéro
Vérifiez le statut d'un numéro (HLR et MNP) avant de l'envoyer, par exemple pour nettoyer une liste ou gérer les numéros transférés. Transmettez le numéro comme paramètre de requête `destinationNumber`. Le paramètre optionnel `reqType` sélectionne le type de recherche.
curl -X POST "https://api.broadnet.me/sms/lookup?destinationNumber=447700900123" \
-H "Authorization: Bearer $BROADNET_TOKEN"État de la livraison
L'état de livraison est transmis à l'URL du webhook configurée sur votre compte BroadNet à mesure que chaque message progresse dans son cycle de vie. Les statuts des messages suivent ce cycle de vie :
SUBMITTED· Accepté par BroadNet et mis en file d'attente pour le réseau.SENT· Remis à l'opérateur ou à la chaîne.DELIVERED· Confirmé sur le téléphone.READ· Ouvert par le destinataire, sur des canaux qui signalent les lectures, tels que WhatsApp.FAILED / REJECTED· Non livré.
Vous pouvez également interroger le statut. Pour WhatsApp, le point de terminaison bulk-insights renvoie le statut de chaque destinataire d'un lot. Pour les envois SMS groupés, le point de terminaison list renvoie le nombre de messages traités et en attente.
Erreurs
Un jeton Bearer manquant ou invalide est rejeté par la passerelle API avant que la requête n'atteigne l'API. La passerelle renvoie HTTP 401 avec un corps JSON contenant deux champs : error et message.
{
"error": "Unauthorized",
"message": "Missing Authorization token"
}Les erreurs renvoyées par l'API elle-même, comme une erreur de validation 400, retournent un corps JSON appelé ExceptionResponse, avec cinq champs : status, error, message, errorCode et requestUri. Les valeurs ci-dessous sont des espaces réservés.
{
"status": 400,
"error": "Bad Request",
"message": "…",
"errorCode": "…",
"requestUri": "/sms/sendSms"
}| Statut | Signification |
|---|---|
| 200 | Succès. |
| 400 | Requête incorrecte : erreur de validation ou champ obligatoire manquant. |
| 401 | Jeton Bearer manquant ou invalide. |
| 403 | Le jeton est valide mais n'est pas autorisé à appeler cette opération. |
| 500 | Erreur serveur inattendue. Veuillez réessayer plus tard. |
Ne réessayez qu'en cas d'erreurs réseau et de réponses 5xx, avec un délai exponentiel. Corrigez les erreurs 4xx au lieu de les réessayer. Si votre compte est également lié via SMPP, les soumissions renvoient les codes d'état SMPP standard, répertoriés dans le Guide du protocole SMPP.
Autres canaux de messagerie
Le même jeton et la même URL de base fonctionnent pour tous les canaux. Ce sont les points de terminaison d'envoi ; la spécification OpenAPI documente leurs champs et les points de terminaison de gestion associés (modèles, contacts, rapports).
| Canal de messagerie | Méthode HTTP | Chemin du point de terminaison | Description |
|---|---|---|---|
| SMS | POST | /sms/sendSms | Message unique (JSON). |
| SMS | POST | /sms/sendbulk | Traitement en masse à partir d'un fichier (multipart). |
| POST | /whatsapp/message/sendbulk | Texte, médias, modèles, interactif (multipartite). | |
| RCS | POST | /rcs/message/sendbulk | Messages RCS (multiparties). |
| Telegram | POST | /telegram-sms/send | Messages Telegram. |
| POST | /email/email-service/send | Courriel avec objet, corps et destinataires. | |
| Messenger | POST | /messenger/message/sendbulk | Messages Facebook Messenger (en plusieurs parties). |
| POST | /instagram/message/sendbulk | Messages Instagram (en plusieurs parties). | |
| Push | POST | /push/message/send | Notifications push (JSON). |
Un modèle d'envoi WhatsApp, par exemple :
curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-F batchId=0 \
-F campaignName=order-updates \
-F destinationNo=447700900123 \
-F messageType=TEMPLATE \
-F templateName=order_update \
-F templateLanguage=en_US \
-F bodyTemplateVariables=INV-400Définissez batchId sur 0 pour démarrer un nouveau lot. Le champ destinationNo accepte plusieurs nombres séparés par des virgules. La réponse contient l'identifiant du lot que vous utiliserez pour consulter le statut de chaque destinataire.
Kit de développement logiciel SDK TypeScript
BroadNet publie un SDK officiel, pour TypeScript et Node.js : @broadnet/cpaas-sdk Disponible sur npm, ce module est généré à partir de la spécification BroadNet OpenAPI, inclut des modules CommonJS et ES avec des définitions de types complètes, et propose une classe API par fonctionnalité de canal. Sa seule dépendance d'exécution est axios, que npm installe avec lui.
npm install @broadnet/cpaas-sdk axiosimport { Configuration, WhatsAppWhatsAppMessagingAPIApi } from "@broadnet/cpaas-sdk";
const wa = new WhatsAppWhatsAppMessagingAPIApi(
new Configuration({
basePath: "https://api.broadnet.me",
accessToken: process.env.BROADNET_TOKEN!,
}),
);
const res = await wa.whatsappMessageSendbulkPost({
campaignName: "order-updates",
messageType: "TEXT",
destinationNo: "447700900123",
content: "Your order has shipped.",
});
console.log(res.data); // batchId + per-file acceptance countsPour tout autre langage, appelez directement l'API REST (les exemples Node.js, Python, Java, C#, Go et Ruby ci-dessus n'utilisent pas la bibliothèque BroadNet) ou générez un client à partir de la spécification OpenAPI.
Spécification OpenAPI
L'API complète est décrite dans un seul fichier OpenAPI 3.1 : 329 chemins et 376 opérations réparties sur huit canaux. Il s'agit d'une copie publique de la spécification dont les exemples internes ont été supprimés. Importez-la dans Postman ou Insomnia, explorez-la dans Swagger UI ou générez un client.
curl -O https://www.broadnet.me/developers/openapi.yaml
# Generate a client in any language, e.g. Python
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml -g python -o broadnet-pythonVous préférez Postman ? Importez le fichier de spécifications pour obtenir toutes les opérations, ou commencez par une petite collection des appels essentiels.
API HTTP héritée (/websmpp)
Les comptes créés sur la plateforme BroadNet compatible SMPP peuvent utiliser l'ancienne API HTTP via le chemin /websmpp. Celle-ci reste opérationnelle pour les intégrations existantes et est documentée dans la spécification OpenAPI. Elle utilise les identifiants (nom d'utilisateur et mot de passe, ou clé d'accès) comme paramètres de requête, au lieu d'un jeton Bearer. Les nouvelles intégrations doivent utiliser l'API REST décrite ci-dessus.
| Méthode HTTP | Chemin du point de terminaison | Description |
|---|---|---|
| GET | /websmpp/websms | Envoyez un SMS. Ajoutez une heure et un décalage horaire (GMT) pour le programmer.user, pass (or accesskey), sid, mno, type, text, schtime, gmt |
| POST | /websmpp/json/sms | Envoyez-le avec un objet de campagne JSON contenant les informations d'identification, l'expéditeur, les numéros et le texte.campaign { username, password, sender, gsm, text, type } |
| GET | /websmpp/websmsstatus | Statut d'un message soumis, indiqué par son ID de réponse.respid, format |
| POST | /websmpp/api/dlrreport | Rapport de livraison pour une période donnée, sous forme de feuille de calcul.username, pass, from_date, to_date |
| GET | /websmpp/hlr/lookup | Recherche HLR pour un numéro.username, password, destination |
# Legacy HTTP API — credentials as query parameters (existing integrations only)
curl "https://api.broadnet.me/websmpp/websms?user=USERNAME&pass=PASSWORD&sid=BroadNet&mno=447700900123&type=1&text=Hello"
# Status of a submitted message
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=MESSAGE_ID&format=json"Foire aux questions
Comment puis-je m'authentifier ?
Envoyez votre jeton d'accès dans un en-tête Authorization: Bearer à chaque requête. Ce jeton provient de votre compte BroadNet ; l'API n'effectue aucune création de jeton. Un jeton manquant ou invalide est rejeté par la passerelle API avec HTTP 401 et un corps JSON de deux champs, error et message. Conservez le jeton dans une variable d'environnement ou un gestionnaire de secrets, jamais dans un système de contrôle de version ni dans le code côté client.
Quelle est l'URL de base ?
Chaque exemple appelle la production, https://api.broadnet.me. Les identifiants de test, et l'adresse où envoyer le trafic de test, sont fournis avec votre accès de test : demandez-le sur /signup, nous répondons sous un jour ouvré.
Comment envoyer du texte arabe ou autre texte Unicode ?
Définissez le type de message sur UNICODE. Utilisez TEXT uniquement si tous les caractères appartiennent à l'alphabet GSM-7. En cas de doute, appelez POST /sms/identify avec le message : elle renverra le type de message, le nombre de caractères, le nombre de segments et le nombre de caractères par segment.
Qu'est-ce qu'un envoi réussi renvoie ?
POST /sms/sendSms renvoie HTTP 200 et l'identifiant du message comme corps de réponse. Les envois groupés renvoient un objet JSON contenant status, bulkSessionId, credits, deductcredits et bulkListInfo.
Comment envoyer un SMS à plusieurs destinataires ?
Utilisez la requête POST /sms/sendbulk avec un envoi en plusieurs parties : destinationNumberFile est un fichier CSV ou TXT contenant des numéros et bulkRequest est une chaîne JSON avec senderId, message, messageType et campaignName. Les tâches peuvent ensuite être listées, mises en pause, reprises ou annulées par leur ID de lot.
Comment puis-je obtenir le statut de ma livraison ?
Le statut de livraison est transmis à l'URL du webhook configurée sur votre compte. Pour WhatsApp, le statut de chaque destinataire est également disponible à l'adresse /whatsapp/message/bulk-insights.
Existe-t-il un SDK ?
Oui, il existe un SDK officiel TypeScript / Node.js, disponible sur npm sous le nom @broadnet/cpaas-sdk et généré à partir de la spécification OpenAPI BroadNet. Pour tout autre langage, vous pouvez appeler directement l'API REST ou générer un client à partir de la spécification OpenAPI 3.1 disponible dans le fichier /developers/openapi.yaml.
Qu'est-ce que l'API /websmpp ?
L'API HTTP héritée est conservée pour les intégrations SMPP existantes. Elle utilise les identifiants comme paramètres de requête. Les nouvelles intégrations doivent utiliser l'API REST à jeton Bearer décrite sur cette page.