Skip to content

Get 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:

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

To use the Enfonica Client Library, you will need:

  1. Your service account key, Click here for more information on how to get 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 on the REST 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

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();

MessagesClient.createMessage({ 
  parent: 'projects/my-project', 
  message: { 
    to: '+61421333444', 
    from: 'MyApp', 
    body: 'This is a test from the Cloud SMS API!' 
  } 
});
# 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

# 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();

MessagesClient.getMessage({
  name: 'projects/my-project/messages/j6tfskeu3q0t6k3hp4fnh7d19c1p1p'
}).then(response => {
  if (response[0].status === 'DELIVERED') {
    console.log('Message has been delivered' response);
  }
});

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!