Cloud SMS¶

Enfonica's Cloud SMS API helps you to add robust SMS capabilities to your applications. Enfonica proactively monitors all of our carrier interconnections and bindings to ensure that we are only using the best performing routes available.

Key capabilities¶

Send and receive SMS¶

Send SMS to anywhere in the world using one API. Receive SMS on SMS-enabled phone numbers in supported countries.

Branded sender ID¶

Customize the sender ID of outgoing messages using letters and numbers up to 13 characters in length to supported countries.

Delivery receipts¶

Get instant webhook notifications when your messages have been delivered, when they can’t be delivered (e.g. handset off) or if delivery fails (e.g. bad phone number).

Auto concatenation¶

Our platform will automatically handle long messages so you don’t have to write complex splitting and concatenation code.

Built-in unsubscribe support¶

Compliance is easier with automatic opt-out on STOP replies. For non-marketing use-cases, bypass the opt-out list by specifying that your messages are transactional.

Getting started with Cloud SMS¶

This quickstart shows you how to send an SMS message and then retrieve the message to see the updated status.

Get prepared¶

To use the API, you will need:

Your access token (a bearer token).
Your project name (e.g. projects/my-project).

To use the Enfonica Client Library, you will need:

Your service account key.

Send a message¶

To send an SMS, you must specify to, from, and body at minimum. A description of all available fields is available in the Cloud SMS API Reference.

All phone numbers must be specified in E164 format. A great library for converting numbers from local format to E164 is libphonenumber. Alternatively, in most cases, you can drop the leading 0 and prepend the country code with a leading plus. For example, the Australian phone number 0421333444 is +61421333444 in E164.

Example: send an SMS¶

.NETNode.jsBash

var client = MessagesClient.Create();

var result = await client.CreateMessageAsync(new CreateMessageRequest()
{
    Parent = "projects/first",
    Message = new Message()
    {
        To = "+61421333444",
        From = "MyApp",
        Body = "This is a test from the Cloud SMS API!"
    }
});

const messaging = require('@enfonica/messaging');
const MessagesClient = new messaging.MessagesClient();

async function createMessage() {
  try {
    const [response] = await MessagesClient.createMessage({ 
      parent: 'projects/my-project', 
      message: { 
        to: '+61421333444', 
        from: 'MyApp', 
        body: 'This is a test from the Cloud SMS API!' 
      } 
    });
  } catch (error) {
    console.log(error);
  }
}

createMessage();

# Change these variables accordingly
PROJECT=projects/your-project-here
ACCESS_TOKEN=your-access-token-here
FROM=MyApp
TO=+61421333444
BODY="This is a test from the Cloud SMS API!"

curl -i \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-type: application/json" \
  -X POST \
  -d "{'from':'$FROM','to':'$TO','body':'$BODY'}" \
  https://messaging.api.enfonica.com/v1/$PROJECT/messages

The bash example prints the response to stdout. This is an example response:

{
  "name": "projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p",
  "to": "+61421333444",
  "from": "MyApp",
  "body": "This is a test from the Cloud SMS API!",
  "validityPeriodSeconds": 432000,
  "smartEncoding": false,
  "labels": {},
  "direction": "OUTGOING",
  "segmentCount": 1,
  "status": "SENDING",
  "createIdentity": "serviceAccount:my-service-account@my-project.iam.enfonica.com",
  "encoding": "GSM7",
  "createTime": "2020-07-10T06:39:58.379036Z"
}

Retrieve a message¶

You may want to retrieve a message that you have sent using the API to check its status or whether it has been delivered. You can identify a message that you have sent by its name (of the form projects/*/messages/*) which is returned when you send a message.

Example: retrieve an SMS¶

BashNode.js

# Change these variables accordingly
ACCESS_TOKEN=your-access-token-here
MESSAGE=projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p

curl -i \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://messaging.api.enfonica.com/v1/$MESSAGE

const messaging = require('@enfonica/messaging');
const MessagesClient = new messaging.MessagesClient();

async function getMessage() {
  try {
    const [response] = await MessagesClient.getMessage({
      name: 'projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p'
    });
  } catch (error) {
    console.log(error);
  }
}

getMessage();

The example prints the response to stdout. An example response is below. Compared to the previous response, this response shows the message's status as DELIVERED and includes a sendTime and deliverTime.

{
  "name": "projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p",
  "to": "+61421333444",
  "from": "MyApp",
  "body": "This is a test from the Cloud SMS API!",
  "validityPeriodSeconds": 432000,
  "smartEncoding": false,
  "labels": {},
  "direction": "OUTGOING",
  "segmentCount": 1,
  "status": "DELIVERED",
  "createIdentity": "serviceAccount:my-service-account@my-project.iam.enfonica.com",
  "encoding": "GSM7",
  "createTime": "2020-07-10T06:39:58.379036Z",
  "sendTime": "2020-07-10T06:39:58.404940Z",
  "deliverTime": "2020-07-10T06:39:59.524854Z"
}

If you subtract the createTime from the deliverTime, you can determine the delay from when you called the API to when confirmation of successful delivery was received. In this example, it was 1.1 seconds. Meep meep!