API Documentation · MA Utility

Introduction

The MA Utility REST API lets you integrate the platform with your own tools: retrieve and create conversations and contacts, trigger message sends, and receive real-time events via webhooks.

All responses are in JSON format. The examples below are illustrative, refer to the interactive reference for the exact, up-to-date list of endpoints and fields.

Authentication

Every request must be authenticated with an API key. Generate one from Settings → API Keys in your dashboard. The key is shown only once at creation, store it somewhere safe.

Pass it in the Authorization header:

# Header to include in every request
Authorization: Bearer YOUR_API_KEY

Each key carries scopes (read, write) that you define at creation to restrict access.

Base URL

All public API calls originate from:

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

Requests must be made over HTTPS. HTTP calls are rejected.

Rate limits

Calls are subject to a per-API-key rate limit, calculated over a sliding window. The cap is configurable on each key to suit your needs.

When the limit is reached, the API responds with status 429 Too Many Requests. Space out your calls and retry after the indicated delay.

Request example

List the latest conversations:

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

Response (excerpt):

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

Webhooks

Receive real-time events (new message, status change, new conversation) at the URL of your choice. Each delivery is signed with HMAC-SHA256: verify the signature header against your secret to ensure authenticity.

On failure, webhooks are automatically retried with an increasing delay.

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

Interactive reference

The complete list of endpoints, parameters, and schemas is available in the interactive reference (Swagger), where you can test each call directly from your browser.

Open the interactive reference

The MA Utility API.