Store content API

https://api.alert.alertinghub.co.uk/api/json/storecontent

The store content API allows you to upload either alerts, recipient lists or content data and store directly onto the system. Multiple content blocks can be included within a single transaction allowing you to upload a variety of pre-prepared items at the same time. All content stored using this API is held securely using high-grade encryption.

You can then use these stored items when sending alerts instead of specifying all the details in the API call.

Stored items generally have a ‘unused’ lifetime associated with them, which is automatically applied by Alerting Hub. If the content is not used within that time it will be deleted. You can override this automated setting but only if your API key has permission to do so (contact your account manager for details).

JSON sample

{
    "version": "latest",
    "apiKey": "abcdefghijklmnopqrstuvwxyz",
    "content": [
        {
            "contentType": "sms",
            "tag": "t1",
            "storeDetails":  {
                "storeName": "myStoredSms"
            },
            "content": "This is an SMS 1",
            "contentEncoding": "utf8",
            "options": {
                "lifetime": "10d"
            }
        }
    ]
}

Store content

ParameterRequirementDefaultDescription
versionMandatoryNoneSee API guide
apiKeyMandatoryNoneSee API guide
contentMandatoryArray of items to be stored
  contentTypeMandatoryNoneThe type of content which is being stored. One of "call","sms", "email","inboundCall","recipientList", "alert", "contactGroup", "contactList" or "contactSetList"
  contentMandatoryActual content
  contentEncodingMandatoryEncoding of content, one of: "base64" | "utf8" | "json" (the latter only valid if contentType is 'alert' or 'contactGroup')
  tagMandatoryClient defined tag - freeform
  storeDetailsOptionalNoneOptional storage details - see below for more information. Allows you to name a new store or to replace an existing store with new content.
If contentType is 'email'
  emailBodyIsMultipartOptionalFalseIf the body of the email message is multi-part
  emailBodyContentTypeOptionaltext/plain; charset=us-asciiUsed if emailBodyIsMultipart is false
  multipartBoundaryOptionalBlankIf emailBodyIsMultipart: true then this flag is used to denote start of a new mulitpart bounday
If contentType is 'call' or 'inboundCall'
  voiceFormatMandatoryNoneOne of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the contentData. For 'tts' the contentData should decode to simple text.
  ttsOptionalNoneOptional tts block used if voiceFormat is 'tts'. See text-to-speech
  options
    lifetimeOptionalLifetime of stored item if not used - only valid if client is permitted to set. Lifetime is specified as {n}{M|w|d|h|m|s} where M = months, w = weeks, d = days, h = hours and s = seconds. Values will be rounded up to the nearest day. A value of 0d will mean no expiration.
    contactGroupSpecificOptionalIf set and if contentType is contactGroup then this object specifies some modifiers to allow partial updates and other items (see below).

Response

ParameterDescription
successOne of “true”, “false”. If false then failureReason should also be returned
contentArray of stored items processed for deletion
  successOne of “true”, “false”. If false then failureReason should also be returned
  storeIdA unique identifier for the stored content
  storeNameIf you specified a storeName as part of the initiating /storecontent api call this will be reflected here.
  contentTypeType of content as per api call
  tagClient defined tag as per api call
  expirationInDaysThe stored data will be removed after 'n' days if not used

Specifying storeDetails

storeDetails are an optional part of the /storecontent API call and give you control over the naming of your store and also the ability to replace content in an existing store.

    "storeDetails":  {
        "storeName": "myStoredSms"
        "storeId": "e5299a3e-03c8-4cb7-9732-1d5d80f8b97f"
    }

If you specify a storeDetails object you must include either a storeId or a storeName part.

When creating a new stored item you can use the storeName string to give your stored item a name; you can then refer to the stored item by that name whenever you need to use it (say in a /sendalert API call). If you do not specify a storeName then you must rely on the unique store id returned by the API call.

If you specify an existing store (either via the storeName or storeId parts) then the API call will replace the content of that existing store with the new contents you include in the API call.

Specifying contactGroupSpecific details

contactGroupSpecific is an optional set of modifiers used when contentType is contactGroup.

"contactGroupSpecific" : {
     "partialUpdate" : true | false,
     "linkRef": ""a-unique-reference"
}

If linkRef is set then the associated linked alerts’ existing contact group is located and used, and partialUpdate is automatically set to true. This ensures that modifications only occur to the contact group used in the linked alerts (when linked alerts are created using a contact group a copy of the contact group is made and associated with the linked alerts; this means that the linked alerts can modify their contact group members without affecting the original stored contact group).

If partialUpdate is true then the content provided in the API call is merged into the existing contact group. When this option is specified you can also include (within the content object) a “deletions” section within which you can specify individual contacts to be removed, entire sets to be removed or individual members of sets to be removed. If a contact is removed, the platform will also remove any references to that contact from any sets automatically, see the following example:

{
    "version" : "latest",
    "apiKey" : "abcdefghijklmnopqrstuvwxyz",
    "content" : [
        {
            "contentType": "contactGroup",
            "tag" : "contactA", 
            "content" : {
                "name": "test",
                "deletions" : {
                    "contacts": [
                        { "id" : "name-1" },
                        { "id" : "name-55"}
                    ]
                    "sets" : [
                        { "name" : "sales" },
                        { "name" : "management", "ids" : [ "name-0" ] }
                    ]			
               }
            },
            "contentEncoding": "json",
            "options": {
                "contactGroupSpecific" : {
                    "partialUpdate": true
                }
            },
            "storeDetails" : {
                "storeName" : "ContactsA"
            }
       }
    ]
}