Sending a Voice Message

TMS provides a flexible and easy way for your application to push notifications to your users. In this tutorial, we’ll walk through a couple of scenarios for using TMS to send static or customized voice messages to users.

After this tutorial, be sure to look at the /messages/voice endpoint reference documents for more information on how to view and manage the voice messages you send via TMS.

Prerequisites

Before you can send a voice message, there are a few things your organization will need to do to enable the Targeted Messaging Service:

  • Purchase the Targeted Messaging Service
  • Configure one or more from numbers for the Targeted Messaging Service
  • Get a Targeted Messaging Service API Token

To get started on any of these, please email support@granicus.com.

Send an Audio Media Voice Message to One Person

Once you’ve covered the prerequisites, sending a voice message is simple. The first thing you need to do is decide who you’re going to voice message, and what you want to send. Let’s send a url of audio media as a voice message like the following:

http://www.example.com/media/hello.wav

Now that you know what you want to send, it’s simply a matter of making a POST to /messages/voice with play_url and recipients specified to what you want. TMS then responds with the JSON below.

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/voice --data \
'{
  "play_url": "http://www.example.com/media/hello.wav",
  "recipients": [
    {
      "phone": "6515551212"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 153,
  "play_url": "http://www.example.com/media/hello.wav",
  "recipient_detail_counts":{
   "busy":1,
   "no_answer":0,
   "human":0,
   "machine":0
  },
  "from_number": "+16515550000",
  "created_at": "2016-10-07T17:27:12Z",
  "status": "completed",
  "_links": {
    "self": "/messages/voice/153",
    "recipients": "/messages/voice/153/recipients",
    "failed": "/messages/voice/153/recipients/failed",
    "sent": "/messages/voice/153/recipients/sent",
    "human": "/messages/voice/153/recipients/human",
    "machine": "/messages/voice/153/recipients/machine",
    "busy": "/messages/voice/153/recipients/busy",
    "no_answer": "/messages/voice/153/recipients/no_answer",
    "could_not_connect": "/messages/voice/153/recipients/could_not_connect"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
voice = client.voice_messages.build(play_url:'http://www.example.com/media/hello.wav')
voice.recipients.build(phone:'6515551212')
voice.post
=> true

Once this POST is sent, TMS will send your voice message from the short code or phone number associated with your TMS account.

Send a Text to Voice Message to One Person

TMS also allows you to send text to be converted to a voice message. This is similar to sending an audio media voice message - simply provide say_text and recipients specified to what you want. Let’s send the following text to voice message to Jim:

Hi, Jim!

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/voice --data \
'{
  "say_text": "Hi, Jim!",
  "recipients": [
    {
      "phone": "6515551212"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 64,
  "say_text": "Hi, Jim!",
  "recipient_detail_counts":{
   "busy":0,
   "no_answer":0,
   "human":1,
   "machine":0
  },
  "from_number": "+16515550000"
  "created_at": "2017-08-30T16:26:19Z",
  "status": "completed",
  "_links": {
    "self": "/messages/voice/64",
    "recipients": "/messages/voice/64/recipients",
    "failed": "/messages/voice/64/recipients/failed",
    "sent": "/messages/voice/64/recipients/sent",
    "human": "/messages/voice/64/recipients/human",
    "machine": "/messages/voice/64/recipients/machine",
    "busy": "/messages/voice/64/recipients/busy",
    "no_answer": "/messages/voice/64/recipients/no_answer",
    "could_not_connect": "/messages/voice/64/recipients/could_not_connect"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
voice = client.voice_messages.build(say_text:'Hi, Jim!')
voice.recipients.build(phone:'6515551212')
voice.post
=> true

In the above example, TMS will convert the say_text provided to voice and will send your voice message from the short code or phone number associated with your TMS account.

Send a Voice Message to Multiple People

At some point, you’ll probably want to send an voice message to more than one person. This is just as simple to do with TMS as sending an voice message to a single person and can be done with both audio media and text to voice - all you need to do is specify multiple recipients. Let’s send a hello message again, but this time to multiple people:

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/voice --data \
'{
  "play_url": "http://www.example.com/media/hello.wav",
  "recipients": [
    {
      "phone": "6515551212"
    },
    {
      "phone": "6515551001"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 155,
  "play_url": "http://www.example.com/media/hello.wav",
  "created_at": "2016-11-07T17:27:12Z",
  "status": "completed",
  "recipient_detail_counts":{
   "busy":0,
   "no_answer":0,
   "human":1,
   "machine":1
  },
  "from_number": "+16515550000",
  "_links": {
    "self": "/messages/voice/155",
    "recipients": "/messages/voice/155/recipients",
    "failed": "/messages/voice/155/recipients/failed",
    "sent": "/messages/voice/155/recipients/sent",
    "human": "/messages/voice/155/recipients/human",
    "machine": "/messages/voice/155/recipients/machine",
    "busy": "/messages/voice/155/recipients/busy",
    "no_answer": "/messages/voice/155/recipients/no_answer",
    "could_not_connect": "/messages/voice/155/recipients/could_not_connect"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
voice = client.voice_messages.build(play_url:'http://www.example.com/media/hello.wav')
voice.recipients.build(phone:'6515551212')
voice.recipients.build(phone:'6515551001')
voice.post
=> true

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/voice --data \
'{
  "say_text": "Hello, friends!",
  "recipients": [
    {
      "phone": "6515551212"
    },
    {
      "phone": "6515551100"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 1001,
  "say_text": "Hello, friends!",
  "recipient_detail_counts":{
   "busy":0,
   "no_answer":0,
   "human":2,
   "machine":0
  },
  "from_number": "+16515550000",
  "created_at": "2016-12-15T14:22:15Z",
  "status": "completed",
  "_links": {
    "self": "/messages/voice/1001",
    "recipients": "/messages/voice/1001/recipients",
    "failed": "/messages/voice/1001/recipients/failed",
    "sent": "/messages/voice/1001/recipients/sent",
    "human": "/messages/voice/1001/recipients/human",
    "machine": "/messages/voice/1001/recipients/machine",
    "busy": "/messages/voice/1001/recipients/busy",
    "no_answer": "/messages/voice/1001/recipients/no_answer",
    "could_not_connect": "/messages/voice/1001/recipients/could_not_connect"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
voice = client.voice_messages.build(say_text:'Hello, friends!')
voice.recipients.build(phone:'6515551212')
voice.recipients.build(phone:'6515551100')
voice.post
=> true

Again, once this POST is sent, TMS will send your voice message to every recipient you specify.

In all of our examples, you’ve probably noticed that TMS also sends you a response with a number of properties. Among these properties are a set of URLs (all found in the _links object) that you can request to review the voice message you sent and check its status, review the status of all of the recipients you specified for your voice message, retrieve lists of recipients who have received your voice message, and recipients who TMS could not deliver your voice message to.