Retour aux docs APIWhatsApp Business API

API WhatsApp Coussema

Envoyez des templates WhatsApp approuvés, répondez dans la fenêtre de service, et lisez vos templates, conversations, messages, campagnes, numéros et soldes via des clés API Coussema à scopes explicites.

Garde-fous V1

Les accès WhatsApp sont activés par organisation; une clé API seule ne crée pas un sender WhatsApp.
Chaque clé doit recevoir explicitement `whatsapp:read` et/ou `whatsapp:send`; les anciennes clés n’obtiennent aucun accès implicite.
La création de campagnes marketing reste hors de cette première surface API développeur.
`provider.messageId` reste masqué dans les réponses publiques; suivez le message via l’ID Coussema, les webhooks et l’historique.
Les réponses texte directes ne sont autorisées que dans la fenêtre de service client de 24 heures.
Envoi template

Requête minimale

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

Automatisation métier

Une école utilise la même API pour envoyer un avis approuvé aux parents, puis suit chaque DLR avec l’ID Coussema.

Agent conversationnel externe

Un runtime d’agent utilise une clé WhatsApp standard pour lire la conversation et répondre dans la fenêtre de service. Il ne reçoit aucun privilège caché.

Endpoints disponibles

Les lectures sont paginées par curseur et filtrables par statut, catégorie, template, destinataire et dates selon la ressource.

POST/v1/whatsapp/messagesEnvoi template utility/authentication approuvé ou réponse texte dans une fenêtre de service ouverte.
GET/v1/whatsapp/templatesTemplates WhatsApp paginés avec filtres status, category, template et dates.
GET/v1/whatsapp/conversationsConversations paginées avec status, destinataire et fenêtre de service.
GET/v1/whatsapp/messagesHistorique message customer-safe sans ID provider ni erreur upstream brute.
GET/v1/whatsapp/messages/{messageId}Détail d’un message par son identifiant Coussema.
GET/v1/whatsapp/phone-numbersSanté des numéros: connexion, qualité, palier, credential et webhook.
GET/v1/whatsapp/campaigns/{campaignId}Statut et compteurs DLR agrégés d’une campagne WhatsApp.
GET/v1/whatsapp/walletSoldes WhatsApp disponibles, réservés et consommés.

JavaScript REST

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: '+243980395067',
    phoneNumberId: '11111111-1111-4111-8111-111111111111',
    template: {
      name: 'payment_notice',
      language: 'fr',
      category: 'utility',
      parameters: ['12345'],
    },
    clientReference: 'invoice-12345',
  }),
});

if (!response.ok) throw new Error('Envoi WhatsApp refusé');
const sent = await response.json();

const historyResponse = await fetch(
  'https://api.coussema.com/v1/whatsapp/messages?status=delivered&category=utility',
  { headers: { Authorization: `Bearer ${apiKey}` } },
});
if (!historyResponse.ok) throw new Error('Historique WhatsApp indisponible');
const messages = await historyResponse.json();

console.log(sent.messageId, messages.pageInfo.nextCursor);

Champs publics

Les objets retournés sont volontairement orientés client et audit métier.

  • Templates: nom, langue, catégorie, statut, dates de création et mise à jour.
  • Conversations: destinataire, statut, dates et fin de fenêtre de service.
  • Messages: direction, type, template, catégorie, statut, dates et `failureLabel` public.
  • Numéros: qualité, palier, état du credential et fraîcheur du dernier contrôle, sans token.
  • Campagnes et portefeuille: compteurs et soldes agrégés, sans preuve fournisseur interne.
  • Les IDs fournisseur, erreurs opérateur et payloads Meta restent côté Coussema.