Layer API for node.js

A Node.js library, which provides a wrapper for the Layer Platform API.

The Layer Platform API is designed to empower developers to automate, extend, and integrate functionality provided by the Layer platform with other services and applications. For more on this see our blog post.

This library supports requests from your servers only.

Documentation

You can find full documentation on Platform API at developer.layer.com/docs/platform.

Installation

npm install layer-api

Simple example

var LayerAPI = require('layer-api');

// Initialize by providing your Layer credentials
var layer = new LayerAPI({
  token: API_TOKEN,
  appId: APP_ID
});

// Create a Conversation
layer.conversations.create({participants: ['abcd']}, function(err, res) {
  var cid = res.body.id;

  // Send a Message
  layer.messages.sendTextFromUser(cid, 'abcd', 'Hello, World!', function(err, res) {
    console.log(err || res.body);
  });
});

Initialization

To use this library you need to create a new instance of the layer-api module by passing config object to a constructor.

new LayerAPI(config)

Layer API constructor is initialized with the following configuration values:

• token - Layer Platform API token which can be obtained from Developer Dashboard
• appId - Layer application ID

Optional values:

• version - API version to use (default: 1.0)
• timeout - Request timeout in milliseconds (default: 10000 milliseconds)
• agent - Instance of https.Agent to use HTTPS KeepAlive
• agentOptions - Or use Agent options hash directly
• debug - Enable debugging (default: false)

Conversations

Conversations coordinate messaging within Layer and can contain up to 25 participants. All Messages sent are sent within the context of a conversation.

conversations.create(payload, [callback])

Create a new Conversation by providing paylod. Payload should contain at least participants array. Optional properties are metadata object and distinct boolean.

Arguments

• payload - Payload object
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

layer.conversations.create({participants: ['abcd']}, function(err, res) {
  if (err) return console.error(err);

  // conversation ID
  var cid = res.body.id;
});

conversations.createDedupe(uuid, payload, [callback])

Same as create conversation above but including de-duplicating UUID value.

---

conversations.get(cid, callback)

Retrieve an existing Conversation by providing conversation ID. Response body will result in conversation object representation.

Arguments

• cid - Conversation ID
• callback(err, res) - Callback function returns an error and response objects

Examples

layer.conversations.get(cid, function(err, res) {
  if (err) return console.error(err);

  // conversation data
  var conversation = res.body;
});

---

conversations.getFromUser(uid, cid, callback)

Retrieve an existing Conversation by providing user ID and conversation ID. Response body will result in conversation object representation.

Arguments

• uid - User ID
• cid - Conversation ID
• callback(err, res) - Callback function returns an error and response objects

Examples

layer.conversations.getFromUser(uid, cid, function(err, res) {
  if (err) return console.error(err);

  // conversation data
  var conversation = res.body;
});

---

conversations.getAllFromUser(uid, [params], callback)

Retrieve all Conversations by providing user ID. Response body will result in an array of conversation objects.

Arguments

• uid - User ID
• params - Optional Query parameters can contain page_size, from_id and sort_by
• callback(err, res) - Callback function returns an error and response objects

Examples

var params = {
  page_size: 50,
  from_id: cid,
  sort_by: 'last_message' // `created_at` or `last_message`
};
layer.conversations.getAllFromUser(uid, params, function(err, res) {
  if (err) return console.error(err);

  // conversation data
  var conversation = res.body;
});

---

conversations.setMetadataProperties(cid, properties, [callback])

Set metadata on an existing Conversation by providing conversation ID and properties object.

Arguments

• cid - Conversation ID
• properties - Metadata properties object
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

var properties = {
  foo: 'bar'
};
layer.conversations.setMetadataProperties(cid, properties, function(err, res) {
  if (err) return console.error(err);
});

---

conversations.deleteMetadataProperties(cid, properties, [callback])

[Delete metadata]((https://developer.layer.com/docs/platform#set-amp-delete-metadata) on an existing Conversation by providing conversation ID and properties object.

Arguments

• cid - Conversation ID
• properties - Properties object
• callback(err, res) - Optional Callback function returns an error and response objects

---

conversations.edit(cid, operations, [callback])

Edit an existing Conversation by providing conversation ID and one or more operations as described by the Layer Patch format.

Arguments

• cid - Conversation ID
• operations - Layer Patch operations array
• callback(err, res) - Optional Callback function returns an error and response objects

---

conversations.addParticipants(cid, participants, [callback])

Add participants to an existing Conversation by providing conversation ID and array of participants.

Arguments

• cid - Conversation ID
• participants - Array of participants
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

var participants = ['user1'];
layer.conversations.addParticipants(cid, participants, function(err, res) {
  if (err) return console.error(err);
});

---

conversations.removeParticipants(cid, participants, [callback])

Remove participants of an existing Conversation by providing conversation ID and array of participants.

Arguments

• cid - Conversation ID
• participants - Array of participants
• callback(err, res) - Optional Callback function returns an error and response objects

---

conversations.replaceParticipants(cid, participants, [callback])

Replace all participants of an existing Conversation by providing conversation ID and array of participants.

Arguments

• cid - Conversation ID
• participants - Array of participants
• callback(err, res) - Optional Callback function returns an error and response objects

---

conversations.delete(cid, [callback])

Delete an existing Conversation by providing conversation ID.

Arguments

• cid - Conversation ID
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

layer.conversations.delete(cid, function(err, res) {
  if (err) return console.error(err);
});

Messages

Messages can be made up of one or many individual pieces of content.

• Message sender can be specified by user_id or name, but not both.
• Message parts are the atomic object in the Layer universe. They represent the individual pieces of content embedded within a message.
• Message notification object represents push notification payload.

messages.send(cid, payload, [callback])

Send a Message by providing conversation ID and payload.

Arguments

• cid - Conversation ID
• payload - Message payload containing sender and parts data
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

var payload = {
  sender: {
    user_id: 'abcd'
  },
  parts: [
    {
      body: 'Hello, World!',
      mime_type: 'text/plain'
    }
  ]
};
layer.messages.send(cid, payload, function(err, res) {
  if (err) return console.error(err);

  // message ID
  var messageId = res.body.id;
});

---

messages.sendDedupe(uuid, cid, payload, [callback])

Same as send a message above but including de-duplicating UUID value.

---

messages.sendTextFromUser(cid, userId, text, [callback])

Shorthand method for sending a plain text Message by providing userId and text.

Arguments

• cid - Conversation ID
• userId - User ID of the participant that this message will appear to be from
• text - Text or base64 encoded data for your message
• callback(err, res) - Optional Callback function returns an error and response objects

---

messages.sendTextFromName(cid, name, text, [callback])

Shorthand method for sending a plain text Message by providing name and text.

Arguments

• cid - Conversation ID
• name - Arbitrary string naming the service that this message will appear to be from
• text - Text or base64 encoded data for your message
• callback(err, res) - Optional Callback function returns an error and response objects

messages.getAll(cid, [params], callback)

Retrieve all messages in a conversation by providing cid. Response body will result in array of messages.

Arguments

• cid - Conversation ID
• params - Optional Query parameters can contain page_size, from_id and sort_by
• callback(err, res) - Callback function returns an error and response objects

Examples

var params = {
  page_size: 50,
  from_id: messageId,
  sort_by: 'last_message' // `created_at` or `last_message`
};
layer.messages.getAll(cid, params, function(err, res) {
  if (err) return console.error(err);

  var messages = res.body;
});

messages.getAllFromUser(userId, cid, [params], callback)

Retrieve all messages in a conversation from a specific user by providing userId and cid. Response body will result in array of messages.

Arguments

• userId - User ID
• cid - Conversation ID
• params - Optional Query parameters can contain page_size, from_id and sort_by
• callback(err, res) - Callback function returns an error and response objects

messages.getFromUser(userId, messageId, [callback])

Retrieve a single message in a conversation from a specific user by providing userId and messageId. Response body will result in a single message representation.

Arguments

• userId - User ID
• messageId - Message ID
• callback(err, res) - Callback function returns an error and response objects

Announcements

Announcements are messages sent to all users of the application or to a list of users. Recipients should be specified in the recipients property, which takes an array of user IDs.

announcements.send(payload, [callback])

Send an Announcement by providing a payload.

Arguments

• payload - Message payload containing recipients, sender and parts data
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

var payload = {
  recipients: ['abcd', '12345'],
  sender: {
    name: 'The System'
  },
  parts: [
    {
      body: 'Hello, World!',
      mime_type: 'text/plain'
    }
  ]
};
layer.announcements.send(payload, function(err, res) {
  if (err) return console.error(err);

  // announcement data
  var announcement = res.body;
});

---

announcements.sendDedupe(uuid, payload, [callback])

Same as send an announcement above but including de-duplicating UUID value.

Block list

Layer Platform API allows you to manage a block list in order to align with your own application level blocking. A block list is maintained for each user, enabling users to manage a list of members they don't want to communicate with.

• ownerId The owner of the block list
• userId A user that is being blocked from communicating with the ownerId

blocklist.get(ownerId, callback)

Retrieve an array of all blocked users for the specified owner.

Arguments

• ownerId - The owner of the block list
• callback(err, res) - Callback function returns an error and response objects

Examples

layer.blocklist.get(ownerId, function(err, res) {
  if (err) return console.error(err);

  // block list array
  var blocklist = res.body;
});

---

blocklist.block(ownerId, userId, [callback])

Add a new blocked user to the block list for the specified owner.

Arguments

• ownerId - The owner of the block list
• userId - A user that is being blocked by the owner
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

layer.blocklist.block(ownerId, userId, function(err, res) {
  if (err) return console.error(err);

  // user blocked
});

---

blocklist.unblock(ownerId, userId, [callback])

Remove a user from the block list for the specified owner.

Arguments

• ownerId - The owner of the block list
• userId - A user that is being blocked by the owner
• callback(err, res) - Optional Callback function returns an error and response objects

Examples

layer.blocklist.unblock(ownerId, userId, function(err, res) {
  if (err) return console.error(err);

  // user unblocked
});

---

Identities

Layer Platform API allows you to manage Identities in order to associate data about your users with the user. Helpful for quickly rendering information about a user when showing a Message from them.

An Identity consists of the following properties:

• display_name: Required Display name
• avatar_url: Optional Avatar URL
• first_name: Optional First name
• last_name: Optional Last name
• phone_number: Optional Phone number
• email_address: Optional Email address
• public_key: Optional Encryption key
• metadata: Optional Hash of custom keys

identities.create(userId, properties, [callback])

Creates an Identity on the Identities server.

Arguments

• userId - User ID of the user we are creating
• properties - Properties of the user to be created. (display_name is a required property)
• callback(err) - Optional Callback function returns an error or status 201

Examples

layer.identities.create('frodo', {
  display_name: 'Frodo the Dodo',
  first_name: 'Frodo',
  last_name: 'Baggins'
}, function(err, res) {
  if (err) return console.error(err);

  // Identity created
});

---

identities.get(userId, callback)

Retrieves an Identity from the Identities server.

Arguments

• userId - User ID of the user we are updating
• callback(err) - Callback function returns an error or identity object

Examples

layer.identities.get('frodo', function(err, res) {
  if (err) return console.error(err);

  // Identity retrieved:
  console.log('User: ' + res.body.display_name);
});

---

identities.edit(userId, properties, [callback])

Updates an Identity on the Identities server.

Arguments

• userId - User ID of the user we are updating
• properties - Properties of the user that should be updated.
• callback(err) - Optional Callback function returns an error or status 204

Examples

layer.identities.edit('frodo', {
  first_name: 'Frodo 2'
}, function(err, res) {
  if (err) return console.error(err);

  // Identity updated
});

---

identities.replace(userId, properties, [callback])

Replace all properties on Identity.

Arguments

• userId - User ID of the user we are updating
• properties - Properties of the user that should be updated. (display_name is a required property)
• callback(err) - Optional Callback function returns an error or status 204

Examples

layer.identities.replace('frodo', {
  display_name: 'Frodo the Dodo 3',
  first_name: 'Frodo 3'
}, function(err, res) {
  if (err) return console.error(err);

  // Identity updated
});

---

identities.delete(userId, [callback])

Deletes an Identity from the Identities server.

Arguments

• userId - User ID of the user we are deleting
• callback(err) - Optional Callback function returns an error or status 204

Examples

layer.identities.delete("frodo", function(err, res) {
  if (err) return console.error(err);

  // Identity deleted
});

---

Promises

All the above functions can be used to return a promise by appending the Async suffix to the function name e.g.:

conversations.createAsync({participants: ['abcd']}).then(function(res) {
  // conversation ID
  var cid = res.body.id;
}).catch(function(err) {
  console.error(err);
});

Testing

The unit tests are based on the mocha module, which may be installed via npm. To run the tests make sure that the npm dependencies are installed by running npm install from the project directory.

npm test

Contributing

Layer API is an Open Source project maintained by Layer. Feedback and contributions are always welcome and the maintainers try to process patches as quickly as possible. Feel free to open up a Pull Request or Issue on Github.

Changelog

For a list of version changes please refer to Github releases page.

Author

Nil Gradisnik