SMS From Me

Automatically Start One on One SMS Conversations

REST API Subscriptions

What is a subscription?

The SMS From Me environment supports a subscription model within its REST API in order for you to listen to various events on your server.

The concept is simple. If you have an account and want to know what is happening within it, you need to check what changed once in a while. This could be done with a poll mechanism and a compare function. Only that means some statuses will be missed because things may change faster than you poll.

The subscription system will instead register all the events and send them to you in order. So for example a message may get "message.created", "message.sent" as a sequence of events. With a poll, you may immediately detect the status of the message as "sent" and never see the "new" message status.

The usage is simple. You send a REST order to subscribe (POST /api/1/subscription.) The subscribe operation includes three parameters that determine what our SMS From Me server should do when that event occurs. The URL, the method, and whether the pass the data as a query string along the URL or as a JSON in the body of the URL access.

For example, a POST to your URL may look like this:

HTTP/1.1 POST /event/12341211
Host: your-domain.ext
Content-Type: application/json
Content-Length: 23
X-Hook-From: sms_from_me

{"message":{"id":"33"}}

The first line shows the method (POST in this example) and the path where the data gets sent to. The method could be "PUT" or "SIGNAL" instead. You may defined any token as the method.

In case of a POST, we send a JSON object.

Here is another example where your server understands a method named "HIT" and it wants the parameter as a query string variable. Notice that in this case we set the content type to "text/plain" although the body should always be empty.

HTTP/1.1 HIT /event/12341211?message%5Bid%5D=33
Host: your-domain.ext
Content-Type: text/plain
Content-Length: 0
X-Hook-From: sms_from_me

See how the query string is built: Each value is viewed as a map element (an array indexed with numbers or strings.) In this example, we have message[id]=123. The [ and ] are URL encoded so they appear as %5B and %5D.

Whenever you receive such a hit on your server, you should react by getting an OAuth token if your existing one is out of date and then do a GET of the specified object (at this time, this will always be a message.) Then go on with doing whatever you want to do with when that event occurs. For example, you may want to subscribe to the "message.failed" event and send yourself an email when that happens.

Note that all those events can be subscribed to on Zapier. On that platform, events are called Triggers.

Subscription Object

A complete subscription object includes the following fields. Some functions may not return all the fields. It may be as short as just the identifier ("id").

{
  "message": {
    "id": "123",
    "event": "message.create",
    "url": "https://your-domain.ext:8888/your/path?and=parameters",
    "method": "GET",
    "post": "GET",
    "stat_triggered": 123,
  },
  "links": {
    "events": {
      "method": "GET",
      "url": "https://smsfromme.com/api/1/subscription/events"
    },
    "list": {
      "method": "GET",
      "url": "https://smsfromme.com/api/1/subscription"
    },
    "new": {
      "method": "POST",
      "url": "https://smsfromme.com/api/1/subscription"
    },
    "get": {
      "method": "GET",
      "url": "https://smsfromme.com/api/1/subscription/123"
    },
    "edit": {
      "method": "PATCH",
      "url": "https://smsfromme.com/api/1/subscription/123"
    },
    "delete": {
      "method": "DELETE",
      "url": "https://smsfromme.com/api/1/subscription/123"
    },
  }
}

"id" -- this field represents the subscription identifier. It can be used to access a subscription directly with a URL that looks like /api/1/subscription/<id> (without the < and > characters, of course.) Pretty much any reply that involves a subscription will include an "id".

"event" -- the event this subscription is listening to. When that even happens, the URL gets hit by our systems so you know that the event happened. Note that we record events in our database as they happen and a backend process picks them up within a minute or two. So it is not exactly realtime, but it should be close enough compared to you doing constant polls. Note that the event is a filter parameter when trying to edit a subscription.

The currently available events are:

  • message.create -- a message was added to your account
  • message.sent -- a message was successfully sent.
  • message.failed -- a message could not be sent after five attempts.
  • message.blocked -- a message was blocked by the Do Not Text List.

"url" -- the URL you want to have hit by a GET or a POST whenever this event happens. The URL can be just a domain. It may also include a login name, a password, a port, a path, or a query string. Whateveer your system requires. Note that the hit will include the subscription identifier, but you will have to do a GET of that subscription in order to get all the data available for that event.

This parameter can be edited with the PATCH method.

"method" -- the method to use to generate the hit. This can be any valid HTTP token. The default when creating a subcription is POST. The sending capabilities can do the equivalent of a GET or a POST, this is defined by the "post" parameter.

This parameter can be edited with the PATCH method.

"post" -- this flag determines how the data of the event has to be sent. It can be true (send as a POST, in the body) or false (send as a GET, in the query string.)

This parameter can be edited with the PATCH method.

"stat_triggered" -- the number of times this specific subscription has triggered the event so far.

GET /api/1/subscription/events -- get a list of subscription events

This function returns the currently supported list of events.

The idea is for your software to be capable of showing that list to your clients so you can let them choose which ones will be used.

GET /api/1/subscription -- get a list of subscriptions

This path gives you access to all the subscriptions you made within your account. The result is an object with on field named "subscriptions" which is an array of subscriptions.

{
  "subscriptions": [
    {
      "subscription": {
        "id": 123,
        ...
      }
      "links": {
        "events": {
          ...
        }
        ...
      }
    }
  ]
}

POST /api/1/subscription -- create a subscription

The POST to this path is used to create a new subscription. The returned JSON is the complete subscription object newly created on success.

Note that this POST returns 200 on success. We expect to return 201 at some point. You should support both possibilities.

The POST expects a set of parameters as follow:

event=... -- the name of the event to listen to. At this point our interface is limited to one event per subscription. The list of available events is defined in the subscription object above.

There is no default event to subscribe to. Also it has to be exactly equal to one of the available events or an error is generated.

url=https://your-domain.ext/... -- the URL to hit whenever an event happens. Remember that it can take one or two minutes for you to get the hit after an even occurred. It is still much faster than using a poll mechanism. The maximum length of the URL is 1,024 characters.

Note that only URLs that start with "http://" or "https://" are accepted. We do not support triggering any other protocol.

method=POST|GET|... -- the method you want our server to use to hit your URL. The default is POST. Any valid HTTP token will be accepted although the maximum length supported is 16 characters.

post=true|false -- set a flag to determine how we shall sent the data to you. If this parameter is false (the default) then the data is appended to your URL as query string fields. If this parameter is set to true, then the data is instead sent as a set of fields in the body as a POST would normally do.

GET /api/1/subscription/<subscription identifier> -- read a subscription

This function reads the specified subscription. The result is a JSON representing the subscription. If the specified subscription identifier is incorrect or the subscription is not owned by the user represented by the given OAuth token, then you may get an "invalid_parameter" error with a 400 HTTP code, or a "not_a_subscription" error with a 404 HTTP code.

PATCH /api/1/subscription/<subscription identifier> -- edit a subscription

The patch allows you to edit a subscription. The "event" parameter must be specified and match that subscription event exactly. You can then edit the URL, method, and post parameters. At least one parameter to be edited must be specified.

If the specified subscription identifier or the event are incorrect for the current user, then a 404 HTTP code is returned with the error "not_a_subscription".

DELETE /api/1/subscription/<subscription identifier> -- delete a subscription

To unsubscribe from an event, you want to use the DELETE method. The effect is to completely remove that subscription. You may resubscribe later with a POST as shown above.

The DELETE command does not expect any parameter.

Note that the function returns a 400 or 404 error if the specified subscription does not exist. This means it is not idempotent as expected by a REST API. You should at least view the 404 HTTP code as a successful DELETE.

 

Login

 

Register

If you already registered with your email address and needed to re-validate (i.e. the first validation somehow failed) then go to the Validate Page where you can request for a new validation code to be emailed to you.

Login         Register         Get App.
 

Get My Free Book About SMS Marketing

Hey! Before you leave, make sure to get my freeBook About SMS Marketing. All you have to do is enter your email address and I'll send you a link to this website where you can retrieve your own copy of my free book.

Connect With Us
Google Plus Button
LinkedIn Button
YouTube Button