NimbaSMS

Capabilities

Gotchas

• ⚠Sans 'groups', le contact est ajouté à la liste de contacts par défaut du compte. Spécifier un groupe inexistant retourne une erreur 400 — utiliser list_groups pour récupérer les noms valides.
• ⚠Le champ 'numero' doit inclure l'indicatif pays sans le '+' (ex: 224XXXXXXXXX), contrairement à send_verification qui attend le format E.164 avec '+'. Un format incorrect retourne une erreur 400.
• ⚠Créer un contact avec un numéro déjà existant peut retourner une erreur de doublon — vérifier avec list_contacts avant d'insérer en masse.
• ⚠Le champ 'balance' est DEPRECATED — utiliser 'sms_balance' pour le solde SMS. Les deux sont retournés mais 'balance' sera supprimé dans une future version.
• ⚠sms_balance est en nombre de SMS (unités), pas en GNF. Un solde de 100 signifie 100 SMS disponibles.
• ⚠Vérifier le solde avant tout envoi groupé — un solde insuffisant retourne une erreur 400 avec le champ 'solde' dans la réponse d'erreur de send_message.
• ⚠Le champ d'identifiant dans la réponse est 'messageid' (pas 'id'). Utiliser le messageid retourné par send_message.
• ⚠sent_at est un Unix timestamp en secondes (integer), pas une date ISO 8601. Convertir avec new Date(sent_at * 1000) en JavaScript.
• ⚠Le statut global ('status') peut être 'sent' alors que certains destinataires dans 'numbers' ont statut 'failure' ou 'not_available'. Inspecter 'numbers' pour le statut par destinataire.
• ⚠Le statut 'received' dans 'numbers' signifie livré (delivery receipt reçu de l'opérateur). 'sent' signifie envoyé à l'opérateur mais non encore confirmé livré.
• ⚠La réponse est paginée. Utiliser 'limit' et 'offset' pour naviguer entre les pages — le champ 'next' contient l'URL complète de la page suivante.
• ⚠Le SDK NimbaSMS strip les champs 'count', 'next', 'previous' de la réponse et ne retourne que 'results'. En appelant l'API directement, la réponse brute contient tous ces champs.
• ⚠Les noms de groupes retournés ici sont ceux à passer dans create_contact({ groups: [...] }). La casse est significative — copier les valeurs exactes retournées par cet endpoint.
• ⚠Les groupes ne peuvent pas être créés via l'API — ils doivent être créés depuis le dashboard NimbaSMS.
• ⚠Le SDK NimbaSMS strip les champs 'count', 'next', 'previous' de la réponse paginée et ne retourne que 'results'. En appelant l'API directement, la réponse brute contient tous ces champs.
• ⚠La réponse est paginée — le champ 'count' indique le total mais 'results' ne contient que la page courante. Utiliser 'next' pour itérer sur toutes les pages.
• ⚠Les filtres sent_at__lte et sent_at__gte peuvent être combinés pour définir une plage de dates. Les dates doivent être en format ISO 8601.
• ⚠Chaque item retourné dans 'results' inclut un champ message_cost indiquant le nombre de SMS consommés pour ce message (longueur × destinataires). Utiliser ce champ pour les rapports de consommation.
• ⚠Seuls les sender names avec statut 'accepted' peuvent être utilisés dans send_message et send_verification. Les statuts valides sont 'pending' (en validation), 'refused' (refusé) et 'accepted' (utilisable) — pas 'active'.
• ⚠Les sender names sont approuvés manuellement par NimbaSMS — ils ne peuvent pas être créés via l'API. Les créer depuis le dashboard, puis les récupérer ici.
• ⚠La valeur retournée dans 'name' est à utiliser telle quelle dans send_message({ sender_name: '...' }) — elle est case-sensitive.
• ⚠Le SDK NimbaSMS strip les champs 'count', 'next', 'previous' de la réponse paginée et ne retourne que 'results'. En appelant l'API directement, la réponse brute contient tous ces champs.
• ⚠sender_name est case-sensitive et doit correspondre exactement à un nom avec statut 'accepted' retourné par list_sendernames. 'active' n'est pas un statut valide — c'est 'accepted'.
• ⚠Le champ 'to' accepte trois formats interchangeables : local (623XXXXXX), avec indicatif pays (224623XXXXXX), ou E.164 (+224623XXXXXX). Maximum 30 destinataires par requête.
• ⚠Le message est limité à 665 caractères (5 SMS). Au-delà de 160 caractères, message_cost augmente proportionnellement. Utiliser le simulateur pour estimer avant l'envoi.
• ⚠La réponse HTTP est 201 Created (pas 200). La réponse ne contient que messageid, message_cost et url — les détails complets (statut par destinataire) sont dans GET /v1/messages/{messageid}.
• ⚠Les erreurs 400 retournent des champs avec des valeurs string (pas tableau) : sender_name, solde, to, detail. Vérifier le solde avec get_balance avant un envoi groupé.
• ⚠sender_name est OBLIGATOIRE (pas optionnel) et case-sensitive. Utiliser list_sendernames pour récupérer les noms avec statut 'accepted'.
• ⚠Le placeholder <1234> dans 'message' est obligatoire — sans lui, le code ne sera pas inclus dans le SMS. Le texte autour du placeholder est libre.
• ⚠Le champ d'identifiant dans la réponse est 'verificationid' (pas 'id'). Stocker ce champ côté serveur pour appeler verify_code.
• ⚠expiry_time et attempts sont envoyés à null quand non fournis — l'API applique ses propres défauts internes.
• ⚠Le code généré est retourné dans la réponse API (champ 'code') — ne jamais l'exposer côté client, l'utiliser uniquement pour les tests.
• ⚠Pour WhatsApp (channel: 'whatsapp'), le contenu du message est remplacé selon un template NimbaSMS — le champ 'message' est ignoré.
• ⚠Le champ 'code' est un integer (pas une string). Envoyer le code saisi par l'utilisateur comme nombre entier dans le body JSON.
• ⚠Le champ 'id' dans l'URL correspond au champ 'verificationid' (pas 'id') retourné par send_verification.
• ⚠Le statut 'too_many_attemps' (avec une seule lettre 't' à 'attempts') est un typo dans l'API NimbaSMS — prévoir cette valeur exacte dans le code.
• ⚠Chaque appel erroné décrémente le compteur de tentatives. Une fois épuisé (status: 'too_many_attemps'), la vérification expire — créer une nouvelle via send_verification.
• ⚠Ne jamais appeler cet endpoint côté client — appeler uniquement côté serveur avec le code saisi par l'utilisateur. Un status 'approved' doit immédiatement marquer le numéro comme vérifié en base de données.
• ⚠Votre serveur doit retourner HTTP 200 immédiatement après réception — NimbaSMS renvoie la notification jusqu'à 3 fois si la réponse n'est pas 200. Tout traitement lourd doit être asynchrone.
• ⚠Le webhook est configuré dans le dashboard NimbaSMS (API KEYS > Webhooks), pas via l'API. Un seul URL webhook par compte.
• ⚠Les notifications ne sont disponibles que pour les envois effectués via l'API (metadata.message_type: 'API').
• ⚠NimbaSMS ne signe pas les requêtes entrantes — valider que messageid existe bien dans votre système avant de traiter la notification pour éviter les requêtes frauduleuses.
• ⚠Le webhook reçoit un événement par destinataire (champ 'contact') — un message envoyé à 10 destinataires peut déclencher jusqu'à 10 appels webhook distincts.