Bulk SMS

Envoyez des SMS à plusieurs destinataires en un seul appel API.

L'authentification et l'URL de base sont documentées dans la Référence API.

Vue d'ensemble

L'API Bulk SMS permet d'envoyer des messages à plusieurs destinataires efficacement. Chaque destinataire peut recevoir un message personnalisé.

Envoyer des messages en masse

POST /api/v2/bulk/send

Envoyer des SMS à plusieurs destinataires en une seule requête.

Corps de la requête

Paramètre	Type	Obligatoire	Description
`recipients`	array	Oui	Tableau d'objets destinataires (max 50 000)
`recipients[].phone`	string	Oui	Numéro au format international
`recipients[].message`	string	Oui	Texte du message pour ce destinataire

Exemple de requête

{
  "recipients": [
    {
      "phone": "+22238089336",
      "message": "Bonjour Jean, votre commande est prête !"
    },
    {
      "phone": "+22238089337",
      "message": "Bonjour Sarah, votre commande est prête !"
    }
  ]
}

Réponse de succès (202 Accepted)

{
  "success": true,
  "message": "Bulk batch created successfully",
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "totalValid": 2,
  "totalInvalid": 0,
  "estimatedCost": 0.04,
  "status": "processing"
}

Réponses d'erreur

400 Bad Request — Erreur de validation

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["recipients"],
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

402 Payment Required — Solde insuffisant

{
  "success": false,
  "message": "Insufficient balance",
  "details": {
    "requiredAmount": 0.04,
    "validRecipients": 2,
    "invalidRecipients": 0
  }
}

400 Bad Request — Aucun destinataire valide

{
  "success": false,
  "message": "No valid recipients found",
  "invalidRecipients": [
    {
      "phone": "invalid",
      "reason": "Invalid phone number format"
    }
  ]
}

Statut d'un lot

GET /api/v2/bulk/status/

Récupérer le statut d'un envoi en masse.

Paramètres URL

Paramètre	Type	Obligatoire	Description
`batchId`	string	Oui	ID du lot retourné par la requête d'envoi

Exemple de réponse

{
  "success": true,
  "batch": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "totalMessages": 100,
    "validMessages": 98,
    "invalidCount": 2,
    "successfulCount": 45,
    "failedCount": 5,
    "totalCost": 1.96,
    "progress": 51,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:31:30.000Z",
    "messages": [
      {
        "messageId": "msg-123",
        "phone": "+22238089336",
        "status": "sent"
      },
      {
        "messageId": "msg-124",
        "phone": "+22238089337",
        "status": "failed",
        "error": "Invalid destination address"
      }
    ]
  }
}

Valeurs de statut

Statut	Description
`pending`	Lot créé, en attente de traitement
`processing`	Messages en cours de mise en file et d'envoi
`completed`	Tous les messages envoyés avec succès
`partial`	Certains messages réussis, d'autres échoués
`failed`	Tous les messages ont échoué

Statuts des messages

Statut	Description
`pending`	Message en attente de traitement
`queued`	Message en file d'attente
`sent`	Message envoyé avec succès
`failed`	Échec de l'envoi

Limites de débit

Maximum 50 000 destinataires par lot
Les limites de débit par seconde de l'API standard ne s'appliquent pas aux endpoints bulk (voir Référence API)
Les messages sont mis en file et traités de façon asynchrone

Format des numéros

Voir la Référence API (SMS / Mauritanie) pour les formats de numéros acceptés.

Facturation

Le coût est calculé par message selon la longueur et l'encodage
Les fonds sont débités à la création du lot
Les messages échoués sont remboursés automatiquement
Les messages longs (multi-parties) sont facturés par segment SMS

Exemples de code

JavaScript/Node.js

const response = await fetch('https://sms.chinqit.com/api/v2/bulk/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    recipients: [
      { phone: '+22238089336', message: 'Bonjour !' },
      { phone: '+22238089337', message: 'Salut !' }
    ]
  })
});

const result = await response.json();
console.log(result.batchId);

Python

import requests

response = requests.post(
    'https://sms.chinqit.com/api/v2/bulk/send',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
    },
    json={
        'recipients': [
            {'phone': '+22238089336', 'message': 'Bonjour !'},
            {'phone': '+22238089337', 'message': 'Salut !'}
        ]
    }
)

result = response.json()
print(result['batchId'])

PHP

<?php
$ch = curl_init('https://sms.chinqit.com/api/v2/bulk/send');

$data = [
    'recipients' => [
        ['phone' => '+22238089336', 'message' => 'Bonjour !'],
        ['phone' => '+22238089337', 'message' => 'Salut !']
    ]
];

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key_here'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['batchId'];

cURL

curl -X POST https://sms.chinqit.com/api/v2/bulk/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "recipients": [
      {"phone": "+22238089336", "message": "Bonjour !"},
      {"phone": "+22238089337", "message": "Salut !"}
    ]
  }'

Interrogation du statut

Après l'envoi d'un lot, interrogez le endpoint de statut toutes les 2 à 5 secondes jusqu'à la fin du traitement :

const checkStatus = async (batchId) => {
  const response = await fetch(`https://sms.chinqit.com/api/v2/bulk/status/${batchId}`, {
    headers: { 'X-API-Key': 'your_api_key_here' }
  });
  
  const result = await response.json();
  
  if (['completed', 'failed', 'partial'].includes(result.batch.status)) {
    console.log('Lot terminé !', result.batch);
    return result.batch;
  }
  
  console.log(`Progression : ${result.batch.progress}%`);
  setTimeout(() => checkStatus(batchId), 2000);
};

Codes d'erreur

Code	Description
`NO_CREDIT`	Solde insuffisant
`BILLING_FAILED`	Échec de la transaction de facturation
`INVALID_DESTINATION`	Format de numéro invalide
`QUEUE_ERROR`	Échec de la mise en file du message

Bonnes pratiques

Validez les numéros avant l'envoi pour éviter des coûts inutiles
Interrogez le statut pour suivre la livraison
Gérez les échecs partiels — certains messages peuvent réussir et d'autres échouer
Taille des lots — Gardez les lots sous 10 000 pour de meilleures performances
Nouvelles tentatives — Les messages échoués sont automatiquement réessayés jusqu'à 4 fois

Bulk SMS

On this page