Parrot-messenger NPM

Parrot Messenger

Features

Parrot Messenger is a messaging library that can normalize the APIs for different messaging transports. In its current iteration it supports 3 types of transport classes:

Email
SMS
Call

Email Services

AWS SES
Mailchimp (Mandrill)
Mailgun
Sendgrid
SMTP

SMS Services

Twilio
Mailjet

Call Services

Twilio

Installing

Using npm:

$ npm install parrot-messenger

Using bower:

$ bower install parrot-messenger

Using yarn:

$ yarn add parrot-messenger

Initialization

Parrot needs to be initialized with the transports that it will be using before being used.

// ES6
import Parrot from 'parrot-messenger';

// CommonJS
const { Parrot } = require('parrot-messenger');

const parrot = new Parrot({
  transports: [
    // List of transports settings enabled
    mailgun,
    mailchimp,
    ses,
    sendgrid,
    mailjetEmail,
    mailjetSMS,
    twilioSMS,
    twilioCall,
    smtp,
  ],
});

The parrot instance receives an array of transports with the settings for each transport. Each transport will have slightly different settings, particularly around the authentication for each. Example configurations are available in the examples.js file.

Settings

Each transport has a defaults object where you can define default parameters for all messages generated by that transport. So for example you can define a default from value for every message.

This is a sample object for AWS SES transport along with its default values:

const ses = {
  name: 'ses',
  settings: {
    auth: {
      region: '',
      credentials: {
        secretAccessKey: '',
        accessKeyId: '',
      },
    },
    defaults: {
      from: 'me@parrotmessenger.com',
    },
  },
};

API

Parrot Messenger works with a simple send service and a templating, here we'll describe the usage for the send method. The send method receives 2 parameters, both being objects. The first parameter is the parameters for the object that we want to send and the second one is the settings for the transport we want to use.

Example API call:

const email = {
  to: 'john@doe.com',
  subject: 'Sample Message',
  html: 'Hey Joe, nice talking to you!'
};

const transport = { 
  class: 'email', 
  name: 'ses'
};

parrot.send(email, transport);

Templates

We can also use and register templates when using Parrot Messenger, so we can pre-define a set of messages we will be using. We use a templating language (Handlebars) to replace values inside the template before being sent.

Example Template Registration & Usage

// Register a template, notice the ussage of {{name}}
// this value will be replaced
parrot.templates.register({
  name: 'Sample Template',
  html: '<p>Hey there {{name}}!!</p>',
});

const messageData = {
  to: 'john@doe.com',
  subject: 'Hey there!',
};

const transport = {
  class: 'email', 
  name: 'ses'
};

// Send an email using this template
parrot.templates.send(
  'Sample Template',
  messageData,
  // Sample Data for Template
  { name: 'User' },
  // Transport Settings
  // Available classes email, sms & call
  // Available transports per Class:
  // Email: 'ses', 'mailgun', 'mailjetEmail', 'mailchimp', 'smtp'
  // SMS: 'twilioSMS', 'mailjetSMS'
  // Call: 'twilioCall'
  transport
);

Async Templates

If you need to get the HTML template from an API service prior to senting a template you can do this as well. Parrot Messenger will use Axios to make an API request and fetch the necessary data, and it can be mapped from the response.

Example Async Template

// Register template
parrot.templates.register({
  name: 'Async Template',
  // Request is a standard Axios type object
  // with an additional resolve parameter
  // that resolves the response of the object
  // API reference for Axios:
  // https://github.com/axios/axios#axios-api
  request: {
    method: 'GET',
    url: 'https://reqres.in/api/unknown/2',
    data: {},
    headers: {},
    // Path to string we want to use in the request's response
    resolve: 'support.text',
  },
});


const messageData = {
  to: 'john@doe.com',
  subject: 'Hey there!',
};

const transport = {
  class: 'email',
  name: 'ses'
};

// Send an email using this template
parrot.templates.send(
  'Async Template',
  messageData,
  // Sample Data for Template
  { name: 'User' },
  // Transport Settings
  transport
);

Who are we

We are the development partner of choice for several different sized companies who need a team that delivers fast & scalable code understanding users needs and commercial scope.