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" } } ] }