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

Parameter	Requirement	Default	Description
version	Mandatory	None	See API guide
apiKey	Mandatory	None	See API guide
content	Mandatory		Array of items to be stored
contentType	Mandatory	None	The type of content which is being stored. One of "call","sms", "email","inboundCall","recipientList", "alert", "contactGroup", "contactList" or "contactSetList"
content	Mandatory		Actual content
contentEncoding	Mandatory		Encoding of content, one of: "base64" \| "utf8" \| "json" (the latter only valid if contentType is 'alert' or 'contactGroup')
tag	Mandatory		Client defined tag - freeform
storeDetails	Optional	None	Optional 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'
emailBodyIsMultipart	Optional	False	If the body of the email message is multi-part
emailBodyContentType	Optional	text/plain; charset=us-ascii	Used if emailBodyIsMultipart is false
multipartBoundary	Optional	Blank	If emailBodyIsMultipart: true then this flag is used to denote start of a new mulitpart bounday
	If contentType is 'call' or 'inboundCall'
voiceFormat	Mandatory	None	One 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.
tts	Optional	None	Optional tts block used if voiceFormat is 'tts'. See text-to-speech
options
lifetime	Optional		Lifetime 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.
contactGroupSpecific	Optional		If set and if contentType is contactGroup then this object specifies some modifiers to allow partial updates and other items (see below).

Response

Parameter	Description
success	One of “true”, “false”. If false then failureReason should also be returned
content	Array of stored items processed for deletion
success	One of “true”, “false”. If false then failureReason should also be returned
storeId	A unique identifier for the stored content
storeName	If you specified a storeName as part of the initiating /storecontent api call this will be reflected here.
contentType	Type of content as per api call
tag	Client defined tag as per api call
expirationInDays	The 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"
            }
       }
    ]
}