Sending and Receiving SMS

Interactive Tutorials are currently not supported on mobile devices. To ensure an enhanced experience, kindly access this tutorial from a laptop/desktop browser instead.

Elarian provides communication infrastructure, one of which is sending SMS messages. Let's look at how this works by sending our first SMS.

Before we continue, make sure you've Created an Account and have gone through the tutorial on Establishing a Connection.

Send SMS

To send SMS, you'll need two resources, a Sender ID and a Short Code. A Sender ID brands an SMS when it's received by a customer, e.g., "BANK-NAME" when receiving a message from your bank. On the other hand, a Short Code is a 4 to 6 digit number - e.g., 4040 - that can also act as a brand identifier, but, more importantly, Short Codes allow customers to send you messages.

Create your Sender ID

Create your Short Code

Great! If you've got your resources, let's start by sending an SMS

const { Elarian }  = require('elarian');

const client = new Elarian({
  orgId: 'YOUR-ORG-ID',
  appId: 'YOUR-APP-ID',
  apiKey: 'YOUR-API-KEY',
});

function sendMessage() {
  const customer = new client.Customer({
      provider: 'cellular',
      number: 'PHONE-NUMBER-FROM-SIMULATOR'
  });

customer
  .sendMessage(
    { number: 'YOUR-SENDER-ID', channel: 'sms' },
    {
      body: {
        text: 'Hello World!'
      },
    },
  )
  .then(console.log)
  .catch(console.log);
}

client
  .on('connected', () => {
    console.log('App is connected');
    sendMessage();
  })
  .on('error', (error) => {
    console.log('Connection failed -> ', error);
  })
  .connect();

Elarian is a customer-centric platform, meaning most actions are done from a customer's perspective. So that's why we first initialize a new customer object that we'll then use to perform actions.

Before running this code, launch the phone simulator from the bottom left corner of the menu. Use a valid phone number to launch the simulator, and make sure to use the same number in the code you're about to run.

If the force is strong with you 💥💯, you should have received a "Hello World" SMS on the simulator and a successful message logged to the console.

Change the number parameter in the sendMessage function to the Short Code you created and try sending a different message 🧑🏼‍💻

Receive SMS

Receiving SMS on Elarian is very simple. All you need to do is set an event listener and handler like this:

function onReceivedSms (notification, customer) {
  console.log('Received SMS notification -> ', JSON.stringify(notification));

  // Respond to customer
  customer
    .sendMessage(
    { number: 'YOUR-SHORTCODE', channel: 'sms' },
    {
      body: {
        text: 'Thanks for texting back :) You rock!'
      },
    },
  )
  .then(console.log)
  .catch(console.log);
}

client.on('receivedSms', onReceivedSms);

Elarian is opinionated on using this event-driven pattern, which is possible as Elarian sets up a persistent bi-directional link between your application and the Elarian server. A considerable advantage you gain from this is not needing to configure webhooks and an HTTP server.

The customer parameter sent to the receive SMS handler represents the customer sending you an SMS. We think this customer-centric pattern makes it easier to write complex logic. We describe this as using the customer as the unit of abstraction; we'll go into this deeper in the coming tutorials.

You can now update and run your code, expand the simulator, and send an SMS to your shortcode.