messaging

Outbound messaging (SMS, MMS, WhatsApp, etc.) for Gingee apps using a provider adapter pattern (similar to `db`, `cache`, `email`, and `ai`). Configuration (single config, no named profiles): - Optional server defaults: `gingee.json` → `messaging` - Optional app config: `app.json` → `messaging` (overrides server for that app) - Runtime override: module:messaging.sendWithConfig merges on top for one send only - Twilio WhatsApp: set message `channel: 'whatsapp'` (optional config `whatsapp_from`); use `contentSid` / `contentVariables` for approved templates Providers (v1): `mock` / `console` (log only), `twilio` (Twilio Programmable Messaging — SMS/MMS/WhatsApp) IMPORTANT: Requires explicit permission to use the module (`messaging`). See docs/permissions-guide for more details.
Description:
  • Outbound messaging (SMS, MMS, WhatsApp, etc.) for Gingee apps using a provider adapter pattern (similar to `db`, `cache`, `email`, and `ai`). Configuration (single config, no named profiles): - Optional server defaults: `gingee.json` → `messaging` - Optional app config: `app.json` → `messaging` (overrides server for that app) - Runtime override: module:messaging.sendWithConfig merges on top for one send only - Twilio WhatsApp: set message `channel: 'whatsapp'` (optional config `whatsapp_from`); use `contentSid` / `contentVariables` for approved templates Providers (v1): `mock` / `console` (log only), `twilio` (Twilio Programmable Messaging — SMS/MMS/WhatsApp) IMPORTANT: Requires explicit permission to use the module (`messaging`). See docs/permissions-guide for more details.

Members

(inner, constant) messagingInstances :Map.<string, {adapter: object, config: object}>

Type:
  • Map.<string, {adapter: object, config: object}>

(inner) serverMessagingConfig :object|null

Type:
  • object | null

Methods

(static) send(message) → {Promise.<object>}

Description:
  • Sends a message using the app's resolved config (app.json overrides gingee.json).
Example
const messaging = require('messaging');
await messaging.send({
  to: '+1234567890',
  body: 'Your verification code is 123456.'
});
// WhatsApp freeform (within 24h session) or Content Template:
await messaging.send({
  channel: 'whatsapp',
  to: '+1234567890',
  contentSid: 'HXxxxxxxxx',
  contentVariables: { '1': 'Ada' }
});
Parameters:
Name Type Description
message object Outbound message.
Properties
Name Type Attributes Default Description
to string | Array.<string> Recipient phone number(s) (e.g. '+1234567890').
body string <optional>
 Text body of the message (can also use message.text).
text string <optional>
 Plain text body alias.
channel string <optional>
 'sms' `'sms'` (default; also `'mms'`) or `'whatsapp'`.
from string <optional>
 Override default sender number for this message only.
messagingServiceSid string <optional>
 Twilio Messaging Service SID override.
mediaUrl string | Array.<string> <optional>
 URL(s) for MMS / WhatsApp media attachments.
contentSid string <optional>
 Twilio Content Template SID (WhatsApp / rich templates).
contentVariables object | string <optional>
 Template variables object (or JSON string).
statusCallback string <optional>
 Webhook callback URL for delivery status updates.
Returns:
Result with messageId, provider, status, etc.
Type
Promise.<object>

(static) sendWithConfig(configOverride, message) → {Promise.<object>}

Description:
  • Sends a single message using a runtime config that overrides both server and app.json settings for this transaction only. Does not persist or change the app's default adapter.
Example
const messaging = require('messaging');
await messaging.sendWithConfig(
  { type: 'twilio', account_sid: 'ACxxx', auth_token: 'auth_xxx', from: '+19876543210' },
  { to: '+1234567890', body: 'One-off notification' }
);
Parameters:
Name Type Description
configOverride object Partial or full messaging config (type, account_sid, auth_token, from, etc.).
message object Same shape as module:messaging.send.
Returns:
Result with messageId, provider, status, etc.
Type
Promise.<object>