Keyword Tutorial - hello_world

SMS Keywords are a powerful way to engage with your residents, and are easy to setup with GovDelivery’s Targeted Messaging Service. To get you started with SMS Keywords, let’s create a hello_world keyword that responds with some static phrase.

After this tutorial, be sure to checkout out the /keywords and /keywords/{id} endpoint reference documents for more information on how to view and manage your SMS keywords.

Prerequisites

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

  • Purchase the Targeted Messaging Service
  • Configure a phone number for the Targeted Messaging Service
  • Get a Targeted Messaging Service API Token

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

Create A Keyword

Once you’ve covered the prerequisties, setting up a keyword with a static response is quite simple. All you need to do is send a POST request to the /keywords endpoint like so:

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" https://tms.govdelivery.com/keywords --data \
"name=hello_world&response_text=Hi%20there\!%20It%27s%20nice%20to%20hear%20from%20you."

// RESPONSE BODY
{  
  "name":"hello_world",
  "response_text":"Hi there! It's nice to hear from you.",
  "created_at":"2015-03-02T20:35:16Z",
  "updated_at":"2015-03-02T20:35:16Z",
  "_links":{  
    "self":"/keywords/1",
    "commands":"/keywords/1/commands"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
keyword = client.keywords.build(name:"hello_world", response_text:"Hi there! It's nice to hear from you.")
keyword.post
=> true

That’s it! After sending the above request and getting a successful response (201), you’ll be able to text the keyword hello_world to the number configured for your account and receive the cheerful response Hi there! It's nice to hear from you.. As part of a successful response, you’ll also receive an object representing your new keyword, including the endpoint URL of your new keyword.

Change A Keyword’s Static Response

Greetings are nice, but providing your users with actionable information is even nicer. So, let’s update the keyword we just created to respond with some useful information, such as the operating hours of a service center.

Updating a keyword is just as easy as creating one. To change the message that a keyword responds with, you simply need to send a PUT request with the new response text to the URL of your keyword:

$ curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" https://tms.govdelivery.com/keywords/1 --data \
"response_text=Hi\!%20Our%20service%20centers%20are%20open%20every%20day%2C%208am%20to%206pm."

// RESPONSE BODY
{  
  "name":"hello_world",
  "response_text":"Hi! Our service centers are open every day, 8am to 6pm.",
  "created_at":"2015-03-02T20:35:16Z",
  "updated_at":"2015-03-02T20:38:16Z",
  "_links":{  
    "self":"/keywords/1",
    "commands":"/keywords/1/commands"
  }
}

keyword.response_text = "Hi! Our service centers are open every day, 8am to 6pm."
keyword.put
=> true

Summary Code Example

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" https://tms.govdelivery.com/keywords --data \
"name=hello_world&response_text=Hi%20there\!%20It%27s%20nice%20to%20hear%20from%20you."

// RESPONSE BODY
{  
  "name":"hello_world",
  "response_text":"Hi there! It's nice to hear from you.",
  "created_at":"2015-03-02T20:35:16Z",
  "updated_at":"2015-03-02T20:35:16Z",
  "_links":{  
    "self":"/keywords/1",
    "commands":"/keywords/1/commands"
  }
}
$ curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" https://tms.govdelivery.com/keywords/1 --data \
"response_text=Hi\!%20Our%20service%20centers%20are%20open%20every%20day%2C%208am%20to%206pm."

// RESPONSE BODY
{  
  "name":"hello_world",
  "response_text":"Hi! Our service centers are open every day, 8am to 6pm.",
  "created_at":"2015-03-02T20:35:16Z",
  "updated_at":"2015-03-02T20:38:16Z",
  "_links":{  
    "self":"/keywords/1",
    "commands":"/keywords/1/commands"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
keyword = client.keywords.build(name:"hello_world", response_text:"Hi there! It's nice to hear from you.")
keyword.post
=> true
keyword.response_text = "Hi! Our service centers are open every day, 8am to 6pm."
keyword.put
=> true