Messaging Workflow Dispatch API

A successful request will return 200 OK and a json document of the following format. If the user does not present proper login credentials or cannot read any address books, a 401 Unauthorized will be returned, with no json document.

while the alphanumeric recipient number was rejected.

will output

Currently, every saved job type that can be started is derived from one of the two generic types, GenericMonitoredMessage (GMM) and GenericMultiAssign (GMA). These have a different look in the web portal interface and different ways of selecting recipients.

GMM derived pages start jobs that expect a response (usually Yes or OK to acknowledge receipt of the message) from every recipient. The GMM jobs have a single web page for the sendout and recipients are specified by adding to the recipient table a mixture of any number of contacts, tag filters (saved or custom), groups/distribution lists and non-contact numbers.

The GMA jobs, on the other hand, are started from a multi-step wizard page which select recipients from how they are tagged in the address book, using tag filters with different values of a single tag type, for example specifying a tag type Role and prescribing a response goal of 1 where the Role is Surgeon, and another response goal of 2 where the Role is Registered Nurse. The example sendout goes to all Surgeons and RNs and finishes when 1 Surgeon and 2 RNs have responded with Yes. The settings page for GMA jobs further allows for setting a global tag filter, so that only those Surgeons and RNs who also have the tag value OnCall:Yes will get the sendout.

The difference in how recipients are selected will make different parameters to this API work in different ways, or not at all, with the different generic job types. If a disallowed parameter is specified when starting a job of a certain type, this will result in a 400 error and no messages being sent.

Changing job name, scheduled start time and main message text is possible for both GMM and GMA.

GMA allows the "assigned message", i.e. the saved message to be sent at the time of assignment to each recipient who is assigned to the job, to be changed by supplying the parameter assignedmessage to the API. The corresponding message in GMM is taken from the currently active job type settings and cannot be changed from the API, resulting in a 400 error with no messages being sent if a non-blank value is supplied.

GMM also allows all the to-parameters and exclude-parameters. The parameter tokeep determines whether the to-parameter recipients are added to those in the saved job, or if they are replaced (the default). The exclude-parameters exclude recipients from both saved and new recipient lists. While changing the GMM responsegoal is not currently possible from the web page, it works fine from this API.

GMA only selects from one tag type, and keeps different response goals for different values for this tag. It can also do escalation using another tag type and set of values, where recipients with different values receive their message at different times. There is a global tag filter from the settings which is added onto the original filter. If this API is called, it is possible to specify a toaddressbookcustomtagfilter or a toaddressbooktagfilterjson, which may be complex, like Role:Surgeon;OnCall:Yes. When this feature is used, a responsegoal must also be given, while a responsegoal cannot be used without a new filter. When a complex new filter is used, it is divided into a first filter used as the tag type and tag value in standard GMA, while the rest of the tag filter goes into the global tag filter, replacing the value from settings. All filters, escalations and response goals from the saved job are ignored in that case. Calling this API without specifying a new filter and response goal will use the filters, escalations and response goals from the saved job, as well as the global tag filter from the settings. The other to-parameters, tokeep and all exclude-parameters are disallowed for the GMA generic job type.

A successful request will, after some waiting time, return 200 OK and a json document of the following format.

In the case that a job start request is formally successful, but the job could not be started because of problems in the saved job, there will still be a 200 OK response, but with the result code in the JSON response different from "OK". HTTP results other than 200 OK, e.g. 400 Bad request or 401 Unauthorized, will result from formal errors in the call to the web service, like missing non-optional data or invalid credentials.

will output

A user, or a company with many users, can have address books in the service, with contacts that each contain a phone number that can receive SMS messages and/or an email address and/or an address to the contact’s address in a mobile app. These contacts can be marked with tags consisting of a tag type and a tag value. For instance, a contact can be marked with the tag Base:STO if the person is based in Stockholm. The same contact can have many tags, for instance Group:Management or On call:Yes. Which tags types and tag values are used is up to the user/company, but they should preferably consist of letters and numbers, and can especially not contain the characters ;, | or :. A tag filter in this interface consists of a list of filter parts, which are connected by logical AND (a contact is selected only if it fulfills every part of the filter). A filter part consists of a tag type and a list of tag values. A contact fulfills the filter part criterion if it has a tag with the given tag type and one of the given tag values (logical OR). Filters can be given either as a string in GET or POST or as a json document in the POST input. Using the string notation, the example contact would fulfill a Base:STO|OSL|CPH;On call:Yes filter, which consists of two filter parts, one saying that the contact needs to have a Base:STO or a Base:OSL or a Base:CPH tag, and the other that the contact needs to have an On call:Yes tag. Note that filter parts are separated by a semicolon, tag type and tag values are separated by a colon and tag values are separated by vertical bars (UNIX pipe symbols).

Which address book to use for the tag filter selections will in most cases have been set when setting the user’s settings for the job type in question (discussed in more detail below).

When a tag filter or group/distribution list is part of the saved job, or added as a to-parameter, the address book will be searched for the correct recipients at the time of starting the job from this API, so that any recent changes in the address book will affect the resulting recipient list. That means that, for instance, employees that left the company will not get the new message, provided that they have been cleared from the company address book. There is no way of accessing the exact recipients that would have been found at the point of time when the job was saved when address book searching of groups and tag filters is employed. In contrast, if the saved job explicitly lists individual recipients or phone numbers, the address book will not be searched for whether they are still present, and any employees that left the company will still get the message. This is a major advantage of only using tag filters and groups/distribution lists in saved jobs.

The web form for starting a job of the type in question, which is also where the job was originally saved, has access to a settings page. There, certain aspects of the job are controlled. Note that the settings are not saved with the job, but instead the most up-to-date settings for the job type are used when starting a job using this API. This can lead to unexpected results if settings are often changed, but for a typical user of the Dispatch API, a standard job of the job type is saved and settings for that job type are input at one point, and thereafter the API is used repeatedly with the same saved job and settings. In future versions, additional API parameters for overriding some of the current settings are planned.

This callback is sent when a starting account (agent) starts a job with an id owned by an account (with id userid) of a certain jobtype.

This callback is sent when the system assigns a recipient with a name sendname, an address book contact id (contactid) and a sendtaskid (internal to the system, mainly for support) to a task within the job with an id owned by an account (with id userid) of a certain jobtype.