Envoyer et recevoir des messages

Ce guide vous emmène d’une clé API à un flux de messages bidirectionnel qui fonctionne : envoyez un message sortant, suivez sa livraison et recevez la réponse sur votre propre serveur. L’exemple utilise le SMS — le même schéma en trois étapes (envoyer → suivre → recevoir) s’applique à WhatsApp, RCS, Viber et e-mail, chacun sur son propre endpoint. Vous allez :

Envoyer un message
Suivre la livraison
Recevoir des messages entrants
Répondre à un message entrant

Prérequis

Une clé API depuis Paramètres → Clés API. Utilisez une clé sandbox (dv_test_sk_…) pendant le développement — les envois sandbox sont gratuits et simulés, et renvoient des accusés de livraison déterministes pour que vous puissiez exercer les deux chemins, succès et erreur. Passez à une clé live (dv_live_sk_…) pour la production.
Un numéro expéditeur capable d’envoyer sur le canal utilisé. Pour le SMS, c’est un numéro SMS-compatible que vous possédez (recherchez-le et achetez-le via l’API Numbers ou via Dashboard → Numéros). Si vous omettez from, Orbit choisit un expéditeur éligible pour la destination.
Une URL HTTPS publique pour l’étape de réception. Tout outil de tunnel convient en développement.

Toutes les requêtes visent une seule URL de base — le sandbox utilise le même hôte, sélectionné par votre clé et non par un autre domaine :

https://api.orbit.devotel.io/api/v1

Chaque requête porte votre clé dans l’en-tête X-API-Key.

1. Envoyer un message

Envoyez un SMS avec POST /messages/sms. Seuls to et body sont obligatoires ; from est facultatif.

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" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Your order #1234 has shipped. Reply STATUS for tracking."
  }'

La réponse est 202 Accepted — le message est persisté et mis en file pour la livraison, pas encore remis à l’opérateur. Les champs vivent sous data ; meta porte le request_id que vous devez journaliser pour le support.

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "direction": "outbound",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-07-20T00:00:00Z"
  }
}

L’id (msg_ suivi de 32 caractères hexadécimaux) est l’identifiant utilisé par tous les appels qui suivent — les requêtes de statut, les webhooks de livraison et la trace du message l’utilisent tous. Les réponses sandbox ajoutent "test_mode": true à meta.

Envoyez toujours une Idempotency-Key lors des envois. Rejouer la même clé et le même corps dans les 24 heures renvoie la réponse originale au lieu d’envoyer un doublon ; rejouer avec un corps différent renvoie 409 IDEMPOTENCY_KEY_REUSED.

Autres canaux

Chaque canal a son propre endpoint sous le préfixe /messages, avec une forme de corps adaptée à ce canal. Il n’y a pas de route unique polymorphe sur le canal — choisissez l’endpoint qui correspond à votre canal :

Canal	Endpoint	Référence
SMS	`POST /messages/sms`	API Messaging
WhatsApp	`POST /messages/whatsapp`	Canal WhatsApp
RCS	`POST /messages/rcs`	Canal RCS
Viber	`POST /messages/viber`	Canal Viber
E-mail	`POST /messages/email`	Canal e-mail

2. Suivre la livraison

Un message en file traverse un cycle de statuts avant d’atteindre le destinataire :

queued → sending → sent → delivered   (ou failed / undelivered)

Vous avez deux moyens de le suivre : Interrogez le message par id :

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

Abonnez-vous aux webhooks (recommandé — pas de polling). Un événement est émis à chaque transition de statut, chacun portant l’id du message et le nouveau status :

message.sent — accepté par l’opérateur
message.delivered — livraison confirmée au terminal
message.failed — échec terminal (le status du payload distingue failed, undelivered, expired et submitted_no_receipt ; error_code / error_message portent la raison du fournisseur lorsqu’elle est présente)

Enregistrez un endpoint webhook une seule fois, puis laissez les événements arriver :

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.sent", "message.delivered", "message.failed", "message.received"],
    "secret": "whsec_your_signing_secret"
  }'

Un événement de livraison ressemble à ceci :

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-07-20T12:00:00Z",
  "data": {
    "message_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "channel": "sms",
    "status": "delivered",
    "is_terminal": true,
    "timestamp": "2026-07-20T12:00:00Z"
  }
}

Vérifiez l’en-tête X-Orbit-Signature avant d’accepter une payload, et dédupliquez sur l’id de l’événement — la livraison est au moins une (at-least-once). Voir Sécurité des webhooks pour l’extrait de validation.

3. Recevoir des messages entrants

Lorsque quelqu’un répond à votre numéro (ou vous écrivent en premier), Orbit enregistre un message entrant et — si vous êtes abonné à message.received à l’étape précédente — le POST vers votre URL webhook :

{
  "id": "evt_def456",
  "type": "message.received",
  "created_at": "2026-07-20T12:01:00Z",
  "data": {
    "message_id": "msg_inb_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "STATUS"
  }
}

Le message entrant est aussi requêtable — listez tout ce que vous avez reçu avec le filtre direction=inbound :

curl "https://api.orbit.devotel.io/api/v1/messages?direction=inbound&channel=sms" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Le routage entrant est automatique pour les numéros que vous possédez sur Orbit — une réponse à l’un de vos numéros expéditeurs est capturée et, avec un abonnement message.received, livrée à votre webhook. Aucun branchement d’URL entrant par numéro n’est nécessaire.

4. Répondre à un message entrant

Répondre n’est qu’un autre envoi, adressé en retour au from entrant. Échangez to et from et appelez POST /messages/sms une nouvelle fois :

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": "Order #1234 is out for delivery, arriving today by 5pm."
  }'

Les deux messages partagent une conversation, donc une fois le fil de discussion créé vous pouvez récupérer l’intégralité de l’échange avec le filtre conversation_id sur GET /messages.

Erreurs courantes

Toute erreur utilise la même forme — faites correspondre sur error.code (une constante en MAJUSCULES) et journalisez meta.request_id :

Code	HTTP	Signification	Solution
`INVALID_API_KEY`	401	Clé révoquée, mauvais environnement ou faute de frappe	Vérifiez Paramètres → Clés API
`INVALID_PHONE_NUMBER`	422	`to` n’est pas un E.164 valide ou pas joignable	Validez le numéro avant l’envoi
`NOT_SMS_CAPABLE`	422	L’expéditeur n’est pas compatible SMS (par ex. numéro sans frais sans 10DLC)	Enregistrez ou changez le numéro
`INSUFFICIENT_BALANCE`	402	Portefeuille en dessous du minimum du canal	Rechargez votre portefeuille
`RATE_LIMITED`	429	Trop d’envois	Respectez `details.retry_after` (secondes)
`VALIDATION_ERROR`	422	Forme de corps incorrecte	Lisez `details.issues` pour chaque champ

Liste complète : Codes d’erreur.

Prochaines étapes

Référence de l’API Messaging — chaque endpoint et champ de message
Cycle de vie du statut des messages — l’ensemble complet des statuts par canal
Aperçu des webhooks — relances, garanties de livraison et catalogue d’événements
Intégration de l’API — sandbox, idempotence, pagination et SDK pour chaque canal
Limites de débit — limites par canal et en-têtes de relance

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Envoyer et recevoir des messages

Envoyer et recevoir des messages

Prérequis

1. Envoyer un message

Autres canaux

2. Suivre la livraison

3. Recevoir des messages entrants

4. Répondre à un message entrant

Erreurs courantes

Prochaines étapes

​Envoyer et recevoir des messages

​Prérequis

​1. Envoyer un message

​Autres canaux

​2. Suivre la livraison

​3. Recevoir des messages entrants

​4. Répondre à un message entrant

​Erreurs courantes

​Prochaines étapes

Envoyer et recevoir des messages

Prérequis

1. Envoyer un message

Autres canaux

2. Suivre la livraison

3. Recevoir des messages entrants

4. Répondre à un message entrant

Erreurs courantes

Prochaines étapes