Retour à l'accueil

Documentation API

Guide complet pour intégrer l'API SMS Callisto

Démarrage rapide

Intégrez l'envoi de SMS en quelques minutes avec notre API REST simple et puissante.

1

Créer un compte

Inscrivez-vous gratuitement sur Callisto

2

Obtenir une clé API

Générez votre clé dans le tableau de bord

3

Envoyer un SMS

Faites votre premier appel API

Authentification

Toutes les requêtes API utilisent l'authentification Basic Auth avec vos identifiants API.

Vos identifiants

Paramètre Description
access_key Votre clé d'accès (utilisateur Basic Auth)
access_secret Votre clé secrète (mot de passe Basic Auth)

Format de l'en-tête

Authorization: Basic base64(access_key:access_secret)

Exemple avec cURL

curl https://api.callistosms.com/v1/sms/balance -u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET"

Important : Ne partagez jamais vos identifiants API et ne les exposez pas côté client.

URL de base

https://api.callistosms.com/v1

Envoyer un SMS

POST /sms/send

Paramètres

Paramètre Type Requis Description
to string | array Oui Numéro(s) de téléphone du/des destinataire(s) (format international)
message string Oui Contenu du message (max 1600 caractères)
sender_id string Non Identifiant de l'expéditeur (doit être approuvé)
scheduled_at datetime Non Date et heure d'envoi programmé (ISO 8601)

Exemple de requête

curl -X POST https://api.callistosms.com/v1/sms/send \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET" \
	-H "Content-Type: application/json" \
	-d '{
	"to": ["+22507XXXXXXXX"],
	"message": "Bonjour ! Votre code de vérification est 123456",
	"sender_id": "CALLISTO"
	}'

Réponse

{
	"success": true,
	"data": {
	"id": "msg_abc123xyz",
	"to": ["+22507XXXXXXXX"],
	"status": "queued",
	"credits_used": 1,
	"created_at": "2026-02-01T10:30:00Z"
	}
	}

Envoi en masse

POST /sms/bulk

Envoyez le même message à plusieurs destinataires en une seule requête.

Exemple de requête

curl -X POST https://api.callistosms.com/v1/sms/bulk \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET" \
	-H "Content-Type: application/json" \
	-d '{
	"recipients": [
	"+22507XXXXXXXX",
	"+22508XXXXXXXX",
	"+22509XXXXXXXX"
	],
	"message": "Promotion : -20% sur tous nos produits !",
	"sender_id": "CALLISTO"
	}'

OTP - Envoyer un code

POST /otp/send

Envoyez un code de vérification unique (OTP) à un destinataire. Le code est généré automatiquement et inséré dans votre message via la variable {'{code}'}.

Paramètres

Paramètre Type Requis Description
to string Oui Numéro de téléphone du destinataire (format international)
message string Oui Message contenant {'{code}'} (5-500 caractères)
sender string Oui Identifiant de l'expéditeur (doit être approuvé)
expired_in integer Oui Durée de validité en secondes (60 - 86400)
digit_size integer Non Nombre de caractères du code (4-10, défaut: 6)
type string Non Type de code: digit, alpha, alphanumeric (défaut: digit)

Exemple de requête

curl -X POST https://api.callistosms.com/v1/otp/send \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET" \
	-H "Content-Type: application/json" \
	-d '{
	"to": "+22507XXXXXXXX",
	"message": "Votre code de vérification Callisto est: {code}. Valide pendant 5 minutes.",
	"sender": "CALLISTO",
	"expired_in": 300,
	"digit_size": 6,
	"type": "digit"
	}'

Réponse

{
	"id": "550e8400-e29b-41d4-a716-446655440000",
	"recipient": "+22507XXXXXXXX",
	"expires_at": "2026-04-07T10:35:00Z",
	"expires_in": 300
	}

Note : Conservez l'id retourné pour vérifier le code ultérieurement.

OTP - Vérifier un code

POST /otp/verify

Vérifiez le code OTP saisi par l'utilisateur.

Paramètres

Paramètre Type Requis Description
otp_id string Oui ID de l'OTP retourné lors de l'envoi (UUID)
code string Oui Code saisi par l'utilisateur (4-10 caractères)

Exemple de requête

curl -X POST https://api.callistosms.com/v1/otp/verify \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET" \
	-H "Content-Type: application/json" \
	-d '{
	"otp_id": "550e8400-e29b-41d4-a716-446655440000",
	"code": "123456"
	}'

Réponse (succès)

{
	"id": "550e8400-e29b-41d4-a716-446655440000",
	"status": "verified",
	"verified": true,
	"verified_at": "2026-04-07T10:32:15Z"
	}

Réponse (échec)

{
	"message": "Invalid OTP code"
	}

Codes d'erreur OTP

Code Description
400 Code OTP invalide
404 OTP non trouvé
410 OTP expiré
429 Trop de tentatives de vérification

OTP - Statut

GET /otps/{{otp_id}}

Récupérez le statut actuel d'un OTP.

Exemple de requête

curl https://api.callistosms.com/v1/otps/{{otp_id}} \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET"

Réponse

{
	"id": "550e8400-e29b-41d4-a716-446655440000",
	"recipient": "+22507XXXXXXXX",
	"status": "pending",
	"created_at": "2026-04-07T10:30:00Z",
	"expires_at": "2026-04-07T10:35:00Z",
	"verified_at": null
	}

Statuts possibles

Statut Description
pending En attente de vérification
verified Code vérifié avec succès
expired Code expiré

OTP - Liste

GET /otps

Récupérez la liste des OTP avec pagination.

Paramètres de requête

Paramètre Type Défaut Description
page integer 1 Numéro de page
limit integer 20 Nombre d'éléments par page
started_at date -30 jours Date de début (YYYY-MM-DD)
ended_at date aujourd'hui Date de fin (YYYY-MM-DD)

Exemple de requête

curl "https://api.callistosms.com/v1/otps?page=1&limit=10&started_at=2026-04-01&ended_at=2026-04-07" \
	-u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET"

Réponse

{
	"items": [
	{
	"id": "3b5d654b-d603-44b6-8f9e-0f24b38eafd0",
	"client_id": "9d8e0eab-6c65-4794-ae22-637445a421bf",
	"api_client_id": "c11e9a92-27eb-430f-949f-40dea00d521d",
	"message_id": "ea01e0ba-02d2-471a-8e23-340b7d570b3e",
	"recipient": "+22507XXXXXXXX",
	"status": "expired",
	"expires_at": "2026-04-07 19:05:12",
	"verified_at": null,
	"attempts": 0,
	"created_at": "2026-04-07 18:06:52",
	"updated_at": "2026-04-07 18:06:52"
	},
	{
	"id": "d5f29dfc-03b5-41da-b371-2d7998896c72",
	"client_id": "9d8e0eab-6c65-4794-ae22-637445a421bf",
	"api_client_id": "c11e9a92-27eb-430f-949f-40dea00d521d",
	"message_id": "ac118655-fe08-4eba-afb1-e4a7a5399a95",
	"recipient": "+22508XXXXXXXX",
	"status": "verified",
	"expires_at": "2026-04-07 18:55:37",
	"verified_at": "2026-04-07 18:52:15",
	"attempts": 1,
	"created_at": "2026-04-07 17:57:17",
	"updated_at": "2026-04-07 18:52:15"
	}
	],
	"total": 25,
	"per_page": 20,
	"current_page": 1,
	"next": 2,
	"previous": 0,
	"total_pages": 2
	}

Vérifier le solde

GET /sms/balance

Exemple de requête

curl https://api.callistosms.com/v1/sms/balance -u "YOUR_ACCESS_KEY:YOUR_ACCESS_SECRET"

Réponse

{
	"success": true,
	"data": {
	"credits": 5000,
	"currency": "FCFA"
	}
	}

Statut d'un message

GET /sms/{{message_id}}

Statuts possibles

Statut Description
queued Le message est en file d'attente
sent Le message a été envoyé à l'opérateur
delivered Le message a été livré au destinataire
failed L'envoi du message a échoué

Codes d'erreur

Code Description
400 Requête invalide - vérifiez les paramètres
401 Non autorisé - clé API invalide ou manquante
402 Crédits insuffisants
404 Ressource non trouvée
429 Limite de requêtes dépassée
500 Erreur serveur interne

Limites de requêtes

Pour garantir la stabilité du service, les limites suivantes s'appliquent :

  • 100 requêtes/minute pour les endpoints d'envoi de SMS
  • 1000 requêtes/minute pour les endpoints de lecture
  • 10 000 SMS/jour par défaut (contactez-nous pour augmenter)

Les en-têtes de réponse incluent des informations sur vos limites actuelles : 

X-RateLimit-Limit: 100
	X-RateLimit-Remaining: 95
	X-RateLimit-Reset: 1706789400

Webhooks

Recevez des notifications en temps réel sur le statut de vos messages. Configurez votre URL de webhook dans le tableau de bord.

Exemple de payload

{
	"event": "message.delivered",
	"data": {
	"id": "msg_abc123xyz",
	"to": "+22507XXXXXXXX",
	"status": "delivered",
	"delivered_at": "2026-02-01T10:30:15Z"
	},
	"timestamp": "2026-02-01T10:30:16Z"
	}

Besoin d'aide ?

Notre équipe technique est disponible pour vous aider à intégrer l'API Callisto.

support@callistosms.com Créer un compte gratuit
>