Retour aux docs APIJavaScript SDK quickstart

Intégrer le premier SMS en JavaScript

Ce guide montre comment utiliser le premier SDK JavaScript officiel pour envoyer un SMS, lire la vraie réponse de l’API et préparer la validation des webhooks.

Pré-requis d’exécution

Le serveur qui appelle l’API doit conserver la clé API côté backend. Ne l’exposez jamais dans un bundle navigateur.

Installer le package officiel `@coussema/sdk-js` dans votre backend Node.js.
Créer une organisation et récupérer une clé API depuis le dashboard.
Conserver la clé API côté serveur uniquement. Le SDK n’est pas prévu pour le navigateur.
Ajouter `Idempotency-Key` sur chaque mutation critique.
Corréler les erreurs via `x-request-id` et les headers `X-RateLimit-*`.
Exemple SDK Node.js

client.sendSms(...)

Installation
npm install @coussema/sdk-js
import crypto from 'node:crypto';
import { CoussemaClient } from '@coussema/sdk-js';

const baseUrl = process.env.COUSSEMA_BASE_URL ?? 'https://api.coussema.com';
const apiKey = process.env.COUSSEMA_API_KEY;

if (!apiKey) {
  throw new Error('COUSSEMA_API_KEY is required.');
}

const client = new CoussemaClient({
  baseUrl,
  apiKey,
});

const response = await client.sendSms(
  {
    to: '243810000000',
    message: 'Votre code de verification est 482019.',
    senderName: 'Coussema',
    clientReference: 'welcome-001',
  },
  {
    idempotencyKey: crypto.randomUUID(),
    requestId: 'quickstart-send-001',
  }
);

console.log({
  requestId: response.requestId,
  remainingQuota: response.data.remainingQuota,
  providerMessageId: response.data.provider.messageId,
});
successtrue
count1
remainingQuota999
provider.codecoussema
provider.messageIdprovider-msg-123
provider.httpStatus200

COUSSEMA_API_KEY

Clé API générée depuis le dashboard.

ck_live_xxx

COUSSEMA_BASE_URL

Hôte API de production. Le SDK ajoute `/v1` si nécessaire.

https://api.coussema.com

COUSSEMA_WEBHOOK_SECRET

Secret partagé pour vérifier les callbacks webhook.

csm_whsec_...

Préparer les webhooks

Quand l’envoi est critique, créez un endpoint webhook et vérifiez les callbacks signés. Le helper du SDK évite de recopier la logique HMAC à la main.

Créer un endpoint

POST /v1/webhooks
Authorization: Bearer ck_live_xxx
Content-Type: application/json

{
  "url": "https://example.com/webhooks/coussema",
  "subscribed_events": ["message.delivered", "message.failed"]
}

200 OK
{
  "success": true,
  "webhookEndpoint": {
    "id": "7d5f1e88-6fd8-4ca7-a1a5-3b338f5f0f50",
    "url": "https://example.com/webhooks/coussema",
    "subscribed_events": ["message.delivered", "message.failed"],
    "status": "active"
  },
  "signingSecret": "csm_whsec_..."
}

Vérifier la signature

import { assertWebhookSignature, extractCoussemaWebhookHeaders } from '@coussema/sdk-js';

function handleWebhook(rawBody, headers) {
  const webhookHeaders = extractCoussemaWebhookHeaders(headers);

  if (!webhookHeaders.timestamp || !webhookHeaders.signature) {
    throw new Error('Missing Coussema webhook headers.');
  }

  assertWebhookSignature({
    signingSecret: process.env.COUSSEMA_WEBHOOK_SECRET ?? '',
    timestamp: webhookHeaders.timestamp,
    signature: webhookHeaders.signature,
    payload: rawBody,
  });

  return JSON.parse(rawBody);
}
Codes d’erreurSDK JavaScript