API WhatsApp

curl -X POST https://api.coussema.com/v1/whatsapp/templates \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "invoice_ready",
    "language": "fr",
    "category": "utility",
    "title": "Votre facture",
    "message": "Bonjour {{1}}, votre facture {{2}} est disponible.",
    "examples": ["Mireille", "F-2026-114"],
    "footer": "Atlas Logistics",
    "buttons": [
      { "type": "website", "text": "Voir la facture", "url": "https://example.com/invoices" },
      { "type": "quick_reply", "text": "Merci" }
    ]
  }'

201 Created
{
  "template": {
    "id": "6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10",
    "name": "invoice_ready",
    "language": "fr",
    "category": "utility",
    "status": "pending",
    "rejectionReason": null,
    "createdAt": "2026-10-25T10:00:00.000Z",
    "updatedAt": "2026-10-25T10:00:00.000Z"
  }
}

# A promotion with an image at the top and a personalized link
curl -X POST https://api.coussema.com/v1/whatsapp/templates \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "weekend_offer",
    "language": "fr",
    "category": "marketing",
    "media": { "type": "image", "url": "https://example.com/images/collection.jpg" },
    "message": "Bonjour {{1}}, -20 % ce week-end sur la nouvelle collection.",
    "examples": ["Mireille"],
    "buttons": [
      { "type": "website", "text": "Voir l’offre", "url": "https://example.com/offers/{{1}}", "example": "red-dress" },
      { "type": "quick_reply", "text": "Plus de promotions" }
    ]
  }'

# Once approved, send it: the kept image goes with it, the link ends with each customer's value
curl -X POST https://api.coussema.com/v1/whatsapp/messages \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: weekend-offer-243810000000' \
  -d '{
    "type": "template",
    "to": "+243810000000",
    "phoneNumberId": "11111111-1111-4111-8111-111111111111",
    "template": {
      "name": "weekend_offer",
      "language": "fr",
      "category": "marketing",
      "parameters": ["Mireille"],
      "urlParameters": ["red-dress"]
    }
  }'

# A limited-time offer with a code to copy
curl -X POST https://api.coussema.com/v1/whatsapp/templates \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "flash_sale",
    "language": "fr",
    "category": "marketing",
    "media": { "type": "image", "url": "https://example.com/images/flash.jpg" },
    "offer": { "text": "Offre flash", "expires": true },
    "message": "Bonjour {{1}}, -20 % sur tout jusqu’à ce soir.",
    "examples": ["Mireille"],
    "buttons": [
      { "type": "copy_code", "example": "FLASH20" },
      { "type": "website", "text": "J’en profite", "url": "https://example.com/flash" }
    ]
  }'

# Its send gives the code and the end of the offer
#   "template": { "name": "flash_sale", "language": "fr", "category": "marketing",
#                 "parameters": ["Mireille"], "couponCode": "FLASH20",
#                 "offerExpiresAt": "2026-11-28T23:59:00+01:00" }

# A carousel: the message, then 2 to 10 cards of the same shape
curl -X POST https://api.coussema.com/v1/whatsapp/templates \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "new_collection",
    "language": "fr",
    "category": "marketing",
    "message": "La nouvelle collection est arrivée.",
    "cards": [
      { "media": { "type": "image", "url": "https://example.com/images/red.jpg" },
        "message": "Robe rouge, -20 %",
        "buttons": [{ "type": "website", "text": "Voir", "url": "https://example.com/red" }] },
      { "media": { "type": "image", "url": "https://example.com/images/blue.jpg" },
        "message": "Robe bleue, -20 %",
        "buttons": [{ "type": "website", "text": "Voir", "url": "https://example.com/blue" }] }
    ]
  }'

curl -X POST https://api.coussema.com/v1/whatsapp/templates \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "login_code",
    "language": "fr",
    "category": "authentication",
    "verificationCode": { "securityNotice": true, "expiresInMinutes": 10 }
  }'

# Read Meta's review again:
curl https://api.coussema.com/v1/whatsapp/templates/6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10 \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx'

curl -X POST https://api.coussema.com/v1/whatsapp/messages \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-12345-wa' \
  -d '{
    "type": "template",
    "to": "+243810000000",
    "phoneNumberId": "11111111-1111-4111-8111-111111111111",
    "template": {
      "name": "payment_notice",
      "language": "fr",
      "category": "utility",
      "parameters": ["12345"]
    },
    "clientReference": "invoice-12345"
  }'

202 Accepted
{
  "success": true,
  "queued": true,
  "status": "accepted",
  "messageId": "a2f7e5cb-bbe9-4d7d-bd17-80d1d7a5e5af",
  "provider": { "code": "whatsapp", "messageId": null, "httpStatus": 202 }
}

const apiKey = process.env.COUSSEMA_API_KEY ?? '';
const response = await fetch('https://api.coussema.com/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'invoice-12345-wa',
  },
  body: JSON.stringify({
    type: 'template',
    to: '+243810000000',
    phoneNumberId: '11111111-1111-4111-8111-111111111111',
    template: { name: 'payment_notice', language: 'fr', category: 'utility', parameters: ['12345'] },
    clientReference: 'invoice-12345',
  }),
});

const body = await response.json();
if (response.status === 402) throw new Error(body.error); // abonnement WhatsApp inactif
if (!response.ok) throw new Error(`WhatsApp request failed: ${response.status}`);
console.log(body.messageId);

# Inside the 24-hour window of a conversation your customer opened:
# the same route, the same Idempotency-Key rule, a 202 with the Coussema message id.

# A document by its public https link (image and video: the same, with a caption)
curl -X POST https://api.coussema.com/v1/whatsapp/messages \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: facture-2231-pdf' \
  -d '{
    "type": "document",
    "to": "+243810000000",
    "phoneNumberId": "11111111-1111-4111-8111-111111111111",
    "conversationId": "22222222-2222-4222-8222-222222222222",
    "media": {
      "url": "https://example.com/factures/F-2231.pdf",
      "filename": "Facture-F-2231.pdf",
      "caption": "Votre facture"
    }
  }'

# Up to 3 reply buttons
curl -X POST https://api.coussema.com/v1/whatsapp/messages \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: rdv-5512-confirm' \
  -d '{
    "type": "interactive",
    "to": "+243810000000",
    "phoneNumberId": "11111111-1111-4111-8111-111111111111",
    "conversationId": "22222222-2222-4222-8222-222222222222",
    "interactive": {
      "type": "button",
      "bodyText": "Confirmez-vous le rendez-vous de demain à 10 h ?",
      "buttons": [{ "id": "confirm", "title": "Je confirme" }, { "id": "move", "title": "Changer" }]
    }
  }'

# A list (up to 10 rows)
#   "interactive": { "type": "list", "bodyText": "Choisissez un créneau.", "buttonText": "Créneaux",
#                    "sections": [{ "title": "Lundi", "rows": [{ "id": "mon-9", "title": "9 h", "description": "Gombe" }] }] }

# A place
#   "type": "location",
#   "location": { "latitude": -4.3217, "longitude": 15.3125, "name": "Agence Gombe", "address": "Boulevard du 30 Juin" }

const apiKey = process.env.COUSSEMA_API_KEY ?? '';
// conversationId: from GET /v1/whatsapp/conversations or the whatsapp.message.received webhook.
async function reply(message, idempotencyKey) {
  const response = await fetch('https://api.coussema.com/v1/whatsapp/messages', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      to: '+243810000000',
      phoneNumberId: '11111111-1111-4111-8111-111111111111',
      conversationId: '22222222-2222-4222-8222-222222222222',
      ...message,
    }),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${body.code ?? ''}`); // whatsapp_service_window_closed : envoyez un modèle
  return body.messageId;
}

await reply({ type: 'image', media: { url: 'https://example.com/colis.jpg', caption: 'Votre colis est parti' } }, 'colis-4471-photo');
await reply({ type: 'location', location: { latitude: -4.3217, longitude: 15.3125, name: 'Agence Gombe' } }, 'colis-4471-agence');

curl -X POST https://api.coussema.com/v1/whatsapp/campaigns \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: rappels-2026-10-29' \
  -d '{
    "name": "Rappel fin d’abonnement",
    "templateId": "6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10",
    "recipients": [
      { "phone": "+243810000000", "values": ["Mireille", "31/10/2026"] },
      { "phone": "+243970000000", "values": ["Jean", "02/11/2026"] }
    ],
    "defaults": ["cher client", "bientôt"],
    "smsRelay": {
      "senderId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "smsTemplateId": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "fieldValues": { "Bouquet": "Famille" }
    }
  }'

202 Accepted
{
  "dryRun": false,
  "campaign": {
    "id": "d4c3b2a1-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
    "name": "Rappel fin d’abonnement",
    "status": "scheduled",
    "scheduledAt": "2026-10-29T10:00:00.000Z",
    "createdAt": "2026-10-29T10:00:00.000Z"
  },
  "recipients": { "requested": 2, "accepted": 2, "excluded": 0, "excludedRecipients": [] },
  "smsRelay": { "senderName": "MONENTREPRISE", "smsTemplateName": "rappel_sms", "maxSmsUnits": null }
}

# Follow it (the counts of the SMS relay included):
curl https://api.coussema.com/v1/whatsapp/campaigns/d4c3b2a1-0f9e-4d8c-b7a6-5f4e3d2c1b0a \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx'

const apiKey = process.env.COUSSEMA_API_KEY ?? '';
const campaign = {
  name: 'Rappel fin d’abonnement',
  templateId: '6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10',
  recipients: subscribers.map((s) => ({ phone: s.phone, values: [s.firstName, s.endDate] })),
  defaults: ['cher client', 'bientôt'],
  smsRelay: { senderId: '9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f' },
};
const call = (body, idempotencyKey) => fetch('https://api.coussema.com/v1/whatsapp/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
  },
  body: JSON.stringify(body),
});

// 1. Check: counts and the most SMS the relay may send, nothing created.
const check = await (await call({ ...campaign, dryRun: true })).json();
console.log(check.recipients.accepted, check.smsRelay?.maxSmsUnits);

// 2. Create: the same key never creates a second campaign.
const response = await call(campaign, 'rappels-2026-10-29');
if (!response.ok) throw new Error(`WhatsApp campaign failed: ${response.status}`);
const { campaign: created } = await response.json();
console.log(created.id);

curl -X POST https://api.coussema.com/v1/whatsapp/messages \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: login-482913' \
  -d '{
    "type": "template",
    "to": "+243810000000",
    "phoneNumberId": "11111111-1111-4111-8111-111111111111",
    "template": { "name": "code_connexion", "language": "fr", "category": "authentication", "parameters": ["482913"] },
    "smsFallback": { "senderId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f" }
  }'

# 202 Accepted: the WhatsApp message. Its SMS leaves only if Meta reports the number is not on WhatsApp:
curl https://api.coussema.com/v1/whatsapp/messages/8f0aa7ed-1b2c-4d3e-8f4a-5b6c7d8e9f01 \
  -H 'Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx'
# "relay": { "requested": true, "status": "queued", "reason": null,
#            "sms": { "messageId": "2fc1be26-…", "status": "DELIVERED" } }

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: login-482913-sms' \
  -d '{
    "to": "243810000000",
    "message": "Votre code de vérification est 482913.",
    "senderId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "whatsappFirst": {
      "phoneNumberId": "11111111-1111-4111-8111-111111111111",
      "templateId": "6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10",
      "fieldValues": { "Code": "482913" }
    }
  }'

# 202 Accepted
{
  "success": true, "queued": true, "status": "accepted", "channel": "whatsapp_first", "count": 1,
  "remainingQuota": 4210,
  "whatsapp": { "messageId": "8f0aa7ed-1b2c-4d3e-8f4a-5b6c7d8e9f01" },
  "sms": { "messageId": null, "billableUnits": 1 },
  "clientReference": null,
  "provider": { "code": "coussema", "messageId": null, "httpStatus": 202 }
}

// On your server (Node 18+): one login code, WhatsApp first, SMS if the number is not on WhatsApp.
const apiKey = process.env.COUSSEMA_API_KEY;
const send = (path, body, idempotencyKey) => fetch(`https://api.coussema.com${path}`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify(body),
});

const code = '482913';
const response = await send('/v1/sms/send', {
  to: '243810000000',
  message: `Votre code de vérification est ${code}.`,
  senderId: '9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f',
  whatsappFirst: {
    phoneNumberId: '11111111-1111-4111-8111-111111111111',
    templateId: '6b1f3c2e-8a54-4d1e-9f0a-2c7d5e4b3a10',
    fieldValues: { Code: code },
  },
}, `login-${code}`); // the same key never sends twice

const body = await response.json();
if (!response.ok) throw new Error(body.error);
// Later (or on the whatsapp.message.* and message.* webhooks): where did the code arrive?
const status = await fetch(`https://api.coussema.com/v1/whatsapp/messages/${body.whatsapp.messageId}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
console.log(status.message.status, status.message.relay.status, status.message.relay.sms?.status);