​

SMS

​

Envoyer un SMS

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Bonjour d'Orbit !"
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

// Les canaux à corps uniquement passent par l'helper générique typé.
const message = await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  from: '+18005551234',          // expéditeur explicite — omettre pour utiliser le défaut tenant
  body: 'Bonjour d'Orbit !',
});

console.log(message.data.id);      // msg_a1b2…
console.log(message.data.status);  // 'queued'

// Pas de SDK ? fetch simple va bien — la forme de la requête se transporte sans changement.
const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+14155552671',
    from: '+18005551234',
    body: 'Bonjour d'Orbit !',
  }),
});
const { data } = await res.json();
console.log(data.id, data.status); // même enveloppe que la réponse curl ci-dessous

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # lit ORBIT_API_KEY

message = client.messages.send_sms(
    to="+14155552671",
    body="Bonjour d'Orbit !",
    from_="+18005551234",  # expéditeur explicite — omettre pour utiliser le défaut tenant
)

print(message["data"]["id"])       # msg_a1b2…
print(message["data"]["status"])   # 'queued'

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Bonjour d'Orbit !",
    From: "+18005551234",  // expéditeur explicite — omettre pour utiliser le défaut du tenant
})
if err != nil {
    panic(err)
}

fmt.Println(msg.Data.ID)      // msg_a1b2…
fmt.Println(msg.Data.Status)  // "queued"

# Une voie d'évitement HTTP brute pour les langues sans SDK typé — tout
# client ou bibliothèque fonctionne tant qu'il peut poser un en-tête et un corps JSON.
send = client.request(
    "POST",
    "/messages/sms",
    json_body: {
        to: "+14155552671",
        from: "+18005551234",
        body: "Bonjour d'Orbit !",
    },
)

puts send.dig("data", "id")       # msg_a1b2…
puts send.dig("data", "status")   # 'queued'

​

Réponse

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "segments": 1,
    "encoding": "GSM-7"
  },
  "meta": {
    "request_id": "req_sms_send",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

• Node.js / fetch (TypeScript) — le SDK ou la valeur de retour de res.json() portent l’enveloppe : message.data.id, message.data.status.
• Python — send_sms renvoie le corps JSON brut comme dict : message["data"]["id"], message["data"]["status"].
• Go — SendSMS décompresse l’enveloppe dans un struct typé : msg.Data.ID, msg.Data.Status.
• Ruby / PHP (voie d’évitement) — client.request renvoie le corps JSON brut : send.dig("data", "id") / $send['data']['id'].

​

Patrons communs

​

Envoie idempotent avec un Idempotency-Key

const message = await orbit.messages.send(
  { channel: 'sms', to: '+14155552671', body: 'Bonjour d'Orbit !' },
  { idempotencyKey: 'job-7a3b9d-checkout-reminder' },  // clé stable sur les retries
);

message = client.messages.send_sms(
    to="+14155552671",
    body="Bonjour d'Orbit !",
    idempotency_key="job-7a3b9d-checkout-reminder",  # clé stable sur les retries
)

​

Paginer GET /messages via les appels listes du SDK

// Boucle de curseur — contrôle explicite.
let cursor: string | undefined;
do {
  const page = await orbit.messages.list({ channel: 'sms', limit: 100, cursor });
  for (const message of page.data) {
    // consommer un message par itération
  }
  cursor = page.meta.pagination.has_more
    ? page.meta.pagination.cursor
    : undefined;
} while (cursor);

// …ou laissez l'itérateur paginer pour vous :
for await (const message of orbit.messages.iter({ channel: 'sms' })) {
  console.log(message.id, message.status);
}

# Le SDK Python n'enveloppe que les ressources centrales — paginez avec la
# voie d'évitement, qui accepte un dict `query` aux côtés de `json_body`.
cursor = None
while True:
    query = {"channel": "sms", "limit": 100}
    if cursor:
        query["cursor"] = cursor
    page = client.request("GET", "/messages", query=query)
    for message in page["data"]:
        # consommer un message par itération
        pass
    pagination = page["meta"]["pagination"]
    if not pagination.get("has_more"):
        break
    cursor = pagination["cursor"]

​

Exemple complet : envoyer, poller, gérer les échecs

​

1. Envoyez le message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Bonjour d'Orbit 🚀 — texte normalisé : 160 caractères ici seraient deux segments UCS-2"
  }'

​

2. Lisez la réponse d’envoi

{
  "data": {
    "id": "msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9",
    "status": "queued",
    "channel": "sms",
    "segments": 2,
    "encoding": "UCS-2"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-09-06T12:00:00Z"
  }
}

​

3. Pollez la ligne

curl https://api.orbit.devotel.io/api/v1/messages/msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9",
    "channel": "sms",
    "direction": "outbound",
    "to": "+14155552671",
    "from": "+18005551234",
    "status": "delivered",
    "segments": 2,
    "encoding": "UCS-2",
    "external_id": "dev-smpp-e9a8b7c6",
    "sent_at": "2026-09-06T12:00:01Z",
    "error_code": null,
    "error_message": null,
    "metadata": {}
  },
  "meta": {
    "request_id": "req_poll_002",
    "timestamp": "2026-09-06T12:00:02Z"
  }
}

​

4. Bifurquez sur les échecs

​

Fondements de la deliverability SMS

​

Choisissez un type d’expéditeur

​

Onboarding via le tableau de bord

1. Ouvrez Channels → SMS dans le tableau de bord.
2. Cliquez Attach Sender et choisissez un type d’expéditeur ci-dessus. Orbit valide la forme (numéro E.164, ID alphanumérique de 3–11, ou référence de bassine) et vérifie si la destination que vous choisissez comme défaut requière l’inscription.
3. Envoyez un message de test à un numéro que vous possédez. Le compositeur montre segments et encoding en ligne, donc vous voyez le coût par segment estimé avant d’envoyer.
4. Si votre port de destination rejette l’attache (US sans campagne 10DLC, pays gaté sans validation d’ID expéditeur), l’assistant vous dirige vers le flux d’inscription — voir les deux sections suivantes.

​

Inscription 10DLC & types de campagnes (US)

​

Encodage et concaténation

​

GSM-7 contre UCS-2

• GSM-7 — l’alphabet GSM 7-bit (ASCII plus quelques extras : @, £, €, quelques grec). Un corps qu’y rentre obtient jusqu’à 160 caractères par segment, ou 153 caractères en envoi multi-parties (7 par segment vont vers l’en-tête UDH de concaténation).
• UCS-2 — tout caractère hors GSM-7 (emoji, CJK, quotes intelligentes, scripts les plus non-Latin) bascule tout le message vers un encodage 16-bit. Un corps obtient jusqu’à 70 caractères par segment, ou 67 en multi-parties.

segments = ceil(chars / per_segment_limit)
per_segment_limit = single_limit         si cela rentre en un segment
                  = single_limit - header  sinon (GSM-7 : 153, UCS-2 : 67)

​

Exemple complet

{
  "segments": 2,
  "encoding": "UCS-2"
}

​

Limites de débit, débit & bassines d’expéditeurs

1. Limite de requête côté API. 100 requêtes/minute par tenant par défaut sur POST /messages/sms, clé par organisation. Au-delà vous recevez 429 RATE_LIMITED ; voyez le guide des limites de débit pour les en-têtes et la gestion des retries. Le tableau complet par canal ci-dessous.
2. Débit côté expéditeur. US 10DLC : un plafond de segment par jour, par numéro fixé par votre étage de vetting. Ailleurs : ce que la route de destination supporte par expéditeur.

​

Cycle de vie de l’état du message

• submitted_no_receipt — le fournisseur a accepté l’envoi, aucune DLR n’est revenue dans la fenêtre de grâce SMPP de 30 minutes. Étiqueté intermédiaire (is_terminal: false) parce qu’une delivered tardive ou une échec DLR peut encore atterrir et écrire par-dessus. Traitez-le comme résultat inconnu, pas une livraison et pas un échec.
• expired — une DLR a arrivé après que la fenêtre de laisse-arrière tardive se soit fermée. Ligne fermée, résultat non connaissable ; fan-out sur message.failed.
• cancelled — accessible seulement par vous ; aucun webhook ne tir jamais pour ça.

​

Dépannage

​

Tarification

​

Fonctionnalités

• Messagerie A2P et P2P — support application-à-personne et personne-à-personne
• Portée globale — 190+ pays via le réseau d’agrégations de Devotel
• Rapports de livraison — webhooks d’état en temps réel pour chaque message
• Messages concaténés — SMS multi-parties géré de manière transparente (jusqu’à 10 segments)
• Validation E.164 — validation automatique du format du numéro de téléphone
• Support Unicode — encodage GSM-7 et UCS-2 complet avec détection automatique et normalisation des quotes intelligentes
• ID expéditeur — ID expéditeurs alphanumériques là où les réglementations locales les supportent, inscrits-gâtés là où requis

​

Limites de débit