Une API qui ne vous surprend pas.
Une adresse, une clé, deux formes de réponse. Tout ce que fait la console, votre code le fait aussi.
curl "https://nodium.io/api/v1/conversations?limit=20" \ -H "Authorization: Bearer $NODIUM_KEY" -iX-RateLimit-Limit: 600X-RateLimit-Remaining: 599{ "data": { "items": [ { "id": "c81d…", "status": "open" } ], "nextCursor": "MjAyNi0wOS0yOFQw…", "hasMore": true }}Les bases
Ce qu’il faut savoir avant le premier appel.
Une adresse versionnée
Toutes les routes vivent sous /api/v1. Une version publiée ne change pas de forme.
https://nodium.io/api/v1Une clé par compte
La clé agit en son nom et ouvre toute l’API : sur votre propre entreprise, sur le client où elle est épinglée, ou sur celui que nomme l’en-tête Nodium-Tenant. Elle se crée dans la console ou par l’API.
Authorization: Bearer nod_…Une enveloppe
Une réponse réussie est rangée sous data ; un refus, sous error. Jamais les deux.
{ "data": … }Des erreurs stables
Testez le code, jamais le texte. Chaque refus porte l’identifiant de la requête.
{ "error": { "code", "requestId" } }Une pagination par curseur
Renvoyez nextCursor tant qu’il n’est pas nul. Les curseurs sont opaques.
?limit=100&cursor=…Aucun double envoi
Chaque envoi porte votre clé anti-doublon : rejoué après un délai dépassé, il part une fois.
"idempotencyKey": "order-1042"
Les webhooks
Abonnez une adresse https à des événements. Nodium signe chaque appel et reprend les échecs.
- Répondez 2xx en moins de 10 secondes, travaillez ensuite.
- Six essais : après 1 min, 5 min, 30 min, 2 h et 12 h.
- Dans l’ordre de chaque conversation ; ignorez un doublon grâce à l’identifiant d’événement.
- Journal, relivraison, appel de test, changement de secret et pause, par l’API.
message.receivedmessage.importedmessage.echoedmessage.editedmessage.revokedmessage.sentmessage.deliveredmessage.readmessage.failedconversation.openedcontact.opted_incontact.opted_outtemplate.status_changedchannel.connectedchannel.connect_failedchannel.health_changedhistory.progress
import crypto from 'node:crypto'// X-Nodium-Signature: t=<seconds>,v1=<hex>[,v1=<hex>]export function verifyNodium(rawBody, header, secret) { const parts = header.split(',') const t = parts.find(p => p.startsWith('t='))?.slice(2) const sigs = parts.filter(p => p.startsWith('v1=')).map(p => p.slice(3)) if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false const expected = crypto.createHmac('sha256', secret) .update(`${t}.${rawBody}`).digest('hex') return sigs.some(s => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)))}Une clé pour tous vos clients
Un client par client final, piloté avec une seule clé.
- Une clé agit sur tous les clients de votre compte ; l’en-tête Nodium-Tenant désigne lequel.
- Votre identifiant client suffit pour désigner un client : rejouer la création ne fait pas de doublon.
- Un lien de branchement hébergé, à usage unique, ramène votre client chez vous une fois son numéro branché.
- Un webhook sur votre propre entreprise vous prévient pour tous les clients, et à chaque numéro branché.
# One account key adds and drives every clientcurl https://nodium.io/api/v1/tenants \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Optique Martin", "externalId": "cust_1042" }'# Then act for that client with the Nodium-Tenant headercurl https://nodium.io/api/v1/conversations \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Nodium-Tenant: cust_1042"Les limites
Chaque réponse dit ce qu’il reste : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
600 / min
Appels par client
Au-delà, 429 et un en-tête Retry-After en secondes.
600 / min
Réponses par minute
Sur l’envoi libre (texte et fichiers), par clé et par client. Pour du volume, mettez vos envois en file.
6
Essais par webhook
Puis la livraison est marquée en échec ; elle se relivre à la demande.
Pour vos outils et vos agents
Tout est tiré du code, jamais recopié à la main.
OpenAPI 3.1
La description complète, pour engendrer un client ou importer dans votre outil d’essai.
openapi.jsonllms.txt
Chaque route publiée, en un fichier, pour un modèle de langage.
llms.txtAGENTS.md
Une compétence d'agent : les routes, la signature et les pièges, pour votre assistant de code.
AGENTS.mdLa page de statut
L'état de l'API, lisible par une machine.
status.json
Votre première clé, dans cinq minutes.
Créez un compte gratuit, puis une clé dans le portail des développeurs.