Examples

curl and JavaScript for SMS, contacts, campaigns and webhooks. The public npm SDK is not available yet; use the REST API.

Send an SMS

A minimal idempotent mutation with explicit correlation. The 202 Accepted response confirms queueing.

bash

curl -X POST https://api.coussema.com/v1/sms/send \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7228b5c7-cb1d-43c0-8d68-2e9f68a5fba5' \
  -H 'X-Request-Id: send-001' \
  -d '{
    "to": "243810000000",
    "message": "Votre code est 482019",
    "senderName": "COUSSEMA",
    "clientReference": "order-482019"
  }'

http

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "success": true,
  "queued": true,
  "status": "accepted",
  "count": 1,
  "remainingQuota": 999,
  "message": {
    "id": "11111111-1111-4111-8111-111111111111",
    "clientReference": "order-482019"
  },
  "provider": {
    "code": "coussema",
    "messageId": null,
    "httpStatus": 202
  }
}

Create a contact

The contact is available in the dashboard and in campaigns.

bash

curl -X POST https://api.coussema.com/v1/contacts \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: contact-create-001' \
  -d '{
    "firstName": "Amina",
    "lastName": "Mbayo",
    "phoneNumber": "243810000000",
    "tags": ["clients-vip", "kinshasa"]
  }'

Schedule a campaign

The campaign is queued, then processed by the worker.

bash

curl -X POST https://api.coussema.com/v1/campaigns \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 26b7af09-c8b0-4b11-b0b5-99a3e2d82d90' \
  -d '{
    "name": "Lancement Avril",
    "content": "Notre offre est disponible jusqu a dimanche.",
    "senderName": "COUSSEMA",
    "scheduledAt": "2026-04-10T08:00:00.000Z",
    "recipients": [
      "243810000000",
      "243820000000"
    ]
  }'

Create an outgoing webhook

The signing secret is returned only once. Store it right away.

bash

curl -X POST https://api.coussema.com/v1/webhooks \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhooks/coussema",
    "subscribed_events": ["message.delivered", "message.failed"]
  }'

JavaScript REST

javascript

import crypto from 'node:crypto';

const baseUrl = process.env.COUSSEMA_BASE_URL ?? 'https://api.coussema.com';
const apiKey = process.env.COUSSEMA_API_KEY ?? '';
const smsResponse = await fetch(`${baseUrl}/v1/sms/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
    'X-Request-Id': 'docs-example-001',
  },
  body: JSON.stringify({
    to: '243810000000',
    message: 'Bonjour depuis Coussema.',
    senderName: 'COUSSEMA',
  }),
});

const sms = await smsResponse.json();
if (!smsResponse.ok) throw new Error(`SMS request failed: ${smsResponse.status}`);

const contactsResponse = await fetch(`${baseUrl}/v1/contacts?limit=20`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const contacts = await contactsResponse.json();

console.log({
  accepted: sms.queued === true && sms.status === 'accepted',
  messageId: sms.message.id,
  contacts: contacts.items.length,
});

← Errors JavaScript →