# Magic MessageGate: full documentation
> README.md and AGENTS.md of strapi-plugin-magic-messagegate in one file.
> Source: https://github.com/Schero94/Magic-MessageGate

# Magic MessageGate
**WhatsApp, RCS, Telegram and SMS for Strapi 5: send templates and files, receive replies, buttons and photos, track delivery, fall back automatically.**
[](https://www.npmjs.com/package/strapi-plugin-magic-messagegate)
[](https://github.com/Schero94/Magic-MessageGate/blob/main/LICENSE)
[](https://strapi.io)
[](https://nodejs.org)
Send a template from your Strapi code, or from any other service, with one call. MessageGate picks the channel, fills in the variables, sends the message exactly once, follows it from _sent_ to _delivered_ to _read_, and falls back to RCS and SMS when WhatsApp can't reach the number. Replies come back as events with their text, button and files, so your code can answer them. It only uses the official provider APIs, so there is no WhatsApp Web session that can get your number banned.
**send → receive → process → automate**: `messages.send` → `messagegate.message.received` → `inbound.get` / `inbound.getMedia` / `conversations.history` → `messages.reply` → `inbound.markProcessed`.

## Features
- **Four channels, one API.** WhatsApp through Meta's Cloud API, RCS through Twilio, Telegram through the Bot API, SMS through seven.io or Twilio. No vendor SDKs; each provider is a small HTTPS client.
- **Templates with variables and buttons.** An editor with a live preview for WhatsApp, RCS rich cards, Telegram and SMS (including the SMS part count). WhatsApp templates (also with image, video or PDF headers) are submitted to Meta from Strapi; RCS cards become Twilio Content templates.
- **Attachments.** Send a PDF, image or video from the media library or a public https URL. WhatsApp, RCS and Telegram carry the file; SMS gets a short signed download link that expires.
- **Inbox.** Replies, button taps, photos, documents, voice notes and locations arrive as an exactly-once event. Files are downloaded, checked (size, type, content) and stored in the media library. Answer from code or from the admin inbox.
- **Testable.** A dry run shows the route and the rendered message without sending; a sandbox mode with magic test numbers runs your app tests without network or cost.
- **Exactly once.** A durable outbox in your database. Each message is sent once, also with several Strapi processes, and the same `idempotencyKey` never sends twice.
- **Delivery and read tracking.** Every message has a timeline: queued → sent → delivered → read, or failed with a reason in plain language.
- **Fallback chain.** WhatsApp → RCS → SMS. A number that isn't on WhatsApp or can't receive RCS is remembered, so the next message skips that channel. E-mail through [Magic Mail](https://github.com/Schero94/Magic-Mail) is an opt-in last step and off by default; MessageGate never sends e-mail itself.
- **Routing rules.** Choose the channel order per template, tag or country.
- **Consent built in.** Consent per channel, STOP keywords (`STOP`, `STOPP`, `ABMELDEN`, `UNSUBSCRIBE`, editable), GDPR export and erasure per contact.
- **Number checks.** A free format check (valid, mobile or landline), plus optional paid checks with a shared cache and monthly budget: Twilio line type and seven.io HLR (is the number assigned?). Sends to unassigned numbers can stop before they cost anything.
- **Safe retries.** Retries after about 1, 5 and 15 minutes, only when the provider provably did not take the message. When the outcome is unknown, the message becomes _uncertain_ and an admin decides, instead of risking a duplicate.
- **An admin that looks like Strapi.** Built only from the Strapi Design System, in English, German, French, Spanish and Portuguese, light and dark, down to phone width.
- **Ready for several instances.** Tested with 8 processes on one PostgreSQL database (Railway replicas, pm2 cluster mode).
## What the official APIs allow
People often ask for things that WhatsApp, Telegram and SMS providers don't offer. Here is what is possible:
| Question | WhatsApp (Cloud API) | Telegram (Bot API) | SMS | What MessageGate does |
| ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Does the number exist? | No check before sending. The first send tells you: error 131026 means not on WhatsApp | Only for people who started your bot | Paid carrier lookups exist | Free format check; optional Twilio line-type lookup (cached, budget-capped); learns "not on WhatsApp" from the first send |
| Is the person online? | Not available | Not available | Not available | Shows the **last activity** instead: last reply, last delivery, last read |
| Has the person read it? | Yes, a `read` status, unless the recipient turned read receipts off | No read receipts for bots | Delivery receipt only | A timeline per message and a read rate per template; read rates are a lower bound |
| Can it receive RCS? | – | – | – | Twilio has no RCS check. MessageGate sends with RCS and learns from error 63036, then falls back to SMS |
| Is the number active? | – | – | HLR lookups (paid) | Optional seven.io HLR check, cached; can stop sends to unassigned numbers (`NUMBER_INACTIVE`) |
## Quick start
1. Install:
```bash
npm install strapi-plugin-magic-messagegate
```
2. Configure the plugin in `config/plugins.js`:
```js
module.exports = ({ env }) => ({
'magic-messagegate': {
enabled: true,
config: {
encryptionKey: env('MESSAGEGATE_ENCRYPTION_KEY'), // 16+ characters, never change it later
publicUrl: env('PUBLIC_URL'), // https://cms.example.com, used for webhook URLs
},
},
});
```
3. Build and start Strapi, then open **MessageGate** in the admin menu.
4. **Accounts → Connect a channel.** SMS or Telegram are the quickest for a first test; WhatsApp needs a Meta app (see below).
5. **Templates → Create template**, then send it from **Messages → Send message**, or from code:
```js
await strapi
.plugin('magic-messagegate')
.service('messages')
.send({
to: '+4915123456789',
template: 'order_shipped',
language: 'de',
variables: { first_name: 'Anna', order_id: 'A-10423' },
idempotencyKey: 'order-shipped-A-10423',
});
```
Requirements: Strapi `^5.38.0`, Node.js `^22.21.0 || >=24.9.0 <=26.x.x`, PostgreSQL, MySQL 8 or SQLite.
Without `encryptionKey`, MessageGate falls back to `MESSAGEGATE_ENCRYPTION_KEY`, then `APP_KEYS`, then `ADMIN_JWT_SECRET`. If the key changes later, stored secrets and phone numbers can no longer be read.
## Screenshots

_Messages with status, channel and filters._

_Template editor with a live WhatsApp preview._

_A conversation: inbound photo, location and the reply box._

_Connect WhatsApp through Meta, including the Business App QR path._

_Delivery and read rates per channel and template._

_An RCS rich card with buttons, created on Twilio._
More screens (inbox, contacts, settings) are on the [docs site](https://schero94.github.io/Magic-MessageGate/#screens). Every screen in light, dark and phone width is in the [`pics/` folder on GitHub](https://github.com/Schero94/Magic-MessageGate/tree/main/pics).
## Connect your channels
### WhatsApp (Meta Cloud API)
What the account owner sets up once at Meta:
1. A **Meta business portfolio** and a **Meta app** with the WhatsApp product. **Business verification** raises your sending limits.
2. A **phone number**: a new number for the API, or your existing **WhatsApp Business App** number. Meta calls the second option _coexistence_: you keep using the app on your phone, and Strapi sends through the API.
3. A payment method in WhatsApp Manager. Meta charges per delivered template message, by category (marketing, utility, authentication); see [Meta's pricing page](https://developers.facebook.com/docs/whatsapp/pricing).
Then, in **Accounts → Connect a channel → WhatsApp**, pick one of two ways:
- **Connect with Meta (Embedded Signup).** Opens Meta's own window. Choose a new number, or choose the WhatsApp Business App and scan the QR code with the app. MessageGate exchanges the code for a token on the server and subscribes your app to the number. Server config:
```js
config: {
providers: {
meta: {
embeddedSignup: {
appId: env('META_APP_ID'),
configId: env('META_SIGNUP_CONFIG_ID'),
appSecret: env('META_APP_SECRET'),
verifyToken: env('META_WEBHOOK_VERIFY_TOKEN'), // 16-128 characters: A-Z a-z 0-9 _ -
},
},
},
},
```
In the Meta app, set the webhook callback URL to `https:///api/magic-messagegate/webhooks/meta/app` with the same verify token, and subscribe to the `messages` and `message_template_status_update` fields.
Strapi's content security policy blocks Meta's script by default. Allow it in `config/middlewares.js`:
```js
{
name: 'strapi::security',
config: {
contentSecurityPolicy: {
useDefaults: true,
directives: {
'script-src': ["'self'", 'https://connect.facebook.net'],
'frame-src': ["'self'", 'https://www.facebook.com', 'https://web.facebook.com'],
},
},
},
},
```
If the Meta window can't load, the wizard says so and offers the manual path.
- **Enter credentials manually.** Paste the access token, phone number ID, WhatsApp Business Account ID and app secret. MessageGate then shows the webhook URL and verify token to copy into the Meta app.
### Telegram
1. Open [@BotFather](https://t.me/BotFather), create a bot and copy its token.
2. Paste the token in **Accounts → Connect a channel → Telegram**. MessageGate registers the webhook with a secret token.
3. A bot can't message someone by phone number. People link their chat through a one-time link (`https://t.me/?start=…`, valid for 30 minutes) that you create in **Contacts** or from code with `service('telegram').createLink(contactId)`.
### SMS (seven.io or Twilio)
- **seven.io**: API key, signing key for status reports, sender ID. The same account can run the paid HLR check.
- **Twilio**: account SID, auth token, and a sender number or messaging service. The same account can run the paid line-type lookup.
Copy the webhook URL shown for the account into the provider's status and inbound settings so delivery receipts and replies arrive.
### RCS (Twilio)
1. Get an RCS sender approved in the Twilio Console and add it to a **Messaging Service**.
2. **Accounts → Connect a channel → RCS**: account SID, auth token and the Messaging Service SID. Leave "Let Twilio fall back to SMS" off, so MessageGate's chain decides (WhatsApp → RCS → SMS) and every step has its own timeline.
3. Set the account's webhook URL as the Messaging Service's status callback and incoming-message URL.
4. Grant `rcs` consent for contacts like for the other channels. Plain RCS text templates work at once; rich cards with a title, image and buttons need **Create on Twilio** in the template editor.
Twilio offers no "can this number receive RCS" check. MessageGate tries RCS and remembers error 63036 (not RCS capable) for 30 days.
## Sending messages
### From Strapi code
```js
const messages = strapi.plugin('magic-messagegate').service('messages');
// An order update: WhatsApp first, SMS if the number isn't on WhatsApp.
const { id, status, channel, duplicate } = await messages.send({
to: '+4915123456789',
template: 'order_shipped',
language: 'de',
variables: { first_name: 'Anna', order_id: 'A-10423' },
idempotencyKey: 'order-shipped-A-10423',
});
// A login code: an AUTHENTICATION template with transactional: true
// needs no marketing consent, and it is dropped if it can't go out in time.
await messages.send({
to: '+4915123456789',
channel: 'sms',
template: 'login_code',
variables: { code: '482913' },
transactional: true,
notAfter: new Date(Date.now() + 10 * 60_000),
idempotencyKey: `login-${sessionId}`,
});
const detail = await messages.get(id); // status, timeline, fallbacks
```
**Attachments.** Add `attachment: { fileId }` (media library) or `attachment: { url: 'https://…', mimeType: 'application/pdf' }`. JPEG, PNG, PDF and MP4 are allowed. WhatsApp, RCS and Telegram send the file; SMS gets a signed link valid for 72 hours (Settings → Inbox and files). A channel that can't carry the file (too large, wrong type) is skipped. Only a reference is stored, never the file.
**Dry run.** `messages.send(input, { dryRun: true })` returns the channel chain, which channels can be used and why not, the account and the rendered payload, without sending or charging anything. Handy in tests and before a campaign.
**Variables in WhatsApp buttons.** A URL button can end in one variable, for example `https://shop.example/track/{{order_id}}`. Pass only the suffix (`order_id: 'A-10423'`); WhatsApp appends it to the URL Meta approved, so a variable can never point the button at another site. Copy-code buttons take their value from `variables` too (at most 15 characters).
### From another service (Content API)
Create a Strapi API token (Settings → API Tokens) with the MessageGate permissions, then:
```bash
curl -X POST https://cms.example.com/api/magic-messagegate/messages \
-H "Authorization: Bearer $STRAPI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"data":{"to":"+4915123456789","template":"order_shipped","language":"de","variables":{"first_name":"Anna","order_id":"A-10423"},"idempotencyKey":"order-shipped-A-10423"}}'
```
| Method | Path | Purpose |
| ------ | ------------------------------------------------- | ------------------------------------------ |
| POST | `/api/magic-messagegate/messages` | send (202 new, 200 duplicate) |
| GET | `/api/magic-messagegate/messages/:id` | status and timeline |
| POST | `/api/magic-messagegate/consent` | record or revoke consent |
| POST | `/api/magic-messagegate/telegram-link` | create a Telegram link for a phone number |
| POST | `/api/magic-messagegate/lookup` | check a number (`hlr: true` for HLR) |
| POST | `/api/magic-messagegate/capabilities` | free summary: valid, active, WhatsApp, RCS |
| POST | `/api/magic-messagegate/templates/render` | render a template without sending |
| GET | `/api/magic-messagegate/inbound` | inbound messages (separate permission) |
| GET | `/api/magic-messagegate/inbound/:id/media` | an inbound file (or `?as=base64`) |
| POST | `/api/magic-messagegate/inbound/:id/reply` | answer on the same channel |
| GET | `/api/magic-messagegate/conversations/:contactId` | inbound and outbound history |
The Content API only accepts API tokens. Users-permissions logins are refused, because these routes act on any phone number. Set `contentApi.allowUsersPermissions: true` only if you add your own checks.
The full contract (every field, status, event and error code) is in [AGENTS.md](https://github.com/Schero94/Magic-MessageGate/blob/main/AGENTS.md).
### Events
React to deliveries without polling. Payloads carry no phone numbers and no message text:
```js
strapi.eventHub.on('messagegate.message.failed', ({ messageId, channel, code }) => {
strapi.log.warn(`Message ${messageId} on ${channel} failed: ${code}`);
});
```
Events: `messagegate.message.queued`, `.sent`, `.delivered`, `.read`, `.failed`, `.uncertain`, `.expired`, `.discarded`, `.fallback`, `.received`, plus `messagegate.media.ready`, `messagegate.media.failed`, `messagegate.contact.opted-out`, `messagegate.contact.unreachable` and `messagegate.template.status-changed`. Every event is emitted by exactly one process. The same events can go to your own https endpoint, signed with HMAC-SHA256 (Settings → Outgoing webhook; verification code in [AGENTS.md](https://github.com/Schero94/Magic-MessageGate/blob/main/AGENTS.md#outgoing-webhook)).
## Receiving messages
Every reply, button tap, photo, document, voice note or location arrives once as `messagegate.message.received`. Text, captions and files are stored encrypted or in your media library, never in the event.
### Access inbound messages and files from your code
```js
const mg = strapi.plugin('magic-messagegate');
mg.service('inbound').onReceived(async ({ inboundId, kind, buttonPayload }) => {
const message = await mg.service('inbound').get(inboundId); // text, button, location, media status
if (kind === 'media' && message.media.status === 'ready') {
const file = await mg.service('inbound').getMedia(inboundId, { as: 'buffer' }); // or 'stream', 'base64'
// or a signed URL for a service that fetches files: inbound.createMediaUrl(inboundId, { ttlSeconds: 300 })
}
const { items } = await mg.service('conversations').history({ inboundId }); // inbound and outbound, in order
await mg.service('messages').reply(inboundId, { text: 'Thanks, we are on it.' });
await mg.service('inbound').markProcessed(inboundId); // idempotent: alreadyProcessed on later calls
});
```
Files arrive a moment later than the message: wait for `messagegate.media.ready` (or check `media.status`). The data can be passed to any processing of your own. Do the work after the event, not inside it, and don't log message text.
### Recipes
**Appointment confirm or cancel with buttons.** Send a template with two quick-reply buttons (payloads `appt_yes`, `appt_cancel`; Telegram: inline buttons; RCS: suggested replies). Then:
```js
strapi.eventHub.on('messagegate.message.received', async ({ inboundId, buttonPayload, replyTo }) => {
if (!buttonPayload?.startsWith('appt_')) return;
const appointment = await findAppointmentByMessage(replyTo); // replyTo = the message with the buttons
await (buttonPayload === 'appt_yes' ? confirm(appointment) : cancel(appointment));
await strapi.plugin('magic-messagegate').service('inbound').markProcessed(inboundId);
});
```
**Support auto-reply and keyword routing.** Look at `message.text` (`inbound.get`), route keywords (`RECHNUNG`, `TERMIN`) to your own handlers and answer with `messages.reply(inboundId, { text })`. On WhatsApp, free text only works within 24 hours of the customer's last message; after that, `reply` fails with `WINDOW_CLOSED` and you send a template instead (`{ template, variables }`).
**Receipt photo → order.** On `messagegate.media.ready`, load the file with `inbound.getMedia(inboundId)` (or link the media library file by `fileId`) and attach it to the order the conversation belongs to (`history` or `replyTo`).
**Voice note → support.** `media.mime` is `audio/ogg` with `duration`; forward `inbound.createMediaUrl(inboundId)` (5 minutes) to your support tool instead of the file itself.
**Idempotent worker.** Process `GET /api/magic-messagegate/inbound?processed=false` in a loop and call `POST /inbound/:id/processed`; `alreadyProcessed: true` tells a second worker to skip.
**Virus scan.** Register a scanner in every process (for example in your app's `bootstrap`); files stay in quarantine, not stored, until it answers `clean`:
```js
strapi
.plugin('magic-messagegate')
.service('inbound')
.onMediaScan(async ({ bytes, mime }) => {
return (await myScanner.scan(bytes)) ? 'clean' : 'infected';
});
```
**External consumer.** Turn on Settings → Outgoing webhook, copy the signing secret once and check `X-MessageGate-Signature` as shown in [AGENTS.md](https://github.com/Schero94/Magic-MessageGate/blob/main/AGENTS.md#outgoing-webhook). Deliveries carry ids and statuses only; fetch the text with the Content API.
**Login link through Magic Link.** Create the token with [Magic Link](https://github.com/Schero94/strapi-plugin-magic-link-v5) (`createToken`) and send its login URL by SMS or Telegram as a template variable. WhatsApp only allows login **codes** in `AUTHENTICATION` templates, not links, so send the code there (`transactional: true`).
### Inbound files: limits, storage and privacy
| Provider | Retrievable for | Size limit | Notes |
| -------- | ---------------------------------------- | ------------------------------------------ | ----------------------------------------------------- |
| WhatsApp | 7 days | 100 MB from customers (Meta), your `maxMb` | downloaded with the access token; URL valid 5 minutes |
| Telegram | 24 hours (MessageGate retries that long) | 20 MB (Bot API `getFile`), your `maxMb` | photos, documents, voice notes, videos, stickers |
| Twilio | until deleted | your `maxMb` | basic auth; SMS (MMS) and RCS |
| seven.io | – | – | inbound SMS text only (no media documented) |
Downloads stop at `inboundMedia.maxMb` (25 MB) while streaming, accept only allowed types, compare the first bytes with the type, remove EXIF location data from JPEG and PNG, and store the file in the media library folder **MessageGate inbound** (works with S3, Cloudinary and every other upload provider). Set **Inbound files → Do not store** to keep only metadata. Inbound messages and their files are deleted after 90 days (Settings → Inbox and files) and with a GDPR erasure; the GDPR export includes them.
## Configuration
`config/plugins.js` holds the infrastructure settings. Business settings are edited in **MessageGate → Settings** and stored in the database.
| Option | Default | Description |
| ----------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| `encryptionKey` | env fallback (see above) | Key for secrets and phone numbers at rest |
| `publicUrl` | `server.url` | Public base URL used to build webhook URLs |
| `defaultCountry` | `DE` | Country for numbers written without `+` |
| `defaultNotAfterHours` | `24` | Deadline for messages without `notAfter` |
| `worker.enabled` | `true` | Set `false` on a process that should not send (for example web-only) |
| `worker.intervalMs` | `5000` | How often each process looks for due messages |
| `worker.batchSize` / `worker.concurrency` | `10` / `2` | Messages per claim / sent in parallel per process |
| `worker.leaseMs` | `120000` | How long a claimed message stays reserved |
| `retry.delaysMs` | `[60000, 300000, 900000]` | Waits before retries 1 to 3 |
| `retry.jitter` | `0.2` | Random spread of the waits (±20 %) |
| `contentApi.allowUsersPermissions` | `false` | Let users-permissions logins call the Content API |
| `rateLimits.sendPerMinute` | `120` | Content API sends per API token, shared by all processes |
| `rateLimits.lookupPerMinute` | `30` | Content API lookups per caller |
| `rateLimits.webhookPerMinute` | `1200` | Webhook requests per account |
| `rateLimits.adminWritePerMinute` | `60` | Admin write actions per admin user |
| `rateLimits.inboundPerMinute` | `300` | Content API reads of inbound messages and files per token |
| `rateLimits.downloadPerMinute` | `60` | Signed file downloads per IP |
| `providers.mode` | `live` | `sandbox`: in-process fake providers for tests (see below) |
| `outgoingWebhooks.allowPrivateHosts` | `false` | Development only: allow a local outgoing webhook receiver |
| `providers.meta.graphVersion` | built in | Pin a Graph API version, for example `v23.0` |
| `providers.meta.embeddedSignup` | none | `appId`, `configId`, `appSecret`, `verifyToken` for Connect with Meta |
| `providers..timeoutMs` | built in | Request timeout per provider (100 to 60000) |
**Settings page** (defaults in brackets): default country (DE), consent required (on), opt-out keywords, default channel chain (WhatsApp → RCS → SMS; installs from 1.0 keep their saved chain), up to 50 routing rules by template, tag or country, e-mail fallback through Magic Mail (off), paid lookups: Twilio line type and seven.io HLR (off, 30-day cache, 500 per month), stop sends to unassigned numbers (off), inbox retention (90 days), SMS reply window (72 hours), inbound files (media library, 25 MB), SMS download links (72 hours), outgoing webhook (off), retention (messages 90 days, webhook receipts 7 days).
### Sandbox for tests and CI
```js
// config/env/test/plugins.js
const { sandboxConfig } = require('strapi-plugin-magic-messagegate/testing');
module.exports = { 'magic-messagegate': { enabled: true, config: sandboxConfig() } };
```
In sandbox mode no message leaves the server. Test numbers decide the outcome: `+4915550000002` is read, `+4915550000003` is not on WhatsApp (falls back), `+4915550000004` can't receive RCS, `+4915550000005` stays undelivered, `+4915550000007` ends uncertain, `+4915550000008` is an unassigned number; every other number is delivered. `sandbox.simulateInbound({ to, text, buttonPayload, media: { mime, size } })` (or `POST /api/magic-messagegate/sandbox/inbound`) feeds replies and files into your automations, and `drain(strapi)` runs the workers right away. The full table is in [AGENTS.md](https://github.com/Schero94/Magic-MessageGate/blob/main/AGENTS.md#sandbox-tests-and-ci).
## Permissions
Settings → Administration Panel → Roles → Plugins → Magic MessageGate:
| Permission | Allows |
| ------------------------ | -------------------------------------------------------- |
| Accounts: read / manage | see accounts / connect, edit, test and delete them |
| Templates: read / manage | see and preview templates / create, edit and delete them |
| Templates: submit | send WhatsApp templates to Meta for approval |
| Messages: read / send | see messages and timelines / send from the admin |
| Messages: manage | retry, discard, mark as sent |
| Inbox: read | see inbound messages, files and conversations |
| Inbox: manage | mark inbound messages as processed |
| Contacts: read | see contacts, run the free number check |
| Contacts: manage | change consent, link Telegram, erase, run paid lookups |
| Contacts: export | GDPR export of a contact |
| Analytics: read | see analytics |
| Settings: read / update | see / change the settings |
For the Content API, tick the MessageGate actions on the API token. The inbound routes (text and files) are separate actions (`inbound-api`), so a token that only sends cannot read replies.
## Consent and privacy
- Sending needs granted consent for the channel. The exception is an `AUTHENTICATION` template sent with `transactional: true` (login codes).
- An opt-out keyword in an incoming WhatsApp, SMS or Telegram message revokes consent for that channel right away, for every process.
- Phone numbers and Telegram chat IDs are stored encrypted and looked up by a keyed hash. Logs only show a short hash prefix, events show none.
- Inbound text, captions and locations are stored encrypted; inbound files go to the media library. Both are deleted after the inbox retention period.
- Messages and their events are deleted after the retention period; outbound message content is removed as soon as a message is delivered.
- **Contacts → Export** returns everything stored about one person, including inbound messages; **Erase** deletes it, including inbound files.
- `metadata` and `tags` are stored in plain text. Don't put personal data there.
## Security
- Every admin route needs an admin session and a MessageGate permission. The Content API needs an API token.
- Provider secrets are encrypted and never returned by the API; the admin only shows whether a secret is set.
- Webhooks use an unguessable URL per account plus the provider's signature: Meta `X-Hub-Signature-256`, the Telegram secret token, the seven.io signature with timestamp and nonce, the Twilio signature. Repeated deliveries are ignored. Failures answer `401` without detail.
- Template variables are plain text with length limits; control characters are removed and Telegram HTML is escaped.
- MessageGate never fetches a URL from user input. Attachment URLs must be public https URLs (no private, loopback or link-local hosts, no credentials) and are passed to the provider; SMS links to them are redirects. Inbound files are downloaded only from the provider's own hosts, with a size cap while streaming, a type allow-list and a check of the first bytes. The outgoing webhook URL is checked against the same rules before every delivery.
- Signed download links and media URLs carry an HMAC and an expiry; every invalid link gets the same `404`, and downloads are rate limited per IP. Files are served as downloads with `nosniff` and a sandboxing CSP.
- Request bodies, variables (50 per message), metadata keys (20), page sizes and search terms are bounded. Rate limits are counted in the database, so they hold across processes.
- Two runtime dependencies: `zod` and `libphonenumber-js`. 1.1 adds none.
Please report vulnerabilities privately through [GitHub security advisories](https://github.com/Schero94/Magic-MessageGate/security/advisories/new).
## Running several instances
MessageGate keeps its state in the database, so any number of Strapi processes can share it (Railway replicas, pm2 cluster mode, Kubernetes):
- The outbox claims messages with `FOR UPDATE SKIP LOCKED` on PostgreSQL and MySQL 8, and with a conditional update on SQLite, so each message is sent by exactly one process.
- Rate limits, the lookup budget and its cache, webhook de-duplication, inbound messages (unique per provider message id), media download jobs, outgoing webhook deliveries and maintenance jobs use shared database rows, so each event and each download happens once.
- Webhooks can reach any process. No sticky sessions are needed.
The test: 8 processes on one PostgreSQL database behind a round-robin balancer sent 500 messages with 0 duplicates. Status webhooks sent in random order to random processes all ended as `read`, and a STOP received by one process blocked the next send on another ([record](https://github.com/Schero94/Magic-MessageGate/blob/main/docs/acceptance/2026-11-11-cluster.md)).
Strapi creates and changes database tables at startup. For the first deploy, and for updates that change tables, start **one** replica first, then scale up.
## Costs
MessageGate is free (MIT). The providers charge you: Meta per delivered WhatsApp template message ([pricing](https://developers.facebook.com/docs/whatsapp/pricing)), Twilio per RCS message, seven.io or Twilio per SMS, Twilio per line-type lookup ([Lookup pricing](https://www.twilio.com/en-us/user-authentication-identity/pricing/lookup)) and seven.io per HLR check (0.01 EUR on the [seven.io price list](https://www.seven.io/en/prices/)). Lookups are cached for 30 days, and the monthly budget stops them when it is used up. Telegram is free. The sandbox costs nothing.
## FAQ
**Can MessageGate check whether a number has WhatsApp or RCS before sending?**
No. Neither Meta's Cloud API nor Twilio has such a check. MessageGate learns it from the first send and falls back to the next channel. Unofficial WhatsApp checks are not used.
**Does MessageGate send e-mail?**
No. E-mail is an opt-in last step of the chain that hands the message to Magic Mail; it is off by default.
**Why is a message "uncertain"?**
The request reached the provider, but no clear answer came back in time. The provider may or may not have the message, so sending again could deliver it twice. An admin can retry it (after confirming the risk) or mark it as sent.
**Can I send free text on WhatsApp?**
Only within 24 hours after the contact last wrote to you. Outside that window, Meta requires an approved template.
**Do I need Magic Mail?**
No. It is only used for the optional, off-by-default e-mail step of the fallback chain.
**Can I connect my personal WhatsApp number?**
No. Only a WhatsApp Business App number (coexistence) or a new number can be connected through the official API.
## Migrating from Magic WhatsApp
`strapi-plugin-magic-whatsapp` drove WhatsApp Web through the unofficial `baileys` library and a QR session. That breaks WhatsApp's terms and puts numbers at risk of a ban, so it is gone. MessageGate is a new plugin (`magic-messagegate`) with new routes, permissions and tables; the old package was never published to npm. To move over:
1. Remove the old plugin from `package.json` and `config/plugins.js`, and delete its `.whatsapp-auth` folder.
2. Install MessageGate and connect your number through Meta (the Business App number works through coexistence).
3. Recreate your templates and submit the WhatsApp ones to Meta.
Details are in the [changelog](https://github.com/Schero94/Magic-MessageGate/blob/main/CHANGELOG.md).
## For AI agents
[AGENTS.md](https://github.com/Schero94/Magic-MessageGate/blob/main/AGENTS.md) is the exact API contract for coding agents. The docs site also serves [`llms.txt`](https://schero94.github.io/Magic-MessageGate/llms.txt) and [`llms-full.txt`](https://schero94.github.io/Magic-MessageGate/llms-full.txt).
## Contributing
```bash
npm ci
npm run lint && npm run format:check
npm test # unit tests, provider contract tests with local fakes, 8 processes on SQLite
npm run test:pg # 8 processes on PostgreSQL (set MG_TEST_PG_URL)
npm run build && npm run verify
```
Issues and pull requests are welcome at [github.com/Schero94/Magic-MessageGate](https://github.com/Schero94/Magic-MessageGate/issues). See [CONTRIBUTING.md](https://github.com/Schero94/Magic-MessageGate/blob/main/CONTRIBUTING.md) for the checks, the 8-process acceptance run and releases; the design decisions are in [CONCEPT.md](https://github.com/Schero94/Magic-MessageGate/blob/main/CONCEPT.md).
## License
[MIT](https://github.com/Schero94/Magic-MessageGate/blob/main/LICENSE)
---
# AGENTS.md: Magic MessageGate API contract
This file is for AI coding agents (Codex, Claude Code, Cursor, …) and developers who integrate with `strapi-plugin-magic-messagegate`. It is the exact contract of version 1.x (1.1 added RCS, attachments, number checks, inbound messages, dry runs, the sandbox and the outgoing webhook). Everything here matches the code in `server/src`; when in doubt, the code wins and this file is a bug.
Plugin id: `magic-messagegate`. Channels: `whatsapp` (Meta WhatsApp Cloud API), `rcs` (Twilio), `telegram` (Bot API), `sms` (seven.io or Twilio).
The loop: **send → receive → process → automate.** Send with `messages.send`, receive every reply as a `messagegate.message.received` event, read it (`inbound.get`, `inbound.getMedia`, `conversations.history`), answer with `messages.reply`, and mark it done with `inbound.markProcessed`.
## Rules for agents
Do:
- Send through `strapi.plugin('magic-messagegate').service('messages').send(...)` on the server, or `POST /api/magic-messagegate/messages` with a Strapi **API token** from another service.
- Pass an `idempotencyKey` for every send that may be retried by your code (order id, event id). A second call with the same key returns the first message with `duplicate: true` and sends nothing.
- Pass `notAfter` for anything time-bound (login codes, appointment reminders). A message is never sent after it, not even by an admin retry.
- Use approved WhatsApp templates for business-initiated messages. Free text (`text`) only works inside the 24-hour window after the contact's last WhatsApp message.
- Record consent (`POST /consent` or `service('contacts').grantConsent`) when your app collects it. Sending needs `granted` consent for the channel (also for `rcs`) unless the template category is `AUTHENTICATION` and you pass `transactional: true`.
- Switch on `error.details.code`, never on the message text.
- Listen to the `messagegate.*` events on `strapi.eventHub` instead of polling. Do the work after the event (queue it in your app); never block the provider webhook.
- Use `send(input, { dryRun: true })` or `POST /messages` with `"dryRun": true` in tests to see the route and payload without sending.
- Use `providers.mode: 'sandbox'` in app tests and CI (no network, no cost, deterministic outcomes).
- Make inbound workers idempotent with `inbound.markProcessed(id)`: only the first call returns `alreadyProcessed: false`.
Don't:
- Don't call Meta, Telegram, seven.io or Twilio directly for messages that MessageGate should track; statuses, fallback and consent would be bypassed.
- Don't send the same message again yourself after an `uncertain` status. The provider may have delivered it; MessageGate leaves the decision to an admin.
- Don't use the Content API from a browser or with a users-permissions login. It is for servers with an API token (end users are refused unless `contentApi.allowUsersPermissions` is on).
- Don't put personal data in `metadata` or `tags`. They are stored in plain text and shown to admins.
- Don't expect "online", "exists on WhatsApp" or "RCS capable" pre-checks. The official APIs don't offer them (Twilio has no RCS capability lookup); MessageGate learns WhatsApp (error 131026) and RCS (Twilio 63036) from sends.
- Don't log inbound text, captions or files. They are personal data; MessageGate stores them encrypted and deletes them after `inbound.retentionDays`.
- E-mail is never sent by MessageGate itself. The `email` step only hands the message to Magic Mail when the owner turned `fallback.emailEnabled` on (off by default).
## Server API (inside Strapi)
```js
const mg = strapi.plugin('magic-messagegate');
const result = await mg.service('messages').send({
to: '+4915123456789', // or userId (users-permissions id) or contactId
channel: 'auto', // 'auto' | 'whatsapp' | 'rcs' | 'telegram' | 'sms'
template: 'order_shipped', // template key
language: 'de',
variables: { first_name: 'Anna', order_id: 'A-10423' },
attachment: { fileId: 42 }, // optional: media library file, or { url, mimeType }
idempotencyKey: 'order-shipped-A-10423',
notAfter: new Date(Date.now() + 24 * 3600_000),
});
// → { id: 'k3j9…', status: 'queued', channel: 'whatsapp', duplicate: false }
```
| Service | Method | Returns |
| --------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `messages` | `send(input, { source?, dryRun? })` | `{ id, status, channel, duplicate }`; with `dryRun: true` the dry-run result (below) |
| `messages` | `preview(input)` | dry-run result: route, account, rendered payload, errors; nothing is queued or charged |
| `messages` | `reply(inboundId, input, { dryRun? })` | like `send`, on the channel and account of the inbound message |
| `messages` | `get(id)` | message detail (see below) |
| `messages` | `list(query)` | `{ results, pagination }` |
| `messages` | `retry(id, { confirmDuplicateRisk? })` | message detail; `uncertain` messages need `confirmDuplicateRisk: true` |
| `messages` | `cancel(id)` | message detail (status `discarded`) |
| `templates` | `render(key, language, variables, channel)` | `{ templateId, key, language, channel, approvalStatus, preview, payload, sms? }`, nothing is sent |
| `contacts` | `upsert(phone, { userId?, locale? })` | contact DTO (phone masked) |
| `contacts` | `grantConsent(contactId, channel, source?)` | `undefined` |
| `contacts` | `revokeConsent(contactId, channel, source?)` | `undefined` |
| `telegram` | `createLink(contactId, accountId?)` | `{ url, token, expiresInMinutes: 30 }`, `url` is `https://t.me/?start=…` |
| `lookup` | `check(phone, { remote?, hlr?, rcs? })` | lookup result (see below) |
| `lookup` | `capabilities(phone)` | `{ valid, e164, type, active, whatsapp, rcs, telegramLinked, checkedAt }`, never paid |
| `inbound` | `get(id)` | inbound DTO with decrypted text (see below) |
| `inbound` | `list({ page?, pageSize?, channel?, kind?, contactId?, processed?, from?, to? })` | `{ results, pagination }`, newest first |
| `inbound` | `markProcessed(id)` | `{ id, processedAt, alreadyProcessed }` |
| `inbound` | `getMedia(id, { as: 'buffer' \| 'stream' \| 'base64' })` | `{ data, mime, size, filename, caption }`; only when `media.status` is `ready` |
| `inbound` | `createMediaUrl(id, { ttlSeconds? })` | `{ url, expiresAt }`: signed https URL, 30–3600 s (default 300) |
| `inbound` | `onReceived(handler)` | unsubscribe function; same as `strapi.eventHub.on('messagegate.message.received', …)` |
| `inbound` | `onMediaScan(async (file) => 'clean' \| 'infected')` | registers a virus scanner (per process; register it in every process) |
| `conversations` | `history(contactId \| { inboundId }, { limit?, since?, includeMedia? })` | `{ contactId, items }`: inbound and outbound in time order (see below) |
| `sandbox` | `simulateInbound(input)` | inbound DTO; sandbox mode only (`SANDBOX_ONLY` otherwise) |
| `sandbox` | `drain({ maxRounds? })` | runs the send and media workers until nothing is due (sandbox mode only) |
| `sandbox` | `numbers` | the magic test numbers |
### `send` input
| Field | Type | Rules |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `to` | string | phone number, parsed to E.164 with the default country (`DE`); 3–40 chars |
| `userId` | integer | alternative to `to`: users-permissions user linked to a contact |
| `contactId` | string | alternative to `to` |
| `email` | string | used only by the opt-in e-mail fallback (Magic Mail) |
| `channel` | `auto` \| `whatsapp` \| `rcs` \| `telegram` \| `sms` | default `auto` = routing rules, then the default chain (`whatsapp → rcs → sms`) |
| `template` | string `^[a-z][a-z0-9_]{0,119}$` | template key; `template` or `text` is required |
| `language` | string, e.g. `de`, `pt_BR` | picks the template variant |
| `variables` | object, ≤ 50 keys, values string ≤ 1024 / number / boolean | validated against the template's variable definitions |
| `text` | string 1–4096 | free text (WhatsApp only inside the 24-hour window) |
| `buttons` | 1–3 × `{ payload, title }` | only with `text`: WhatsApp reply buttons, Telegram inline keyboard; `payload` `^[A-Za-z0-9_.:-]{1,64}$`, `title` ≤ 20 |
| `attachment` | `{ fileId }` or `{ url, mimeType? }`, optional `filename` | see "Attachments" |
| `idempotencyKey` | string 1–200 | scoped per caller (API token or service) |
| `notAfter` | Date, ISO string with offset, or epoch ms | final deadline; default `defaultNotAfterHours` (24) |
| `transactional` | boolean | with an `AUTHENTICATION` template: no consent needed |
| `tags` | string[] ≤ 10, each ≤ 40 | used by routing rules |
| `accountId` | string | send through this account only |
| `priority` | `high` \| `normal` \| `low` | worker order |
| `metadata` | object ≤ 20 keys | stored, never sent |
Unknown fields are rejected (`INVALID_REQUEST`). `dryRun` is an option (service) or a body field (Content API), not part of the input.
### Channel chain and RCS
`auto` tries the channels of the matching routing rule, else `routing.defaultChain` (new installs: `whatsapp → rcs → sms`; settings saved by 1.0 keep their chain). A channel is skipped when it cannot reach the contact (the codes show up in the dry-run `steps`): no account, no consent, suppressed, WhatsApp window closed, not on WhatsApp (learned 131026), not RCS capable (learned Twilio 63036, trusted for 30 days), not linked (Telegram), attachment not possible. A terminal failure after sending (for example RCS `undelivered` with 63036) runs the next channel once.
RCS goes through a Twilio Messaging Service that holds your approved RCS sender (`messagingServiceSid` on the RCS account). MessageGate sends `To=rcs:+…`, so Twilio does not fall back on its own and MessageGate's chain decides; set `twilioFallback: true` on the account to let Twilio fall back to SMS instead. Plain-text RCS templates (`{ text, mediaUrl? }`) are approved on save; a rich card (`title`, up to 4 `buttons` of type `URL`, `PHONE_NUMBER` or `QUICK_REPLY` with `payload`) becomes a Twilio Content template with **Create on Twilio** (`POST /templates/:id/submit` with a Twilio account) and is sent with `ContentSid` and numbered `ContentVariables` in the stored `variableOrder`.
### Attachments
| Source | Fields | Checks |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| media library | `{ fileId, filename? }` | file exists, MIME allow-list, first bytes match the type (local files), public URL = `publicUrl` + file URL |
| URL | `{ url, mimeType?, filename? }` | `https:` only, no credentials, port 443, no local, private, loopback, link-local or CGNAT host; type from `mimeType` or the extension; they must match |
Allowed types: `image/jpeg`, `image/png`, `application/pdf`, `video/mp4`. How each channel carries the file:
| Channel | Carries | Limit |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| WhatsApp | free text → image, video or document message with caption (≤ 1024); template → header media (needs an IMAGE/VIDEO/DOCUMENT header of that kind) | image 5 MB, video 16 MB, PDF 100 MB |
| RCS | `MediaUrl` (Twilio builds a rich card with the text); not combinable with a Content template | 16 MB |
| Telegram | `sendPhoto` (JPEG/PNG) or `sendDocument` (PDF) by URL with the text as caption (≤ 1024); other files or longer text → signed link | photo 5 MB, PDF 20 MB |
| SMS | a signed, expiring download link appended to the text | – |
A channel that cannot carry the file is skipped (`ATTACHMENT_TOO_LARGE`, `ATTACHMENT_TYPE_NOT_ALLOWED`, `ATTACHMENT_UNSUPPORTED`). Only a reference (file id or URL, name, type) is stored, encrypted; never the file. Signed links look like `https:///api/magic-messagegate/files/..`, are valid `attachments.linkTtlHours` (72) and are rate limited per IP; every invalid, expired or tampered link answers the same `404`. Media-library files on a remote upload provider (S3, …) and URL attachments are answered with a redirect to their public URL; local files are streamed as downloads (`Content-Disposition: attachment`, `nosniff`, sandbox CSP).
WhatsApp media templates: the header's `fileId` is uploaded as the sample with Meta's Resumable Upload API on submit (`example.header_handle`; needs the Meta app id from the account config `appId` or `providers.meta.embeddedSignup.appId`), and it is the default header media at send time; a message `attachment` replaces it.
### Variables in WhatsApp buttons
- **URL buttons:** Meta lets one variable sit at the **end** of an approved URL, for example `https://shop.example/track/{{order_id}}`. MessageGate sends only the value; WhatsApp appends it to the approved URL. The value must be the URL suffix (`A-10423`), never a full URL. Only the first placeholder of a URL button is used.
- **Copy-code buttons:** set `variable` on the button; the value is cut to 15 characters, Meta's limit.
- **Quick-reply buttons:** set a fixed `payload`; it comes back as `buttonPayload` of the inbound message when the customer taps it.
- Body, header and button variables all come from the same `variables` object.
### Dry run
`send(input, { dryRun: true })`, `messages.preview(input)` and `POST /messages` with `"dryRun": true` validate, resolve the route and render the payload of the channel that would be used. Nothing is queued, no contact is created, no provider is called and no paid lookup runs (cached HLR results are used).
```json
{
"dryRun": true,
"valid": true,
"errors": [],
"chain": ["whatsapp", "rcs", "sms"],
"steps": [
{ "channel": "whatsapp", "eligible": false, "code": "NO_CONSENT" },
{ "channel": "rcs", "eligible": true, "attachmentMode": "media" },
{ "channel": "sms", "eligible": true }
],
"channel": "rcs",
"account": { "id": "x8…", "provider": "twilio", "name": "RCS Shop" },
"to": "+491•••89",
"payload": { "kind": "rcs", "text": "Hallo Anna …", "mediaUrl": "https://…" },
"preview": "Hallo Anna …",
"attachment": { "source": "library", "mimeType": "application/pdf", "filename": "invoice.pdf", "size": 12800 }
}
```
`errors` is `[{ code, field? }]` (for example `INVALID_REQUEST` with `field`, `MISSING_VARIABLE`, `NO_CONSENT`, `NUMBER_INACTIVE`); `valid` is false when there are errors. SMS links show as `…/files/`. Secrets never appear.
## Content API (for other services)
Base path `/api/magic-messagegate`. Authenticate with a Strapi API token (`Authorization: Bearer `) that has the MessageGate permissions. Bodies may be wrapped in `{ "data": … }`.
| Method | Path | Body / query | Success |
| ------ | --------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| POST | `/messages` | `send` input, optional `"dryRun": true` | `202 { data: { id, status, channel, duplicate: false } }`, replay `200 … duplicate: true`, dry run `200 { data: dry-run result }` |
| GET | `/messages/:id` | – | `200 { data: { id, status, channel, templateKey, errorCode, sentAt, deliveredAt, readAt, failedAt, timeline, fallbacks } }` |
| POST | `/consent` | `{ phone, channel, status: 'granted'\|'revoked', userId? }` | `200 { data: { contactId, channel, status } }` |
| POST | `/telegram-link` | `{ phone }` | `200 { data: { url, token, expiresInMinutes } }` |
| POST | `/lookup` | `{ phone, remote?, hlr?, rcs? }` | `200 { data: lookup result }` |
| POST | `/capabilities` | `{ phone }` | `200 { data: { valid, e164, type, active, whatsapp, rcs, telegramLinked, checkedAt } }` |
| POST | `/templates/render` | `{ template, channel, language?, variables? }` | `200 { data: { templateId, key, language, channel, approvalStatus, preview, payload, sms? } }` |
| GET | `/inbound` | `page, pageSize, channel, kind, contactId, processed, from, to` | `200 { data: { results: inbound DTO[], pagination } }` |
| GET | `/inbound/:id` | – | `200 { data: inbound DTO }` |
| POST | `/inbound/:id/processed` | – | `200 { data: { id, processedAt, alreadyProcessed } }` |
| GET | `/inbound/:id/media` | `?as=base64` (default: the file as a download) | the file (`Content-Disposition: attachment`, `nosniff`) or `200 { data: { data, mime, size, filename, caption } }` |
| POST | `/inbound/:id/media-url` | `{ ttlSeconds? }` (30–3600) | `200 { data: { url, expiresAt } }` |
| POST | `/inbound/:id/reply` | `text` (+ `buttons`) or `template` + `variables`, `attachment`, `idempotencyKey`, `dryRun` | `202` like `/messages` |
| GET | `/conversations/:contactId` | `limit` (≤ 200), `since`, `includeMedia` | `200 { data: { contactId, items } }` |
| POST | `/sandbox/inbound` | `simulateInbound` input | `201 { data: inbound DTO }`; `403 SANDBOX_ONLY` outside sandbox mode |
| GET | `/files/:token` | – (public, signed) | the file or a redirect; `404` for anything invalid |
The inbound routes (`/inbound…`, `/conversations…`, `/sandbox/inbound`) return message text and files, so they belong to a separate controller (`inbound-api`): a custom API token only gets them when those permissions are ticked, and send-only tokens cannot read replies.
Rate limits (shared across all processes, per token): `rateLimits.sendPerMinute` (120) for `/messages`, `/templates/render` and replies, `rateLimits.lookupPerMinute` (30) for `/lookup` and `/capabilities`, `rateLimits.inboundPerMinute` (300) for the inbound routes, `rateLimits.downloadPerMinute` (60, per IP) for `/files`. Over the limit: `429` with `Retry-After: 60` and code `RATE_LIMITED`.
```bash
curl -X POST https://cms.example.com/api/magic-messagegate/messages \
-H "Authorization: Bearer $STRAPI_API_TOKEN" -H "Content-Type: application/json" \
-d '{"data":{"to":"+4915123456789","template":"order_shipped","language":"de","variables":{"first_name":"Anna","order_id":"A-10423"},"idempotencyKey":"order-shipped-A-10423"}}'
```
Errors use Strapi's error shape:
```json
{
"data": null,
"error": { "status": 409, "name": "ConflictError", "message": "…", "details": { "code": "NO_CONSENT" } }
}
```
## Message detail and statuses
`timeline` is a list of `{ type, code, at }` (epoch ms), `fallbacks` a list of `{ id, channel, status }` for messages created by the fallback chain.
| Status | Meaning | Terminal |
| ----------- | ------------------------------------------------------------------------------------------------ | -------- |
| `queued` | waiting for the worker (also between retries) | no |
| `sent` | the provider accepted it | no |
| `delivered` | the provider reported delivery to the phone | no |
| `read` | the recipient opened it (WhatsApp and RCS, only with read receipts on) | yes |
| `failed` | not delivered (`errorCode`, e.g. `META_131026`, `TWILIO_63036`); the fallback chain may continue | yes |
| `uncertain` | the outcome is unknown (timeout after the request was written); never resent automatically | yes |
| `expired` | `notAfter` passed before it could be sent | yes |
| `discarded` | cancelled by an admin or `cancel(id)` | yes |
Statuses only move forward: a late `delivered` after `read` is ignored. Retries: first try plus up to 3 retries after about 1, 5 and 15 minutes (±20 %), only when the provider provably did not accept the message. Outbound message content is removed once a message is delivered (privacy by design), so `conversations.history` shows the template key instead of the text for delivered messages.
## Lookup result
```json
{
"valid": true,
"e164": "+4915123456789",
"country": "DE",
"type": "MOBILE",
"mobile": true,
"whatsapp": "unknown",
"remote": null,
"rcs": "unknown",
"hlr": {
"ok": true,
"active": true,
"valid": "valid",
"reachable": "reachable",
"ported": "assumed_not_ported",
"roaming": "not_roaming",
"network": "Example Mobile",
"networkType": "mobile",
"checkedAt": 1800000000000
}
}
```
- `whatsapp`: `unknown`, `ok` (a message was delivered) or `unreachable` (Meta reported 131026).
- `remote`: the cached Twilio line-type result when `remote` is on (the default) and the Twilio lookup is configured, otherwise `null`.
- `rcs` (with `rcs: true`): `unknown`, `capable` (an RCS message was delivered) or `not_capable` (Twilio 63036 within the last 30 days).
- `hlr` (with `hlr: true`): seven.io HLR (`GET /api/lookup/hlr`). `active` is `true` (assigned; `reachable`, or `absent` = switched off), `false` (`not_valid` or `bad_number`) or `null` (unknown). Paid; cached for `lookup.cacheDays` (30) in the database; counts against `lookup.monthlyBudget` together with Twilio lookups. `LOOKUP_DISABLED` when HLR is not configured.
- `capabilities(phone)` returns the free summary `{ valid, e164, type, active, whatsapp, rcs, telegramLinked, checkedAt }` from cached results only.
`lookup.blockInactiveNumbers` (off by default) makes every send on a phone channel run the HLR check first (cached; paid only when not cached): a number with `active: false` fails at once with `NUMBER_INACTIVE` and costs no message. A check that fails or a used-up budget never blocks a send.
## Inbound messages
Every message a contact sends (WhatsApp, RCS, Telegram, SMS) is stored once and announced once:
```js
strapi
.plugin('magic-messagegate')
.service('inbound')
.onReceived(async ({ inboundId, kind, buttonPayload }) => {
// queue your own job here; keep the webhook fast
});
```
Inbound DTO (`inbound.get`, `GET /inbound/:id`):
| Field | Type |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | inbound id |
| `channel` | `whatsapp` \| `rcs` \| `telegram` \| `sms` |
| `kind` | `text` \| `button` \| `media` \| `location` \| `other` |
| `text` | decrypted text or caption, or `null` |
| `buttonPayload` | payload of a tapped button (WhatsApp quick reply or reply button, Telegram callback data, RCS suggested reply), or `null` |
| `buttonTitle` | the button's label, or `null` |
| `location` | `{ latitude, longitude, name?, address? }` or `null` |
| `media` | `null` or `{ status, code, fileId, mime, size, filename, caption, duration }` |
| `replyTo` | id of our outbound message it answers (WhatsApp `context.id`, Telegram `reply_to_message`, Twilio `OriginalRepliedMessageSid`; SMS/RCS without a reference: the last message sent to the contact on that channel within `inbound.replyWindowHours`, 72) |
| `contactId`, `contact` | contact id; `{ id, phoneMasked, userId }` |
| `receivedAt`, `processedAt`, `seenAt` | epoch ms or `null` |
Telegram messages are only stored for chats linked to a contact (bots cannot see phone numbers). An inline-keyboard press is answered (`answerCallbackQuery`) so the client stops its spinner.
### Inbound media
`media.status`: `pending` (download queued) → `ready`, or `failed` with `code`; `quarantined` while a registered scanner has not answered `clean`; `skipped` when `inboundMedia.storage` is `none`.
The download worker claims jobs with a lease (one process per file) and downloads only from the provider's own hosts with the account credentials: Meta `GET /{media-id}`, then the CDN URL with the bearer token; Telegram `getFile`, then `api.telegram.org/file/bot…`; Twilio the account's `MediaUrl` on `api.twilio.com` with basic auth and one redirect to Twilio's media hosts without credentials. It retries after 1, 5, 15 and 60 minutes until the provider's window ends (Meta media ids expire after 7 days; Telegram: 24 hours; Twilio: 7 days), and then:
1. stops at `inboundMedia.maxMb` (25) **while streaming** (`MEDIA_TOO_LARGE`),
2. checks the type against `inboundMedia.allowedTypes` (JPEG, PNG and WebP images, PDF, Office documents, plain text, Ogg, MP3, M4A, AAC and AMR audio, MP4 and 3GP video; `MEDIA_TYPE_BLOCKED`),
3. checks the first bytes against the type (`MEDIA_TYPE_MISMATCH`),
4. removes EXIF (GPS, device) from JPEG and `eXIf` chunks from PNG; other formats keep their metadata,
5. runs the scanner registered with `inbound.onMediaScan` (`infected` → `MEDIA_INFECTED`; any other answer keeps the file in quarantine, not stored, and checks again after 5 minutes),
6. stores the file with a safe name in the media library folder **MessageGate inbound** through the upload plugin (local, S3, Cloudinary … all work) and records `fileId`.
Other codes: `MEDIA_EXPIRED` (the provider no longer has it), `MEDIA_HOST_REFUSED` (the provider pointed to a host outside its own), `MEDIA_FETCH_FAILED`, `MEDIA_STORAGE_FAILED`. With the local upload provider, media library files are reachable by their (unguessable) URL like every other upload; use a private bucket provider if that is not acceptable. Files are deleted together with the inbound message (retention, GDPR erasure).
### Access inbound messages and files from your code
1. `onReceived` (the `messagegate.message.received` event) gives you the `inboundId`, `kind` and `buttonPayload`.
2. `inbound.get(inboundId)` returns the decrypted text, button, location and media metadata.
3. For media, wait for `messagegate.media.ready` (or check `media.status`), then call `inbound.getMedia(inboundId, { as: 'buffer' | 'stream' | 'base64' })`, or `inbound.createMediaUrl(inboundId, { ttlSeconds: 300 })` for a service that fetches files by URL. Anyone holding that URL can download the file until it expires; keep the TTL short and do not log it.
4. `conversations.history({ inboundId })` gives the context: inbound and outbound items `{ direction, id, channel, kind, text, buttonPayload, buttonTitle, location, media, status, replyTo, at, templateKey }`.
5. Answer with `messages.reply(inboundId, { text })` (WhatsApp: only within 24 hours of the customer's last message, otherwise `WINDOW_CLOSED`; use `{ template, variables }`), then call `inbound.markProcessed(inboundId)`.
The data can be passed to any processing of your own; MessageGate does not process it further. Check consent and your privacy notice before you forward message text or files to third parties.
## Sandbox (tests and CI)
```js
// config/env/test/plugins.js
const { sandboxConfig } = require('strapi-plugin-magic-messagegate/testing');
module.exports = {
'magic-messagegate': { enabled: true, config: sandboxConfig({ encryptionKey: 'test-key-at-least-16' }) },
};
```
`providers.mode: 'sandbox'` replaces every provider with an in-process fake: no network, no cost. Accounts still need format-valid credentials. Each send is accepted and its statuses are applied at once through the normal webhook path, decided by the recipient:
| `SANDBOX_NUMBERS.` | Number | Outcome |
| ------------------ | ---------------- | ------------------------------------------------------------------- |
| `delivered` | `+4915550000001` | delivered (also every number not listed here) |
| `read` | `+4915550000002` | delivered, then read (WhatsApp and RCS) |
| `notOnWhatsApp` | `+4915550000003` | WhatsApp fails `META_131026`, the next channel delivers |
| `rcsNotCapable` | `+4915550000004` | RCS fails `TWILIO_63036`, the next channel delivers |
| `undelivered` | `+4915550000005` | accepted, then failed on every channel |
| `rejected` | `+4915550000006` | refused at send time (`SANDBOX_REJECTED`) |
| `uncertain` | `+4915550000007` | timeout after the request was written (`uncertain`) |
| `inactive` | `+4915550000008` | HLR `active: false` (`NUMBER_INACTIVE` with `blockInactiveNumbers`) |
Telegram sends end as `sent`. Templates submitted to Meta or Twilio are approved at once. `sandbox.simulateInbound({ to | contactId, channel?, text?, buttonPayload?, buttonTitle?, replyTo?, location?, media?: { mime, size?, filename?, caption?, duration?, expired?, mismatch? }, providerMessageId? })` stores an inbound message (the same `providerMessageId` twice returns `{ duplicate: true }`) and generates a synthetic file of the given type and size for the media path. `strapi-plugin-magic-messagegate/testing` exports `SANDBOX_NUMBERS`, `sandboxConfig(extra)`, `drain(strapi)` and `signDelivery(secret, timestamp, body)`. A warning is logged at startup in sandbox mode.
## Outgoing webhook
Settings → Outgoing webhook: an https URL (public host, no redirects; checked again before every delivery) and the events to forward: `message.received`, `message.status` (sent, delivered, read, failed, uncertain, expired), `media.ready`, `media.failed`. **Create signing secret** shows the secret once.
Each delivery is a POST with the JSON body `{ id, event, data, at }` (`data` is the event payload: ids, channel, status, codes; never phone numbers or text) and the headers `X-MessageGate-Event`, `X-MessageGate-Delivery`, `X-MessageGate-Timestamp` (unix seconds) and `X-MessageGate-Signature: v1=.")>`. A `2xx` answer ends it; otherwise it is retried after 1, 5 and 15 minutes, 1 and 6 hours (6 tries). Deliveries are rows claimed with a lease, so each one is sent by one process. Settings changes reach every process within about 3 seconds; events in that time use the previous settings. Verify like this:
```js
const crypto = require('node:crypto');
function verifyMessageGate(rawBody, headers, secret, toleranceSeconds = 300) {
const timestamp = headers['x-messagegate-timestamp'];
const signature = String(headers['x-messagegate-signature'] || '');
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
const expected = `v1=${crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`;
return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```
Use the delivery id to ignore repeats.
## Events (`strapi.eventHub`)
No phone numbers, names or message text in any payload. Every event is emitted by exactly one process.
| Event | Payload |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `messagegate.message.queued` | `{ messageId, channel, templateKey, status, code?, at }` |
| `messagegate.message.sent` | same |
| `messagegate.message.delivered` | same |
| `messagegate.message.read` | same |
| `messagegate.message.failed` | same, `code` set |
| `messagegate.message.uncertain` | same, `code` set |
| `messagegate.message.expired` | same, `code: 'DEADLINE_PASSED'` |
| `messagegate.message.discarded` | same |
| `messagegate.message.fallback` | `{ messageId, channel, templateKey, status: 'fallback', code, at }` (`channel` = next channel) |
| `messagegate.message.received` | `{ inboundId, contactId, channel, replyTo, kind, buttonPayload?, media?: { status }, at }` |
| `messagegate.media.ready` | `{ inboundId, fileId, mime, size, at }` (`fileId` is the media library id) |
| `messagegate.media.failed` | `{ inboundId, code, at }` |
| `messagegate.contact.opted-out` | `{ channel, at }` |
| `messagegate.contact.unreachable` | `{ channel: 'whatsapp', at }` |
| `messagegate.template.status-changed` | template id, key, language, new status |
```js
strapi.eventHub.on('messagegate.message.read', ({ messageId, templateKey }) => {
/* … */
});
```
## Error codes
| Code | HTTP | When |
| ----------------------------- | ---- | ------------------------------------------------------------------------------------ |
| `INVALID_REQUEST` | 400 | body does not match the schema |
| `INVALID_PHONE` | 400 | not a valid mobile number |
| `MISSING_VARIABLE` | 400 | a required template variable is missing (`details.field`) |
| `INVALID_VARIABLE` | 400 | a variable is too long or unknown, or the rendered Telegram text is too long |
| `CONFIG_INVALID` | 400 | account, template or settings configuration is invalid (`details.field`) |
| `ATTACHMENT_TYPE_NOT_ALLOWED` | 400 | the file type is not on the allow-list |
| `ATTACHMENT_TYPE_MISMATCH` | 400 | the bytes, name or declared type do not match |
| `ATTACHMENT_URL_INVALID` | 400 | not a public `https` URL (`details.reason`), or no `publicUrl` for a local file |
| `ATTACHMENT_TOO_LARGE` | 400 | larger than every channel in the chain allows |
| `WEBHOOK_URL_INVALID` | 400 | the outgoing webhook URL is not public `https` |
| `INVALID_SIGNATURE` | 401 | webhook signature check failed |
| `FORBIDDEN` | 403 | Content API without an API token, or a paid lookup without `contacts.manage` |
| `SANDBOX_ONLY` | 403 | sandbox route or service outside `providers.mode: 'sandbox'` |
| `NOT_FOUND` | 404 | unknown message, inbound message, contact, template or account |
| `UNKNOWN_TEMPLATE` | 404 | no active template with this key for the channel |
| `ATTACHMENT_NOT_FOUND` | 404 | the media library file does not exist |
| `TEMPLATE_NOT_APPROVED` | 409 | WhatsApp template not approved by Meta yet, or RCS card not created on Twilio |
| `NO_CONSENT` | 409 | no granted consent for the channel |
| `SUPPRESSED` | 409 | contact suppressed (opted out, blocked the bot, not on WhatsApp) |
| `WINDOW_CLOSED` | 409 | free text outside the 24-hour WhatsApp window (use a template) |
| `NO_ACCOUNT` | 409 | no active account for the channel |
| `NO_ROUTE` | 409 | no channel in the chain can reach the contact |
| `NOT_LINKED` | 409 | contact has not linked Telegram |
| `RCS_NOT_CAPABLE` | 409 | the number cannot receive RCS (learned from Twilio 63036) |
| `NUMBER_INACTIVE` | 409 | HLR says the number is not assigned (`lookup.blockInactiveNumbers`) |
| `ATTACHMENT_UNSUPPORTED` | 409 | no channel in the chain can carry the attachment |
| `MEDIA_NOT_READY` | 409 | inbound file pending, quarantined or failed (`details.status`, `details.code`) |
| `MEDIA_NOT_STORED` | 409 | inbound files are not stored (`inboundMedia.storage: 'none'`) |
| `DEADLINE_PASSED` | 409 | `notAfter` has passed |
| `STATE_CHANGED` | 409 | the message changed meanwhile (retry/discard race) |
| `CONFIRMATION_REQUIRED` | 409 | retrying an `uncertain` message without `confirmDuplicateRisk` |
| `PAYLOAD_PURGED` | 409 | the message content was already removed by retention |
| `LOOKUP_DISABLED` | 409 | paid lookup (Twilio or HLR) not configured |
| `EMBEDDED_SIGNUP_DISABLED` | 409 | Meta Embedded Signup not configured on the server |
| `RATE_LIMITED` | 429 | too many requests |
| `LOOKUP_BUDGET_EXCEEDED` | 429 | monthly lookup budget used up |
| `PROVIDER_ERROR` | 502 | the provider rejected an admin action (template submit, sample upload, account test) |
Provider error codes in `errorCode` and timelines are prefixed: `META_131026`, `TG_403`, `SEVEN_…`, `TWILIO_63036`, plus `TIMEOUT`, `LEASE_EXPIRED_DURING_SEND`, `DEADLINE_PASSED`, `SANDBOX_REJECTED`. Inbound media codes are listed under "Inbound media".
## Webhooks (configured by the owner, not called by apps)
`GET|POST /api/magic-messagegate/webhooks/:provider/:path`, where `:path` is a random id per account shown in the admin (Meta app-level URL: `/webhooks/meta/app`). Every POST must carry the provider signature (`X-Hub-Signature-256`, `X-Telegram-Bot-Api-Secret-Token`, seven.io `X-Signature`, `X-Twilio-Signature`); otherwise `401` without detail. Events are deduplicated (inbound messages by provider message id), and Meta retries for up to 36 hours. Telegram webhooks are registered for `message` and `callback_query` updates; run **Test** once on an existing Telegram account after updating to 1.1 so button presses arrive.