You already know that DOTGO can be used to access interactive services on demand. But did you know that DOTGO can also be used to access subscription services on a schedule? With this powerful feature of DOTGO, you can offer your users “alerts” on a one-off or regularly-scheduled basis or “on update,” when new content becomes available.

This document describes how to implement subscriptions under DOTGO. The document assumes that you have some familiarity with DOTGO and CMRL (obtained, e.g., by reading A Brief Introduction to DOTGO).

Consider a service under the internet domain name “example” and the match pattern “horoscope” that provides a horoscope given a zodiac sign. A possible query might be

example horoscope libra

Now suppose that you as an astrology enthusiast want to have this query automatically executed every day at the same time, say 9:00 AM Eastern Time. To do this, you could set up a “subscription” or an “alert” with the query

example horoscope libra subscribe daily 9am eastern

which would produce the response

Reply YES to confirm your subscription to "example horoscope libra" daily at
9am eastern. You can unsubscribe any time by sending STOP.

Replying

yes

(in the very next text message) would produce the response

You have been subscribed. Unsubscribe with "example horoscope libra
unsubscribe" or by replying STOP to any subscription message.

You would then receive the response to the query “example horoscope libra” every day at 9:00 AM Eastern Time. You could unsubscribe at any time with the query

example horoscope libra unsubscribe

or by replying “s” or “stop” to any subscription message. (Indeed, you would be reminded of how to unsubscribe in every subscription message).

So how does it work? In the query “example horoscope libra subscribe daily 9am eastern,” “subscribe” is a DOTGO reserved word or “directive,” which indicates that the query is not to be treated as usual. Specifically, instead of resolving the query as usual, the system establishes a subscription to the portion of the query before the directive (which in this case is “example horoscope libra”) according to the schedule specified by the “directive argument,” i.e. everything after the directive, which in this case is “daily 9am eastern.” The system handles all details of confirming, fulfilling, and terminating the subscription.

A subscription is specified by appending “subscribe” followed by (1) an optional complete or partial starting date and time, (2) a period, and (3) an optional time zone to any query.

First, let's consider specification of a complete or partial starting date and time. If any part of the starting date and time is not specified, then it defaults to now. So, for example,

february 1 8am

indicates next February 1 at 8:00 AM. And

11:15 am

indicates next 11:15 AM (which may be today or tomorrow, depending on what time it is now). And

June 1

indicates next June 1 at whatever time it is now. Names of months and AM and PM are irrespective of case and can be abbreviated, and the order of date and time does not matter. So, for example,

9p aug 14

indicates next August 14 at 9:00 PM.

Next, let's consider specification of a period. The period can be any one of “once,” “hourly,” “daily,” “weekly”, or “monthly.” Or the period can specify any one of number of “minutes” (which can be abbreviated “min” or “mins”), “hours” (which can be abbreviated “hr” or “hrs”), “days” (which can be abbreviated “day”), or “weeks” (which can be abbreviated “wk” or “wks”). So, for example,

15 min

indicates every 15 minutes. Or the period can specify a sequence of day abbreviations, including any combination of m (for Monday), t (for Tuesday), w (for Wednesday), r or th (for Thursday), f (for Friday), sa (for Saturday), and su (for Sunday). So, for example,

mtwrf

indicates every week day, while

susa

indicates every weekend day. Or the period can specify “on update” or “onupdate,” which indicates whenever new content is available (such as the update of an RSS feed—the DOTGO servers periodically poll for new content.)

Finally, let's consider specification of a time zone. DOTGO is currently available only in the U.S., and the time zone can be any one of “eastern,” “central,” “mountain,” “pacific,” “hawaii,” and “alaska.” The time zone defaults to “eastern” if it is not specified. The system handles daylight savings time. (Note that under this scheme, it is not possible to specify exceptions to daylight savings time for localities, such as Arizona, that do not observe daylight savings time.)

Putting this all together, the query

example subscribe 3 hr

establishes a subscription to the query “example” every three hours starting now. The query

example subscribe 2pm eastern daily

establishes a subscription to the query “example” daily at 2:00 PM Eastern Time. The query

example subscribe mwf 6:30a pacific

establishes a subscription to the query “example” every Monday, Wednesday, and Friday at 6:30 AM Pacific Time. The query

example subscribe July 22 12pm once

establishes a one-time subscription to the query “example” on July 22 at 12:00 PM Eastern Time. And the query

example subscribe on update

establishes a subscription to the query “example” on update.

The syntax used to specify subscriptions is concise and complete but perhaps a bit awkward to use in practice within the context of text messages. An alternative is to create links to subscriptions using the <a> or <anchor> tags. For example, consider the following CMRL fragment under the internet domain name “example”:

<match pattern="subscription">
  <message>
    <content>Reply <a query="example subscribe on update"/> to
subscribe</content>
  </message>
</match>

Under this construction, the query

example subscription

produces the response

Reply (1) to subscribe

Then the reply “1” (in the very next text message) is equivalent to the query

example subscribe on update

As another example, consider the following CMRL fragment under the internet domain name “example”:

<match pattern="subscription">
  <message>
    <content>Reply to subscribe:<br/>
<a query="example subscribe daily 9a eastern"/> Eastern<br/>
<a query="example subscribe daily 9a central"/> Central<br/>
<a query="example subscribe daily 9a mountain"/> Mountain<br/>
<a query="example subscribe daily 9a pacific"/> Pacific<br/></content>
  </message>
</match>

Under this construction, the query

example subscription

produces the response

Reply to subscribe:
(1) Eastern
(2) Central
(3) Mountain
(4) Pacific

Then the reply of the appropriate number (in the very next text message) is equivalent to the appropriate query for the appropriate time zone.

The “subscribe” directive allows you to offer your users “alerts” on a one-off or regularly-scheduled basis or “on update,” when new content becomes available. The next step is to try it for yourself.