API docs | maggio

Getting started

The base URL is https://api.maggio.ai/v1. Every request needs an Authorization: Bearer <token> header. Responses are JSON, and errors share one shape with a machine-readable code.

curl https://api.maggio.ai/v1/conversations?channel=instagram&status=open \
  -H "Authorization: Bearer $MAGGIO_TOKEN"

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 12 seconds."
  }
}

Rate limits

Standard plans allow 120 requests per minute per token, burstable to 300. Limits come back on every response in the X-RateLimit-* headers.

Versioning

The version is in the path. Breaking changes ship as a new version, and the previous version stays supported for twelve months.

Core endpoints

Endpoint	What it does
`GET /conversations`	List and filter conversations by channel, status, assignee or date.
`GET /conversations/:id/messages`	Full message history for a thread, paginated.
`POST /messages`	Send an outbound message on any connected channel.
`GET /contacts`	Search contacts, read attributes, tags and consent state.
`POST /flows/:id/trigger`	Start a workflow for a contact with your own payload.
`POST /webhooks`	Subscribe an endpoint to conversation, message and outcome events.

Send a message on any channel with one call:

curl -X POST https://api.maggio.ai/v1/messages \
  -H "Authorization: Bearer $MAGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ct_8f2a91",
    "channel": "whatsapp",
    "text": "Your order has shipped. Tracking: 1Z999AA10123456784"
  }'

Webhooks

Events are delivered as POST requests with an HMAC signature in the X-Maggio-Signature header. Verify it against your signing secret before trusting the payload.

import crypto from "node:crypto";

function isValid(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Delivery is retried with exponential backoff for 24 hours. Return a 2xx quickly and do the work asynchronously.

Common questions

Is there a sandbox?

Yes. Sandbox tokens hit the same endpoints against isolated test data.

Are there official SDKs?

The API is plain REST and works with any HTTP client. Thin helper libraries are on the roadmap.

A REST API for everything the inbox does.