API

The HTTP interface for M91. Raise alerts, read the human decision, and manage who gets reached. Base URL https://m91-api.msg91.com.

Introduction

There are two ways to reach a human. Pick by who you are alerting.

Links that start with https://m91.msg91.com/s/ must be changed. That was the API’s address until October 2026; it is now m91-api.msg91.com, and the old host no longer reaches the API. Replace the host; the token after /s/ stays the same.

A team: Send linkOne person: Platform API
Use it whenThe people are a fixed group in a channelYour product discovers its users at runtime
CredentialSend link token in the URL (/s/sk_…)API key, Authorization: Bearer m91sk_…
Comes fromA channel, in the M91 appThe M91 app: Settings → API keys
AlertsEveryone in that channelAny phone number you invited and who accepted
Can create channelsNoYes

One URL is the whole integration: no headers, no API key, no account at the other end. That is the send link, called over plain HTTPS or through the SDK.

A send link or API key can raise, read and close alerts. Neither can record a response. That is always a person, on their own phone.

Every response is { "success": true, "data": { … } }. Read your field from inside data, never from the top level.

Check a send link

GET/s/{token}

Confirms the link is live and names the channel it points to. It raises nothing and wakes nobody.

Authorization Send link token in the path. No headers needed.

Path parameters

token
stringrequired
The sk_… part of your send link. Use the whole link as one string.

Responses

  • 200 The link works.
  • 401 Wrong or revoked token.

A bare GET never raises an alert. Link previews, crawlers and mail scanners fetch URLs on their own, so only a request with a title rings phones. Remove any ?title= before testing.

Request
curl "$M91_SEND_LINK"
const res = await fetch(process.env.M91_SEND_LINK);
const result = await res.json();
import os, requests

res = requests.get(os.environ["M91_SEND_LINK"])
print(res.json())
Response
{
  "success": true,
  "data": {
    "ok": true,
    "channel": {
      "id": "6712ab…",
      "name": "Payments",
      "visibility": "PRIVATE"
    },
    "sender": {
      "id": "6712ac…",
      "label": "Grafana"
    }
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid sender token"
  }
}

Send an alert (GET)

GET/s/{token}

Raises an alert from a plain URL. Use it wherever you can only paste a link: a webhook field, a bookmark, a shortcut, a spreadsheet.

Authorization Send link token in the path. No headers needed.

Path parameters

token
stringrequired
The sk_… part of your send link. Use the whole link as one string.

Query parameters

title
stringrequired
5–2000 characters. Without it nothing is raised.
description
string
Up to 2000 characters.
severity
enum
LOW, MEDIUM, HIGH or CRITICAL. Default MEDIUM. See Severity.
respond
string
Comma-separated answer labels, up to 6. The first is SHARED, the rest PERSONAL. A trailing ! forces SHARED: respond=On it,Seen!.
isAutoClose
boolean
true false 1 0 yes no on off. Default false.
customId
string
Up to 200 characters.

Responses

  • 201 A new alert was raised. Same body as POST.
  • 200 A repeat was suppressed.
  • 400 A field is invalid.
  • 401 Wrong or revoked token.
  • 409 Nobody can receive. See CHANNEL_EMPTY.
  • 429 More than 60 sends a minute.

The link form carries only these fields. For attachments, callbackUrl, other or required / optional, use POST.

A browser gets an HTML result page. Anything else gets JSON.

Request
curl -G "$M91_SEND_LINK" \
  --data-urlencode "title=Payment 4821 failed" \
  --data-urlencode "severity=HIGH" \
  --data-urlencode "respond=I am on it,Seen" \
  --data-urlencode "customId=payment-4821"
const url = new URL(process.env.M91_SEND_LINK);
url.searchParams.set("title", "Payment 4821 failed");
url.searchParams.set("severity", "HIGH");
url.searchParams.set("respond", "I am on it,Seen");
url.searchParams.set("customId", "payment-4821");
const res = await fetch(url);
const result = await res.json();
import os, requests

res = requests.get(
    os.environ["M91_SEND_LINK"],
    params={
    "title": "Payment 4821 failed",
    "severity": "HIGH",
    "respond": "I am on it,Seen",
    "customId": "payment-4821",
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "channelId": "6712ab…",
    "channelName": "Payments",
    "customId": "payment-4821",
    "severity": "HIGH",
    "status": "OPEN",
    "isAutoClose": false,
    "createdAt": "2026-10-01T02:10:03.000Z",
    "delivered": 4,
    "unregistered": [],
    "noDevice": 1,
    "pending": 2
  }
}
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "customId": "payment-4821",
    "status": "OPEN",
    "delivered": 0,
    "deduplicated": true,
    "message": "An alert with customId \"payment-4821\" is already open, so nobody was alerted again."
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL",
    "details": {
      "fields": [
        {
          "field": "severity",
          "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL"
        }
      ]
    }
  }
}

Send an alert

POST/s/{token}

Raises an alert with the full payload. This is the main endpoint: one URL, no headers except Content-Type.

Authorization Send link token in the path. No headers needed.

Path parameters

token
stringrequired
The sk_… part of your send link. Use the whole link as one string.

Body

title
stringrequired
5–2000 characters. The line someone reads on a lock screen. summary is accepted as an alias.
description
string
Up to 2000 characters. What happened and what is needed to act.
severity
enum
LOW, MEDIUM, HIGH or CRITICAL. Default MEDIUM. See Severity.
responseOptions
array
Up to 20 answer buttons. See Response options. Omitted means nobody can answer and nothing can close the alert.
other
boolean
Default true. Adds a Something else reply where the person types an answer.
attachments
string[]
https links to files shown with the alert. They must open without a login. See Attachments.
callbackUrl
string
An https URL M91 POSTs to when someone answers and when the alert ends. See Callbacks.
isAutoClose
boolean
Default false. Whether the alert closes itself. See How an alert ends.
customId
string
Up to 200 characters. Your own id for the condition. Collapses repeats. See Repeats.

Response option object

label
stringrequired
Up to 24 characters. Written as the answer, in the first person. Labels must differ.
effect
enum
SHARED (I take responsibility) or PERSONAL (I do not). Default SHARED.
required
string[]
What the person must add to answer: "note", "attachment", or both.
optional
string[]
What the person may add: "note", "attachment", or both. Not the same field as in required.

Responses

  • 201 A new alert was raised.
  • 200 A repeat was suppressed. Nobody was alerted again.
  • 400 VALIDATION_ERROR or MALFORMED_JSON. Unknown fields are rejected.
  • 401 Wrong or revoked token.
  • 404 channel_not_found.
  • 409 CHANNEL_EMPTY. Nobody can receive. People must accept in the app.
  • 413 Body over 1 MB.
  • 429 More than 60 sends a minute. Wait for Retry-After.

Check delivered. It is the number of phones the alert was sent to. unregistered, noDevice and pending say why people were missed. See Delivery.

Content-Type: application/json is required. There is no recipient field: the channel is the recipient list.

Request
curl -X POST "$M91_SEND_LINK" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
      {
        "label": "I am on it",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ]
  }'
const res = await fetch(process.env.M91_SEND_LINK, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
      {
        "label": "I am on it",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ]
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    os.environ["M91_SEND_LINK"],
    json={
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
        {
            "label": "I am on it",
            "effect": "SHARED",
        },
        {
            "label": "Seen",
            "effect": "PERSONAL",
        },
    ],
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "channelId": "6712ab…",
    "channelName": "Payments",
    "customId": "payment-4821",
    "severity": "HIGH",
    "status": "OPEN",
    "isAutoClose": false,
    "createdAt": "2026-10-01T02:10:03.000Z",
    "delivered": 4,
    "unregistered": [],
    "noDevice": 1,
    "pending": 2
  }
}
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "customId": "payment-4821",
    "status": "OPEN",
    "delivered": 0,
    "deduplicated": true,
    "message": "An alert with customId \"payment-4821\" is already open, so nobody was alerted again."
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL",
    "details": {
      "fields": [
        {
          "field": "severity",
          "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL"
        }
      ]
    }
  }
}
{
  "success": false,
  "error": {
    "code": "CHANNEL_EMPTY",
    "message": "Nobody has joined this channel yet",
    "details": {
      "unregistered": [
        "919876543210"
      ]
    }
  }
}

Read an alert

GET/s/{token}/alerts/{id}

Who was reached, who answered, and what they chose. This is how your software learns the human decision.

Authorization Send link token in the path. No headers needed.

Path parameters

token
stringrequired
The sk_… part of your send link. Use the whole link as one string.
id
stringrequired
The customId you sent, or the _id the send returned.

Responses

  • 200 The alert. decision is null until someone gives a SHARED response.
  • 401 Wrong or revoked token.
  • 404 No alert with that id on this channel.

Only a SHARED response sets decision. A PERSONAL one such as “Seen” never does, so an agent cannot read it as “Approved”. If responses has entries and decision is null, those options were PERSONAL.

responses[] holds every answer with label, effect, optionIndex, at, by (the responder’s id), and note and attachments (always present: null and [] when not given). pending is how many people have not answered yet.

Poll every few seconds, or use a callback. M91 never expires an alert, so set your own timeout.

Request
curl "$M91_SEND_LINK/alerts/deploy-prod"
const res = await fetch(process.env.M91_SEND_LINK + "/alerts/deploy-prod");
const result = await res.json();
import os, requests

res = requests.get(os.environ["M91_SEND_LINK"] + "/alerts/deploy-prod")
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "customId": "deploy-prod",
    "status": "RESOLVED",
    "severity": "HIGH",
    "title": "Approve deploy to prod?",
    "isAutoClose": false,
    "responseOptions": [
      {
        "label": "Approve",
        "effect": "SHARED"
      },
      {
        "label": "Reject",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ],
    "attachments": [],
    "responses": [
      {
        "label": "Approve",
        "effect": "SHARED",
        "optionIndex": 0,
        "at": "2026-10-01T03:14:22.000Z",
        "by": "…",
        "note": "checked the migration, go ahead",
        "attachments": [
          {
            "id": "3a24…",
            "url": "https://…/photo.jpg",
            "name": "photo.jpg",
            "type": "image/jpeg",
            "size": 48213
          }
        ]
      }
    ],
    "pending": 1,
    "decision": {
      "label": "Approve",
      "effect": "SHARED",
      "at": "2026-10-01T03:14:22.000Z",
      "by": "…"
    },
    "resolvedAt": "2026-10-01T03:20:41.000Z"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "alert_not_found"
  }
}

Close an alert

POST/s/{token}/close

Closes an open alert. Do it when the problem clears. Closing also re-arms the customId, so the next failure can alert again.

Authorization Send link token in the path. No headers needed.

Path parameters

token
stringrequired
The sk_… part of your send link. Use the whole link as one string.

Body

customId
string
Your id for the alert. Send this or alertId.
alertId
string
The _id from the send response.

Responses

  • 200 Closed.
  • 400 Neither customId nor alertId was sent.
  • 403 Already resolved. Treat as success.
  • 404 Nothing open with that id. Treat as success.

Scoped to the token’s channel. One link cannot close another channel’s alerts.

Request
curl -X POST "$M91_SEND_LINK/close" \
  -H "Content-Type: application/json" \
  -d '{
    "customId": "payment-4821"
  }'
const res = await fetch(process.env.M91_SEND_LINK + "/close", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "customId": "payment-4821"
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    os.environ["M91_SEND_LINK"] + "/close",
    json={
    "customId": "payment-4821",
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "status": "RESOLVED"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "alert_not_found"
  }
}
Platform API

Get key info

GET/api/v1/me

Returns the key’s label and its owner. Use it to check a key is valid.

Authorization Header Authorization: Bearer m91sk_…

Responses

  • 200 The key.
  • 401 Missing or revoked key.
Request
curl "https://m91-api.msg91.com/api/v1/me" \
  -H "Authorization: Bearer $M91_API_KEY"
const res = await fetch("https://m91-api.msg91.com/api/v1/me", {
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}` },
});
const result = await res.json();
import os, requests

res = requests.get(
    "https://m91-api.msg91.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "label": "CRM backend",
    "owner": "…"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Add a recipient

POST/api/v1/recipients

Invites one person so you can alert them directly. Idempotent: call it on every login if you like.

Authorization Header Authorization: Bearer m91sk_…

Body

phone
stringrequired
Digits only, 8–15, country code included, no +. Example 919876543210.
label
string
Up to 60 characters. A name for the person.

state values

pending
state
Invited, has not answered. Wait. Do not retry.
accepted
state
Can be alerted. Only accepted recipients can.
declined
state
Terminal. No API can re-invite. Only the person can undo it in their app.

Responses

  • 200 The recipient and their state.
  • 400 Invalid phone or label.
  • 401 Bad key.

Until the person accepts in the M91 app, reachable is false and an alert reaches nobody.

Request
curl -X POST "https://m91-api.msg91.com/api/v1/recipients" \
  -H "Authorization: Bearer $M91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "919876543210",
    "label": "Sales rep"
  }'
const res = await fetch("https://m91-api.msg91.com/api/v1/recipients", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "phone": "919876543210",
    "label": "Sales rep"
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://m91-api.msg91.com/api/v1/recipients",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    json={
    "phone": "919876543210",
    "label": "Sales rep",
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "phone": "919876543210",
    "state": "pending",
    "reachable": false
  }
}

Remove a recipient

DELETE/api/v1/recipients/{phone}

Stops you being able to alert this person.

Authorization Header Authorization: Bearer m91sk_…

Path parameters

phone
stringrequired
Digits only, 8–15, country code included, no +. Example 919876543210.

Responses

  • 200 Removed.
  • 401 Bad key.
Request
curl -X DELETE "https://m91-api.msg91.com/api/v1/recipients/919876543210" \
  -H "Authorization: Bearer $M91_API_KEY"
const res = await fetch("https://m91-api.msg91.com/api/v1/recipients/919876543210", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}` },
});
const result = await res.json();
import os, requests

res = requests.delete(
    "https://m91-api.msg91.com/api/v1/recipients/919876543210",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "phone": "919876543210",
    "removed": true
  }
}

Send a direct alert

POST/api/v1/alerts

Alerts one person by phone number. It is a channel with one member, so responses, escalation and repeats behave like a send-link alert.

Authorization Header Authorization: Bearer m91sk_…

Body

phone
stringrequired
Digits only, 8–15, country code included, no +. Example 919876543210.
title
stringrequired
5–2000 characters. The line someone reads on a lock screen. summary is accepted as an alias.
description
string
Up to 2000 characters. What happened and what is needed to act.
severity
enum
LOW, MEDIUM, HIGH or CRITICAL. Default MEDIUM. See Severity.
responseOptions
array
Up to 20 answer buttons. See Response options. Omitted means nobody can answer and nothing can close the alert.
other
boolean
Default true. Adds a Something else reply where the person types an answer.
attachments
string[]
https links to files shown with the alert. They must open without a login. See Attachments.
callbackUrl
string
An https URL M91 POSTs to when someone answers and when the alert ends. See Callbacks.
isAutoClose
boolean
Default false. Whether the alert closes itself. See How an alert ends.
customId
string
Up to 200 characters. Your own id for the condition. Collapses repeats. See Repeats.

Response option object

label
stringrequired
Up to 24 characters. Written as the answer, in the first person. Labels must differ.
effect
enum
SHARED (I take responsibility) or PERSONAL (I do not). Default SHARED.
required
string[]
What the person must add to answer: "note", "attachment", or both.
optional
string[]
What the person may add: "note", "attachment", or both. Not the same field as in required.

Responses

  • 201 A new alert was raised. Same body as the send link.
  • 200 A repeat was suppressed.
  • 404 not_a_recipient. That phone was never invited. An alert never invites anyone.
  • 400 A field is invalid.
  • 401 Bad key.

An invited person is not an M91 user yet, so an alert to them would arrive as an ordinary message that does not break through Do Not Disturb. Add the recipient first.

Request
curl -X POST "https://m91-api.msg91.com/api/v1/alerts" \
  -H "Authorization: Bearer $M91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "919876543210",
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
      {
        "label": "I am on it",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ]
  }'
const res = await fetch("https://m91-api.msg91.com/api/v1/alerts", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "phone": "919876543210",
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
      {
        "label": "I am on it",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ]
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://m91-api.msg91.com/api/v1/alerts",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    json={
    "phone": "919876543210",
    "title": "Payment 4821 failed",
    "description": "Card declined 3 times. Customer is waiting.",
    "severity": "HIGH",
    "customId": "payment-4821",
    "responseOptions": [
        {
            "label": "I am on it",
            "effect": "SHARED",
        },
        {
            "label": "Seen",
            "effect": "PERSONAL",
        },
    ],
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "channelId": "6712ab…",
    "channelName": "Payments",
    "customId": "payment-4821",
    "severity": "HIGH",
    "status": "OPEN",
    "isAutoClose": false,
    "createdAt": "2026-10-01T02:10:03.000Z",
    "delivered": 4,
    "unregistered": [],
    "noDevice": 1,
    "pending": 2
  }
}
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "customId": "payment-4821",
    "status": "OPEN",
    "delivered": 0,
    "deduplicated": true,
    "message": "An alert with customId \"payment-4821\" is already open, so nobody was alerted again."
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "not_a_recipient"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL",
    "details": {
      "fields": [
        {
          "field": "severity",
          "message": "severity must be one of: LOW, MEDIUM, HIGH, CRITICAL"
        }
      ]
    }
  }
}

Read a direct alert

GET/api/v1/alerts/{id}

Reads what the person decided. Same response as Read an alert.

Authorization Header Authorization: Bearer m91sk_…

Path parameters

id
stringrequired
The customId or _id.

Query parameters

phone
stringrequired
The recipient the alert was sent to.

Responses

  • 200 The alert, including decision.
  • 404 No such alert for that recipient.
Request
curl -G "https://m91-api.msg91.com/api/v1/alerts/payment-4821" \
  -H "Authorization: Bearer $M91_API_KEY" \
  --data-urlencode "phone=919876543210"
const url = new URL("https://m91-api.msg91.com/api/v1/alerts/payment-4821");
url.searchParams.set("phone", "919876543210");
const res = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}` },
});
const result = await res.json();
import os, requests

res = requests.get(
    "https://m91-api.msg91.com/api/v1/alerts/payment-4821",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    params={
    "phone": "919876543210",
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703f1a2c8e4b90012ab34cd",
    "customId": "deploy-prod",
    "status": "RESOLVED",
    "severity": "HIGH",
    "title": "Approve deploy to prod?",
    "isAutoClose": false,
    "responseOptions": [
      {
        "label": "Approve",
        "effect": "SHARED"
      },
      {
        "label": "Reject",
        "effect": "SHARED"
      },
      {
        "label": "Seen",
        "effect": "PERSONAL"
      }
    ],
    "attachments": [],
    "responses": [
      {
        "label": "Approve",
        "effect": "SHARED",
        "optionIndex": 0,
        "at": "2026-10-01T03:14:22.000Z",
        "by": "…",
        "note": "checked the migration, go ahead",
        "attachments": [
          {
            "id": "3a24…",
            "url": "https://…/photo.jpg",
            "name": "photo.jpg",
            "type": "image/jpeg",
            "size": 48213
          }
        ]
      }
    ],
    "pending": 1,
    "decision": {
      "label": "Approve",
      "effect": "SHARED",
      "at": "2026-10-01T03:14:22.000Z",
      "by": "…"
    },
    "resolvedAt": "2026-10-01T03:20:41.000Z"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "alert_not_found"
  }
}

Close a direct alert

POST/api/v1/alerts/close

Closes an open direct alert.

Authorization Header Authorization: Bearer m91sk_…

Body

phone
stringrequired
Digits only, 8–15, country code included, no +. Example 919876543210.
customId
string
The alert’s customId. Send this or alertId.
alertId
string
The _id from the send response.

Responses

  • 200 Closed.
  • 400 Neither customId nor alertId was sent.
  • 403 Already resolved. Treat as success.
  • 404 Nothing to close. Treat as success.
Request
curl -X POST "https://m91-api.msg91.com/api/v1/alerts/close" \
  -H "Authorization: Bearer $M91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "919876543210",
    "customId": "payment-4821"
  }'
const res = await fetch("https://m91-api.msg91.com/api/v1/alerts/close", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "phone": "919876543210",
    "customId": "payment-4821"
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://m91-api.msg91.com/api/v1/alerts/close",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    json={
    "phone": "919876543210",
    "customId": "payment-4821",
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "_id": "6703…",
    "status": "RESOLVED"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "alert_not_found"
  }
}

Create a channel

POST/api/v1/channels

Creates a team channel and returns its send link. Use it when your platform creates one channel per customer team.

Authorization Header Authorization: Bearer m91sk_…

Body

name
stringrequired
Up to 80 characters.
alertOwner
boolean
Default true. Set false so the key’s owner is not added and paged for every channel.

Responses

  • 201 The new channel.
  • 400 Missing or too long name.

Not idempotent. It takes no id from you, so calling it twice makes two channels. Store the _id or sendLink against your own team straight away.

An API key can create and staff a channel but cannot alert it. Alerting a team is the send link’s job.

Request
curl -X POST "https://m91-api.msg91.com/api/v1/channels" \
  -H "Authorization: Bearer $M91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp on-call",
    "alertOwner": false
  }'
const res = await fetch("https://m91-api.msg91.com/api/v1/channels", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Acme Corp on-call",
    "alertOwner": false
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://m91-api.msg91.com/api/v1/channels",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    json={
    "name": "Acme Corp on-call",
    "alertOwner": False,
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "id": "6712ab…",
    "name": "Acme Corp on-call",
    "sendLink": "https://m91-api.msg91.com/s/sk_…"
  }
}

List channels

GET/api/v1/channels

Returns every channel you can send to. Not paginated.

Authorization Header Authorization: Bearer m91sk_…

Responses

  • 200 An array of channels.
Request
curl "https://m91-api.msg91.com/api/v1/channels" \
  -H "Authorization: Bearer $M91_API_KEY"
const res = await fetch("https://m91-api.msg91.com/api/v1/channels", {
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}` },
});
const result = await res.json();
import os, requests

res = requests.get(
    "https://m91-api.msg91.com/api/v1/channels",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
)
print(res.json())
Response
{
  "success": true,
  "data": [
    {
      "_id": "6712ab…",
      "name": "Acme Corp on-call",
      "sendLink": "https://m91-api.msg91.com/s/sk_…"
    }
  ]
}

Add channel members

POST/api/v1/channels/{id}/members

Invites people into a channel by phone number. Each person still has to accept in the app.

Authorization Header Authorization: Bearer m91sk_…

Path parameters

id
stringrequired
The channel id.

Body

phones
string[]required
Phone numbers, digits only, 8–15, no +. Up to 500 per call.

Responses

  • 200 Who was added.
  • 404 Channel not found or not yours.
Request
curl -X POST "https://m91-api.msg91.com/api/v1/channels/6712ab…/members" \
  -H "Authorization: Bearer $M91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": [
      "919876543210",
      "919812345678"
    ]
  }'
const res = await fetch("https://m91-api.msg91.com/api/v1/channels/6712ab…/members", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "phones": [
      "919876543210",
      "919812345678"
    ]
  }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://m91-api.msg91.com/api/v1/channels/6712ab…/members",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
    json={
    "phones": ["919876543210", "919812345678"],
},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "added": [
      "919812345678"
    ],
    "alreadyMembers": [
      "919876543210"
    ],
    "invited": [
      "919812345678"
    ]
  }
}

Remove a channel member

DELETE/api/v1/channels/{id}/members/{phone}

Removes one person from a channel.

Authorization Header Authorization: Bearer m91sk_…

Path parameters

id
stringrequired
The channel id.
phone
stringrequired
Digits only, 8–15, country code included, no +. Example 919876543210.

Responses

  • 200 Removed.
  • 404 Channel not found or not yours.
Request
curl -X DELETE "https://m91-api.msg91.com/api/v1/channels/6712ab…/members/919876543210" \
  -H "Authorization: Bearer $M91_API_KEY"
const res = await fetch("https://m91-api.msg91.com/api/v1/channels/6712ab…/members/919876543210", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.M91_API_KEY}` },
});
const result = await res.json();
import os, requests

res = requests.delete(
    "https://m91-api.msg91.com/api/v1/channels/6712ab…/members/919876543210",
    headers={"Authorization": f"Bearer {os.environ['M91_API_KEY']}"},
)
print(res.json())
Response
{
  "success": true,
  "data": {
    "phone": "919876543210",
    "state": "REMOVED"
  }
}
Alert behavior

What goes in an alert

An alert is a short message with buttons. Only the title is required. Add the other parts when the situation needs them.

PartAdd it whenField
The headlinealwaystitle
The detailsthe person has to decide something and the title is not enoughdescription
How urgentalways. The default never phones anyoneseverity
The buttonsthe person has to do something, which is almost every alertresponseOptions
Proofa graph, screenshot or document would make it obviousattachments
A way backyour software is waiting for the answercallbackUrl

Two more settings decide how it ends (isAutoClose) and what to call the problem (customId). Both are explained below.

Write the title like a text to a friend: say what broke and where. Payments API returning errors is good. Alert is not. Put numbers and next steps in description, and link long logs with attachments.

Severity

Every alert rings loudly, even on silent. Severity only decides what happens if the first ring is ignored.

LevelThink of it asWhat M91 does
LOWFYIRings once. Does not chase.
MEDIUM (default)Look at this soonRings again for 2 minutes. Never phones anyone.
HIGHNeeds a person nowKeeps ringing for 18 minutes. Phones only if nobody has responded and nobody has even opened it.
CRITICALMoney or safety is at riskKeeps ringing for 60 minutes and phones people, two at a time. Tells the channel owner after 15 minutes.
  • As soon as one person responds, all of this stops.
  • If nobody ever answers, M91 stops trying, tells the channel owner, and leaves the alert open.
  • Phone calls start 45 seconds after nobody has responded, with up to 10 people per round and 50 calls per alert. Each person gets at most one call every 5 minutes.
Do not mark everything CRITICAL. If people get phoned for small things, they stop picking up, and the next real emergency is missed.

Response options

These are the buttons the person taps. They pick one, once, and it cannot be changed. There are two kinds:

TypeIt meansWhat happens to everyone else
SHARED“I will take this.”The alert disappears for them.
PERSONAL“I have seen it, but it is not mine.”It stays for them.

Write each button as the answer, in the first person, up to 24 characters: I am on it, Approve, Already fixed. Not OK or Option 1.

If you wantSend these buttons
One person to take it onone SHARED button, plus PERSONAL ones like Seen
A yes or no decisiontwo SHARED buttons: Approve and Reject
A reason when the answer is nomake the no button ask for a note: "required": ["note"]
Everyone to confirmonly PERSONAL buttons. The alert closes when the last person answers
Just a heads-up, no buttons"responseOptions": [] and "isAutoClose": true
Two common mistakes. One button on its own is not a choice: it only tells you somebody saw it. And leaving responseOptions out is not the same as sending []. If you leave it out, nobody can answer and nothing can close the alert, so it sits open forever.

Asking for a note or a file. A button can require or allow a note, a file, or both: "required": ["note"], "optional": ["attachment"]. Use it when the answer needs proof or a reason. Do not put a requirement on every button, because people need a quick one-tap way out.

Free text. By default M91 adds a Something else option where people type their own reply. It never takes the alert, so it never clashes with your buttons. Leave it on unless the answer must be one of your buttons ("other": false).

When does an alert close?

An alert stays open until somebody closes it. isAutoClose is false unless you say otherwise.

What happensDoes it close?
Someone taps a SHARED buttononly if isAutoClose is true
Everyone tapped a PERSONAL button, and there was no SHARED buttonyes
No buttons ([]) and isAutoClose: trueyes, as soon as it is delivered
No buttons and no isAutoClosenever. Nothing can close it

There is no timer. If your software is waiting for a person, decide what silence means, treat it as “no”, and close the alert yourself.

Repeats and customId

customId is a name you give to a problem, like payment-4821 or disk-full-db1. Use the same name every time the same problem happens.

  • While that alert is open, sending it again does nothing. Nobody is disturbed twice, and the new text is ignored.
  • Closing the alert frees the name. If the problem comes back, the same alert reopens (earlier answers are cleared).
  • Do not put a timestamp in it. Every send would look like a new problem and ring again.
  • The name is per channel, so two channels can both use disk-full.
  • Separately, identical messages sent within 5 seconds are merged into one.

Both cases return 200 with deduplicated: true and a short message. delivered is 0 or missing, because nobody was alerted again.

Combinations to avoid

If you sendWhat happens
No buttons and no isAutoCloseNobody can answer and nothing can close it
Every button asks for something, and other is falseNobody can answer at all
MEDIUM and nobody looksRings for 2 minutes, then goes quiet. No call, ever
HIGH and somebody opens itNo call is made, because somebody is already looking
A SHARED button and isAutoClose: falseOne person takes it, the rest are released, and it stays open until closed
callbackUrl with PERSONAL buttons on 300 people300 callbacks. Use the closed event if you only want the final result

Attachments

Add links to files, such as a graph, a screenshot or a PDF. They show inside the alert. Images appear in the alert, and other files open in the phone’s viewer.

  • Links only. You cannot upload a file. M91 shows your link and does not keep a copy, so the link has to stay alive.
  • The link must open without a login. A link to your internal dashboard works on your laptop but not on somebody else’s phone. A signed link works well.
  • If a link fails, it is skipped and the alert still goes out.

Callbacks

Add a callbackUrl when your software is waiting for the answer. M91 sends it a message when someone answers (answered, once per person) and when the alert ends (closed). Without it, you have to keep asking with GET.

{ "event": "answered", "at": "2026-10-01T12:14:09.535Z",
  "alert": { "id": "…", "customId": "deploy-4821", "title": "…" },
  "response": { "label": "Approve", "effect": "SHARED", "by": { "id": "…", "name": "Aryan" },
                "at": "…", "note": "go ahead", "attachments": [] },
  "idempotencyKey": "<alertId>-<userId>-<generation>" }
  • The closed event gives the final picture: reason, all responses, and who is still pending.
  • The same message can arrive twice. Use idempotencyKey to ignore repeats.
  • Check the signature so you know it came from M91. It is an HMAC-SHA256 of "<timestamp>.<raw body>", using the secret returned when the alert was created. Use the raw body and reject old timestamps.
  • Reply with 2xx quickly. note and attachments are always there (null or [] when empty).

Delivery

A 2xx means accepted, not delivered

True
a 201 says M91 recorded the alert and queued it, usually within a few hundred milliseconds. Fan-out to devices happens afterwards, in a separate process. delivered counts recipients the alert was dispatched to.
Why
a push service will accept a token the device platform has since invalidated and report success, so a dead registration fails silently at the far end, after everything on this side reported fine.
Do
assert on delivered, not on the status code, and treat delivered: 0 as a failure even though the request succeeded.
Don’t
build a workflow that assumes an alert was seen. The only evidence of that is a response coming back, which is what responseOptions are for.

Delivery depends on things outside M91

True
a phone with notifications denied, no network, or the app uninstalled still counts as a recipient and makes no sound. unregistered is invited but never signed in. noDevice is signed in with no device, usually after a reinstall.
Why
neither retries nor a durable queue can fix a device that is set not to listen.
Do
have each member tap Send a test alert on their own phone when they join, and open the app once after a reinstall.
Don’t
make M91 the only record of something that must not be missed.

Errors

Every error is { "success": false, "error": { "code", "message", "details", "docs" } }. Branch on code. error.docs links to the fix.

StatuscodeMeaningWhat to do
400VALIDATION_ERRORA field is invalid. details.fields names it. Unknown fields are rejected.Fix that field.
400MALFORMED_JSONBody is not JSON.Fix quoting. Send Content-Type: application/json.
401UNAUTHORIZEDToken or key is missing, wrong, forged or revoked.Copy it again. Do not retry.
403FORBIDDENNot allowed. On close, usually already resolved.On close, treat as success.
404NOT_FOUNDAbsent, or not yours. The two look the same on purpose.Check the id and channel.
409CHANNEL_EMPTYNobody can receive. details.unregistered lists invited numbers with no account.People must install, sign in and accept.
413PAYLOAD_TOO_LARGEBody over 1 MB.Send a summary and a reference.
429RATE_LIMITEDOver 60 sends a minute per link. Retry-After is always set.Wait, then add a customId.
500INTERNAL_ERRORUnexpected.Retry with backoff.

Limits

ItemLimit / default
title5–2000 characters
description2000 characters
customId200 characters
Response option label24 characters
Response options20 in JSON, 6 in a link
Channel name80 characters
Key or sender label60 characters
phone8–15 digits, no +
Members per invite call500
Request body1 MB
Send rate60 per minute per send link
Duplicate payload window5 seconds
Default severityMEDIUM
Dialling severitiesHIGH, CRITICAL
Escalation delay45 seconds
People per wave10
Calls per alert50
Calls per person1 per 5 minutes
Retentionclosed alerts are deleted after 30 days by default