Intégrez l’envoi de SMS
à votre service.

Démarrage rapide

1. Créez une clé API

   Après l’inscription, l’approbation et la connexion OTP, rendez-vous surGestion des clés APIpour créer une clé.

2. Préparez vos crédits

   L’API utilise les crédits et les tarifs de votre compte. Le montant est débité lors de la prise en charge de l’envoi.

3. Envoyez et suivez vos messages

   Conservez l’ID d’envoi et consultez les résultats via l’API de statut.

Pays pris en charge

GET/api/v1/messages/countries

Consultez via l’API les pays actifs et les tarifs réellement appliqués. Indiquez le pays avec country dans la requête d’envoi et n’incluez que des numéros de ce pays dans une même requête. Les pays sans tarif configuré ne sont pas acceptés.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Authentifiez-vous avec une clé API

Ajoutez l’en-tête ci-dessous à chaque requête API externe. Aucun cookie de session ni code OTP n’est nécessaire.

Authorization: Bearer hex_live_VOTRE_CLÉ_API

La clé complète n’est affichée qu’une seule fois, lors de sa création. Conservez-la dans une variable d’environnement du serveur et jamais dans le code frontend. Une clé révoquée ou un compte suspendu ne peut plus être utilisé. Vous pouvez créer jusqu’à 5 clés.

Envoyez à 1 000 numéros d’un coup

Envoyez un même message à plusieurs numéros. La requête est validée, mise en file d’envoi, puis une réponse est renvoyée immédiatement. Pour envoyer un contenu différent par numéro, utilisez des requêtes distinctes avec une nouvelle Idempotency-Key.

Un seul numéro invalide ou en double entraîne le rejet de toute la requête, sans envoi ni débit. Les doublons sont détectés après conversion au format international.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

Calcul du montant

Nombre de numéros × nombre de segments (segments) × tarif du compteEn UCS-2, un segment contient jusqu’à 70 caractères, puis 67 par segment. En GSM-7 de base, un segment contient jusqu’à 160 caractères, puis 153 par segment. Les caractères étendus comptent double et les emoji selon leur longueur UTF-16. unitPrice et cost sont en USDT. Le tarif de la réponse est celui réellement appliqué ; 0,025 ci-dessus n’est qu’un exemple.

Suivez le résultat de chaque numéro

Utilisez l’id renvoyé par l’API d’envoi. Seuls les envois effectués via l’API par le même compte sont consultables. Cette API renvoie les résultats enregistrés ; pour les derniers résultats opérateur, appelez d’abord l’API d’actualisation ci-dessous.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit va de 1 à 1 000 (100 par défaut), offset de 0 à 1 000 (0 par défaut). Si nextOffset vaut null, c’est la dernière page. summary indique le nombre de numéros par statut. to est renvoyé au format international sans +, et les horodatages en millisecondes Unix. L’ordre des résultats peut différer de l’ordre d’envoi ; identifiez chaque message par son id.

Récupérez le dernier statut de réception

Actualise les résultats enregistrés à partir des journaux de l’opérateur. Aucun corps n’est nécessaire. Relisez ensuite les résultats avec GET. Un même envoi peut être actualisé une fois toutes les 30 secondes. Les journaux de l’opérateur sont disponibles pendant 48 heures après l’envoi. Si un webhook est configuré, les résultats peuvent être mis à jour automatiquement.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated est le nombre de lignes mises à jour. Il peut valoir 0 si l’envoi est encore en file ou s’il n’y a pas de nouveau résultat. Nous recommandons d’appeler GET à intervalles d’au moins 10 secondes et de n’utiliser refresh qu’en cas de besoin.

Comprendre les codes de statut

state de l’envoi

PREPARING en préparation · RUNNING en cours · PAUSED en pause · DONE file traitée · CANCELED annulé

Les opérateurs peuvent ajouter de nouveaux codes : gérez aussi les valeurs de status inconnues. Le motif d’échec est indiqué dans statusName, description et error.

Gérer les erreurs

{ "error": "Crédits insuffisants. Rechargez puis réessayez.", "code": "INSUFFICIENT_CREDITS" }

Chaque clé API permet jusqu’à 120 requêtes par minute, envoi, consultation et actualisation confondus. En cas de limitation, consultez l’en-tête Retry-After. L’API est destinée aux échanges serveur à serveur ; les appels CORS depuis le navigateur ne sont pas pris en charge.

Connectez-vous avec Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Créez une clé de requête une seule fois par opération et réutilisez-la en cas de nouvelle tentative faute de réponse. Renvoyer une opération réussie avec une nouvelle clé crée un envoi distinct.