Hermes Messenger #

This plugin gives the application the ability to send various types of messages (SMS, email, or anything a custom provider can reach) using external providers.

Built-in providers, registered by default:

The providerId is the value to pass in the providerId argument of every account action and the key of the routes. The displayName is a label for user interfaces. Both are returned by hermes:listProviders. Accounts follow the same pattern: an accountId used in arguments and routes, and an optional displayName.

Coming from version 1? Read the Migration guide.

Concepts #

• Provider: an integration with an external messaging service, implemented by extending BaseProvider<T>. A provider declares its capabilities, the recipient types it accepts and three JSON Schemas.

• Account: a set of credentials registered on a provider under a name. Several accounts can coexist on the same provider (e.g. one per customer). Accounts are kept in memory and synchronized across cluster nodes.

• Recipient type: a named JSON Schema describing one recipient string. Recipients are always plain strings; delivery options such as cc or bcc are provider params. Recipient types are shared between providers through a registry, see hermes:listRecipientTypes. Three are built in:

  Name	Format	Audiences
  email	string, format: "email"	human
  phoneNumber	string, E.164 pattern	human
  uri	string, format: "uri"	technical

• Audience: each recipient type lists the audiences it is meant for. human recipients designate a person (email, phone number), technical ones a resource (webhook URI, broker topic, bucket). listRecipientTypes, listProviders and listAccounts accept an audience argument (one value or an array), so an application can offer only human oriented channels when editing a user's contacts.

• Capabilities: what a provider can carry in a message, as an array of strings. Well-known values: text (short plain text), html (rich content), json (structured payload), file (attachments or file transfer). Used to filter providers in listProviders with the capability argument.

• JSON Schemas: accountParamsSchema (account credentials for addAccount), messageContentSchema (the content object of sendMessage), messageAdditionalParamsSchema (the params object of sendMessage). They are returned by listProviders so clients can generate forms dynamically.

API #

The plugin exposes a single hermes controller. Account and message actions take the providerId and accountId arguments and work the same way for every provider:

The sendMessage body always has the same three parts:

{
  "recipients": [ /* strings, each matching one of the provider's recipient types */ ],
  "content":    { /* matches the provider's messageContentSchema */ },
  "params":     { /* optional, matches the provider's messageAdditionalParamsSchema */ }
}

Per-provider examples: SMTP, Sendgrid, Twilio, SMS Envoi.

Accounts Management #

Each provider supports multiple named accounts with different credentials. The following API actions manage accounts:

• hermes:addAccount
• hermes:removeAccount
• hermes:listAccounts (all providers, or one with the providerId argument)

Register an account at startup #

Accounts can be added programmatically once the application has started, using getProvider(providerId).addAccount(accountId, params, displayName?). params must match the provider's accountParamsSchema.

import { HermesMessengerPlugin } from "kuzzle-plugin-hermes-messenger";

const hermesMessengerPlugin = new HermesMessengerPlugin();
app.plugin.use(hermesMessengerPlugin);

app
  .start()
  .then(() => {
    hermesMessengerPlugin.getProvider("smtp").addAccount("common", {
      host_name: "smtp.example.com",
      port: 587,
      user: "user@example.com",
      password: "secret",
      default_sender: "no-reply@example.com",
    });

    hermesMessengerPlugin.getProvider("twilio").addAccount("common", {
      account_sid: "ACxxxxxxxx",
      auth_token: "secret",
      default_sender: "+33600000000",
    });
  })
  .catch(console.error);

Register a custom provider #

Custom providers and custom recipient types must be registered before the application starts:

import { HermesMessengerPlugin } from "kuzzle-plugin-hermes-messenger";
import { MyCustomProvider } from "./providers/MyCustomProvider";

const hermesMessengerPlugin = new HermesMessengerPlugin();
hermesMessengerPlugin.registerProvider("my-provider", new MyCustomProvider());
app.plugin.use(hermesMessengerPlugin);

See the Custom Provider guide for details on implementing your own provider and recipient types.