NotificaMeHub SDK for Node.js

This SDK for Node.js was created based on the NotificaMe API.

Table of Contents

• Changelog
• Features
• Prerequisites
• Installation
• Basic Usage
• Getting Started
  • Sending your first message
  • Sending a batch
  • Subscribe for messages
  • Subscribe for message status
  • Receiving message events and message status events
  • Getting message reports
  • Getting flow reports
  • Listing your templates
• Contributing
• License

1.1.0

• Changed
  • API endpoint to v1

Features

• [x] Text message content
• [x] File message content
• [x] Location message content
• [x] Contacts message content
• [x] Template message content
• [x] Email message content
• [x] Replyable text message content
• [x] Subscription handling

Prerequisites

• Sign up for a NotificaMe Account
• Node.js
• Generate an API token in the NotificaMe API console
• Use you account's User ID as the sender identifier when sending any message. You can find it at the NotificaMe Platform

Installation

npm install notificamehubsdk

Basic Usage

// ES5
const { Cliente } = require('notificamehubsdk');

// ES6 or Typescript
import * as Ciente from 'notificamehubsdk';

// Initialization with your API token (x-api-token)
const client = new Client('YOUR_API_TOKEN');

// Choosing the channel
const whatsapp = client.setChannel('whatsapp');

// Creating a text content
const content = new TextContent('some text message here');

// ES6
whatsapp.sendMessage('sender-identifier', 'recipient-identifier', content)
.then(response => {
  // do something here
})
.catch(error => {
  // handle error here
});

// ES8 or Typescript. NodeJS 7.6.0 or higher
try {
  const response = await whatsapp.sendMessage('sender-identifier', 'recipient-identifier', content);
  // do something here
} catch (error) {
  // handle error here
}

Getting Started

Examples not listed on this section can be found here.

Sending your first message

The content types that can be sent are:

| Name | Description | |-----------------|--------------------------------------------------| | TextContent | Used to send text messages to your customer. | | FileContent | Used to send file messages to your customer. | | LocationContent | Used to send location messages to your customer. | | ContactsContent | Used to send contacts messages to your customer. | | TemplateContent | Used to send template messages to your customer. | | EmailContent | Used to send e-mail messages to your customer. | | ReplyableTextContent | Used to send replyable text messages to your customer.

The channels that can be used to send the content are:

| Channel | TextContent | FileContent | LocationContent | ContactsContent | TemplateContent | EmailContent | CardContent | CarouselContent | ReplyableTextContent | |----------| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | SMS | X | | | | X | | | | | | RCS | X | X | | | X | | X | X | X | | WhatsApp | X | X | X | X | X | | | | | | Facebook | X | X | | | | | X | X | X | | Instagram| X | X | | | | | X | X | X | | Email | | | | | | X | | | | | GBM | X | X | | | | | X | X | X | | Telegram | X | X | | | | |X | | X |

Use the sendMessage method to messages to your customers.

// Text message using the SMS channel
const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const sms = client.setChannel('sms');
const content = new TextContent('some text message');
const response = await sms.sendMessage('sender-identifier', 'recipient-identifier', content);

The response can be an IMessage object when successful or an IError object when an error occurs.

Subscribe for messages

Use the createSubscription method to create a MessageSubscription object for message subscriptions.

const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const subscription = new MessageSubscription({
  url: 'https://your-webhook.company.com'
},
{
  channel: 'YOUR_API_CHANNEL'
});
const response = await client.createSubscription(subscription);

The response can be an ISubscription object when successful or an IError object on errors.

Subscribe for message status

Use the createSubscription method to create a MessageStatusSubscription object for message status subscriptions.

const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const subscription = new MessageStatusSubscription({
  url: 'https://your-webhook.company.com'
},
{
  channel: 'YOUR_API_CHANNEL'
});
const response = await client.createSubscription(subscription);

The response can be an ISubscription object when successful or an IError object when an error occurs.

Receiving message events and message status events

Use the WebhookController class to create your webhook so you can receive message events and message status events. The default port is 3000.

If you inform the client, url, and channel fields, a subscription will be created, unless a subscription matching these configuration already exists.

In the messageEventHandler field you will receive the message events and in the messageStatusEventHandler field you will receive the message status events.

const { Client, WebhookController } = require('notificamehubsdk');
const client = new Client(process.env.HUB_API_TOKEN);
const webhook = new WebhookController({
  messageEventHandler: (messageEvent) => {
    console.log('Message event:', messageEvent);
  },
  messageStatusEventHandler: (messageStatusEvent) => {
    console.log('Message status event:', messageStatusEvent);
  },
  client,
  url: 'https://my-webhook.company.com',
  channel: 'YOUR_API_CHANNEL',
});
webhook.init();

To receive events running the example on your machine, we suggest ngrok.

Getting message reports

To get information on how many messages you've sent or have received during a period of time, use the getEntries method to list IReportMessagesEntry objects as shown below.

const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const reportClient = client.getMessagesReportClient();
const response = await reportClient.getEntries({
  startDate: '2020-01-10',
  endDate: '2020-01-15',
});

The response can be an array of IReportMessagesEntry objects when successful or an IError object when an error occurs.

Getting flow reports

In order to get information about the current state of sessions (executions) of flows in a period of time, use the getEntries method to list IReportFlowEntry objects as shown below.

const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const reportClient = client.getFlowReportClient();
const response = await reportClient.getEntries({ startDate: '2020-01-10' });

The response can be an array of IReportFlowEntry objects when successful or an IError object when an error occurs.

Listing your templates

You can execute CRUD operations on templates. For example, use the listTemplates method to list an ITemplate object.

const { Client } = require('notificamehubsdk');
const client = new Client('YOUR_API_TOKEN');
const response = await client.listTemplates();

The response will be an array of ITemplate object.

Contributing

Pull requests are always welcome!

Please consult the Contributors' Guide for more information on contributing.

License

MIT