SMS SUBSCRIPTION

1. Register keywords.
2. Save an initial, optionally empty, subscription list with Alerting Hub.
3. Receive notifications from Alerting Hub when your keywords are seen.
4. Update the subscription list held with Alerting Hub.
5. Broadcast to your clients using our sendalert API, specifying the saved subscription list.

• Keywords are simply freeform text that can be sent via SMS to an Alerting Hub SMS inbox (telephone number); example keywords for a subscription service might be ‘subscribe-weather’ or ‘unsubscribe-weather’.
• Keywords can be registered on a shared Alerting Hub SMS inbox on a first come first served basis, or a dedicated SMS inbox can be purchased. You can have the same keyword over multiple SMS inbox numbers.
• Please talk to your account manager about setting up keywords.

Subscription lists are managed in Alerting Hub using the contact group capability. To save an initial empty contact group send the following to our /storecontent API call:

{
  "version": "latest",
  "apiKey": "xxxxxx-xxxx-xxxxxx-xxxx",
  "content": [
    {
      "contentType": "contactGroup",
      "tag": "aTag",
      "content": {
        "contacts": []
      },
      "contentEncoding": "json",
      "storeDetails": {
        "storeName": "MySubscriptionGroup"
      }
    }
  ]
}

The above JSON simply specifies an empty contact group (contacts set is empty) and that can be referred to as ‘MySubscriptionGroup’. More details on the /storecontent API call can be found here and more details on contact groups can be found here.

If you had a pre-existing set of contacts / clients you wanted adding to the contact group then you can simply add them all in one go by populating the contacts array as required.

On a successful API call you will receive back some JSON that will look similar to this:

{
  "success": true,
  "returnCode": 200,
  "content": [
    {
      "contentType": "contactGroup",
      "tag": " aTag ",
      "success": true,
      "storeId": "xxxxxx-xxxx-xxxxxx-xxxx",
      "storeName": "MySubscriptionGroup"
    }
  ]
}

The important information is the success = true element, you can ignore the storeId if you want as you can always refer to your saved contact group by the name you gave it ‘MySubscriptionGroup’.

We now have registered keywords and we have a basic subscription list stored away. The next step is to ensure you can receive events when Alerting Hub receives SMS to it inboxes that contain your keywords.

There are two ways to do this, either by Alerting Hub calling you back on a webhook (see here) when the event occurs or by you regularly polling Alerting Hub for events using the /collectevents API (see here).

You will most likely have already done this step when you initially setup your Alerting Hub API account and began using it so this is presented here for completeness only.

When you receive events from Alerting Hub relating to your keywords you will receive something that looks similar to this:

{
      "alerter": "+441000100010",
      "keyword": "subscribe",
      "event": "keyword",
      "type": "sms",
      "alertees": [
        "+441234512345"
      ],
      "whence": "2021-12-08T08:09:39.000Z",
      "reply": "subscribe John Smith",
      "replyEncoding": "utf8"
    }

As you can see, the important items are:

• The event = keyword which tells you this is a keyword match.
• The keyword item which denotes the registered keyword that was matched.
• The alertees which is an array, usually one entry, that denotes the phone number of the person sending in the SMS.
• The reply which is the full SMS message, which allows you to do more processing if required.

When you receive a notification of a keyword event, as described above, or if you have other mechanisms for allowing subscribing / unsubscribing (e.g. via a web portal, or an automatic unsubscribe after a certain period) then your next step is to update the contact list as held by Alerting Hub (assuming that you are happy to add the person requesting the subscription).

If you wanted to add a person to the list you would do so using the same /storecontent API call as shown in step 2 except this time you would send something similar to:

{
  "version": "latest",
  "apiKey": " xxxxxx-xxxx-xxxxxx-xxxx ",
  "content": [
    {
      "contentType": "contactGroup",
      "tag": "aTag",
      "content": {
        "contacts": [
          {
            "id": "+441234512345",
            "sms": "+441234512345"
          }
        ]
      },
      "contentEncoding": "json",
      "options": {
        "contactGroupSpecific": {
          "partialUpdate": true
        }
      },
      "storeDetails": {
        "storeName": "MySubscriptionGroup"
      }
    }
  ]
}

As you will see the above is very close to the original /storecontent only this time we are:

• Specifying a contact in the contacts array.
• Specifying partialUpdate = true to ensure we merge this into the existing saved group.

You will notice that the contact consists of two items, an id and an sms entry. The former (id) must be specified and is a unique reference for the contact, in this case it’s easy enough to just use the phone number; the latter (sms) specifies the phone number to use to send the contact an SMS.

If you have a pre-existing database of potential clients you could set the id to be their unique database reference, client number or full name.

If you wanted to remove someone from the contact list (unsubscribe) then you make a similar call to /storecontent but in this case it would look something like:

{
  "version": "latest",
  "apiKey": "xxxxxx-xxxx-xxxxxx-xxxx",
  "content": [
    {
      "contentType": "contactGroup",
      "tag": "aTag",
      "content": {
        "deletions": {
          "contacts": [
            {
              "id": "+441234512345"
            }
          ]
        }
      },
      "contentEncoding": "json",
      "options": {
        "contactGroupSpecific": {
          "partialUpdate": true
        }
      },
      "storeDetails": {
        "storeName": "MySubscriptionGroup"
      }
    }
  ]
}

As you can see, the only difference is that the original ‘contacts’ has been removed and replaced with a ‘deletions|contacts’ section that contains just the ids of the contacts requiring removal.