A fork of the Twilio node library that implements automatic callback provisioning. Originally based on CEWendel's library https://github.com/CEWendel/heroku-twilio but substantially reworked to use official twilio module.
npm install deedw/node-twilio-autouri --save
The library uses either Redis or MongoDB (using mubsub) to communicate between processes. The Redis client is installed as a module dependency, but if MongoDB is required you will need to add mubsub to your project:
npm install mubsub@^1.2.0 --save
NOTE: mubsub MODULE NO LONGER WORKS WITH LATEST MONGODB AND WILL NEED UPDATING
To start, you'll need to obtain a Twilio account. (https://twilio.com). This will give you a Twilio Account Sid and a Twilio Auth Key. Using these, you may start using node for complex, awesome telephony applications.
node-twilio-autouri uses the npm twilio module provided by Twilio (https://www.npmjs.com/package/twilio') which provides promise based access to the Twilio API (https://www.twilio.com/docs/api).
node-twilio-autouri provides a high-level interface for dealing with Twilio requests and responses, and encapsulates all the functionality within EventEmitters. This means you can develop Twilio applications in node without worrying about or provisioning URIs for every request and response your application will make; It may be non-obvious from the description, but that is awesome.
In order to explain how great this is, I will use an example:
If you were to build a Twilio application in any language using any helper library other than this one, you'd wind up doing something like:
client.calls
.create({
url: UriForCallback,
to: '+14155551212',
from: '+15017122661'
})
.then(call => console.log(call.sid));Then, you'd have to go out and ensure than UriForCallback is a real, provisioned URI, and you'd put either a script or a static Twiml file there, and Twilio would go and fetch it.
node-twilio-autouri, however, takes care of all of that provisioning for you, and represents all Twilio interacts as EventEmitters. Again, this is awesome. Here's an example:
First, we want to instantiate a new Twilo client object. The constructor takes three parameters: the account SID and auth token, as well as the hostname of the application server. (This is used to construct URIs to give Twilio.)
const {Client: TwilioClient} = require('deedw/node-twilio-autouri');
client = new TwilioClient(ACCOUNT_SID, AUTH_TOKEN, MY_HOSTNAME);Now that we have our client, let's get a PhoneNumber object using one of the phone numbers that we've provisioned through some other channel. (Note: You can provision phone numbers via the twilio module) The phone number used here can be any sort of Twilio number. If it's an outgoing caller ID, the object will only be able to make outgoing phone calls/SMS. If it's a regular incoming number, it will be able to make/receive phone calls and SMS.
const phone = client.getPhoneNumber('+16269239971');We'll now setup our phone number. Depending on the options provided this will tell Twilio to call our application when inbound calls or sms come in.
await phone.setupIncoming({voice: true, sms: true}); const call = phone.makeCall('+18674451795');
// 'call' is an OutgoingCall object. This object is an event emitter.
// It emits 'answered' and 'ended' events
// and 'status' event OR if no response to status event, specific in-call / call completed status events
// in-call statuses include 'queued', 'initiated', 'ringing', 'in-progress'
// end-call statuses include 'completed', 'busy', 'failed', 'no-answer'
call.on('answered', function (reqParams, res) {
// reqParams is the body of the request Twilio makes on call pickup.
// For instance, reqParams.CallSid, reqParams.CallStatus.
// See: http://www.twilio.com/docs/api/2010-04-01/twiml/twilio_request
// res is a Twiml.VoiceResponse object. This object handles generating
// a compliant Twiml response.
console.log('Call answered');
// We'll append a single say method to the response:
res.say('Hello, there!');
// And now we'll send it.
res.sendResponse();
});
call.on('ended', function (reqParams) {
console.log('Call ended');
});
// But wait! What if we receive an incoming SMS on our phone number?
phone.on('incomingSms', function (reqParams, res) {
// As above, reqParams contains the Twilio request parameters.
// Res is a Twiml.Response object.
console.log('Received incoming SMS with text: ' + reqParams.Body);
console.log('From: ' + reqParams.From);
res.sendResponse();
});
// Oh, and what if we get an incoming call?
phone.on('incomingCall', function(reqParams, res) {
res.say('Thanks for calling! I think you are beautiful!');
res.sendResponse();
});More documentation is forthcoming.
Copyright (c) 2010 Stephen J. Walters stephenwalters@gmail.com Copyright (c) 2014-2022 David Willis
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.