L'API MA Utility.

Introduction

L'API REST de MA Utility vous permet d'intégrer la plateforme à vos propres outils : récupérer et créer des conversations et des contacts, déclencher des envois, et recevoir des événements en temps réel via des webhooks.

Toutes les réponses sont au format JSON. Les exemples ci-dessous sont indicatifs : reportez-vous à la référence interactive pour la liste exacte et à jour des endpoints et des champs.

Authentification

Chaque requête doit être authentifiée avec une clé API. Générez-la depuis Réglages → Clés API dans votre tableau de bord. La clé n'est affichée qu'une seule fois à la création : conservez-la en lieu sûr.

Transmettez-la dans l'en-tête Authorization :

# En-tête à inclure dans chaque requête
Authorization: Bearer VOTRE_CLE_API

Chaque clé porte des scopes (lecture, écriture) que vous définissez à la création pour limiter les accès.

URL de base

Tous les appels de l'API publique partent de :

https://api.mautility.com/api/v2/public

Les requêtes doivent être faites en HTTPS. Les appels en HTTP sont refusés.

Limites de débit

Les appels sont soumis à une limite de débit par clé API, calculée sur une fenêtre glissante. Le plafond est configurable sur chaque clé selon vos besoins.

Lorsque la limite est atteinte, l'API répond avec le statut 429 Too Many Requests. Espacez vos appels et réessayez après le délai indiqué.

Exemple de requête

Lister les dernières conversations :

curl https://api.mautility.com/api/v2/public/conversations \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse (extrait) :

{
  "data": [
    {
      "id": "conv_8f2a...",
      "channel": "whatsapp",
      "status": "open",
      "contact": { "name": "Sarah V." }
    }
  ],
  "meta": { "total": 128, "page": 1 }
}

Webhooks

Recevez les événements en temps réel (nouveau message, changement de statut, nouvelle conversation) sur l'URL de votre choix. Chaque envoi est signé en HMAC-SHA256 : vérifiez l'en-tête de signature avec votre secret pour garantir l'authenticité.

En cas d'échec, les webhooks sont réessayés automatiquement avec un délai croissant.

{
  "event": "message.created",
  "data": {
    "conversationId": "conv_8f2a...",
    "channel": "whatsapp",
    "body": "Bonjour, je voudrais un devis"
  }
}

Référence interactive

La liste complète des endpoints, des paramètres et des schémas est disponible dans la référence interactive (Swagger), où vous pouvez tester chaque appel directement depuis votre navigateur.

Ouvrir la référence interactive