zamano-api

Node.js API for Zamano, a mobile message aggregation service. Allows servers to send and recieve mobile text and binary messages.

Version: 0.1.5

Setup

To install the package, run:

npm install zamano-api

Then call require with your client ID and password provided by Zamano. The id and password are required by zamano to authenticate you before sending your mobile message.

var zamano = require('zamano-api')('CLIENT_ID', 'ZAMANO_PASSWORD')

Usage

Zamano has API methods for both sending and receiving mobile messages.

zamano.sendMessage(opts, callback)

zamano.sendMessage sends a text message to a mobile number over a specific mobile network operator. This method calls back with either a success object or error object with messages from Zamano's service. Internally, this method sends a request to Zamano's HTTP API and parses the XML response into a JavaScript object.

zamano.sendMessage({
  sourceMsisdn:      'SHORT_CODE',
  destinationMsisdn: 'PHONE_NUMBER',
  messageText:       'Hello world',
  operatorId:        'ID_NUMBER'
}, function(err, out) {...})

Parameters:

• opts (Object)

  • destinationMsisdn - destination mobile phone number.
  • messageText - text of the message.
  • sourceMsisdn (optional) - short code representing the tariff amount and country.
  • operatorId (optional) - The unique identifier of the Mobile Network Operator.
  • requestId (optional) - a reference/tag for this message.
  • sourceMsisdnTag (optional) - the label that the message will appear to come from on end users' handsets.
  • clientId (optional) - an override for the Id set at initialization.
  • password (optional) - an override for the password set at initialization.

• callback (Function) - a function with conventional node.js function(err, out) signature. If the message was a success, the out object will have a responseId tracking number generated by zamano's server.

zamano.handleMessages(opts)

Express middleware for parsing mobile-originating (MO) SMS message requests from Zamano. Use the function as middleware in a app.get('') function to authenticate the request from Zamano and add a mobileMessage property to the request object:

app.get('/api/mo', 
  zamano.handleMessages({username: 'MO_USERNAME', password: 'MO_PASSWORD'}),
  function(req, res) {
    console.dir(req.mobileMessage)
    res.end()
})

Request authentication is done by passing the mobile-originating zamano username and password to the handleMessages function. NOTE this is a different username and password than the client id and password set at initialization. Contact your zamano representative if you have questions about your usernames and passwords.

If the options are not passed to the handleMessages function, no authentication will be performed. This means any requests will be accepted by the middleware. Note: zamano will always make a request from the same IP, which means you can choose to manually authenticate by IP address instead of using the username and password.

The mobileMessage object that is attached to the request has the following properties:

• username - user's mobile-originating zamano id.
• password - user's mobile-originating zamano password.
• from - the originating mobile phone number.
• to - the terminating number to which the message was sent.
• text - the text of the message.
• operatorId - The unique identifier of the Mobile Network Operator.

Note: Zamano's server expects a response from the mobile originating message request. If there is no response within 2 seconds, then the transaction will be considered failed.

For Shortcodes and Operator IDs, please refer to Zamano.