Key Management

Access to Dispatch's API is controlled through the use of API keys. Clients can be granted one or more API Keys. API keys can be generated through the Client Settings panel.

Key

The API key you will use for authorization

Label

A label to help you identify where you use the key. You can set the label after the key has been generated by editing the key.

Age

How long it has been since the key was generated. API Keys should be rotated on a regular basis. You can have multiple active keys at a time.

Last Used

How long ago the API Key was used in a request. This value is updated once a day.

Security

Authentication

Two authentication methods are supported: HTTP Basic Authentication and a custom HTTP header.

• HTTP Basic Authentication: Your username is your client name (visible to the right of 'Client' in the navigation bar. Your password is the API key obtained from your client settings.
• Custom HTTP Header: A custom HTTP header can also be used for authentication. This is required if you are using the Java SDK available in UIOWA-Commons. For each request to Dispatch's API, just add the HTTP header x-dispatch-api-key with the API key as its value.

Encryption

Communication over HTTPS is required.

API Reference

Go to API Reference Documentation for using Dispatch's API.

SDK libraries

Java SDK

There is a Dispatch SDK available which is available publicly.

For ITS-AIS developers, you can see additional documentation at the commons-dispatch project.

Other languages

There is not a supported SDK for other languages like C#, Python, Ruby, or Php. You can just call the API via standard HTTP requests.

Examples

Example: Send to a communication with an AdHoc population.

The following example will send a message immediately using the Communication AdHoc endpoint. The recipients can be dynamic.

Python

import json
import requests
from requests.auth import HTTPBasicAuth

# Method to send a notification via Dispatch
def send_notification(data):
    # Define the bits necessary for communication with Dispatch
    dispatch_communication_id = "" # The ID of your communication
    dispatch_communication_url = "https://apps.its.uiowa.edu/dispatch/api/v1/communications/" + dispatch_communication_id + "/adhocs"
    dispatch_client = "" # The client name
    dispatch_key = "" # The API key found in Client Settings

    # Transform the data so it matches what Dispatch needs
    dispatch_payload = dict()
    dispatch_payload['members'] = data

    dispatch_json = json.dumps(dispatch_payload)

    # Send request to Dispatch
    r = requests.post(url=dispatch_communication_url,
                      data=dispatch_json,
                      auth=HTTPBasicAuth(dispatch_client, dispatch_key))

    # Throw error if we got anything other than a 200
    r.raise_for_status()

if __name__ == "__main__":
    # Construct the dict of the member attributes
    member = dict()
    member['toAddress'] = "herky-hawk@uiowa.edu" # toAddress is required if you are sending an email
    member['toPhone'] = "+13193351000" # toPhone is required if you are sending a SMS
    member['toName'] = "Herky Hawk"
    member['anotherProperty'] = "Something else"
    member['anotherUniqueProperty'] = "One more thing"

    members = [member]

    # Call the method to make the request to Dispatch
    send_notification(members)

Java

import uiowa.dispatch.*;

public class DispatchScheduleExample {
    public static void main(String[] args) {
        //Create the Dispatch client
        Dispatch dispatch = new Dispatch(Dispatch.Environment.PROD, "my-api-key");

        //Find your client
        Client client = dispatch.clients.getFirst(Client.Filter.NAME, "my-client-name");

        //Locate your campaign
        Campaign campaign = client.campaigns.getFirst(Campaign.Filter.NAME, "my-campaign-name");

        //Find your communication
        Communication communication = campaign.communications.getFirst(Communication.Filter.NAME, "my-communication-name");

        //Scheduling a batch of messages using a pre-configured population
        Schedule schedule = new Schedule(Schedule.Occurrence.ONE_TIME, new Date());
        communication.schedules.create(schedule);

        System.out.println("Communication scheduled");
    }
}

Example: Schedule a batch to execute

This example will trigger a one-time execution of a communication using the Communication Schedule endpoint. You probably want to make sure that if you are invoking the schedule API to send a batch, you also enable Bypass Approval setting in the Communication setup.

Python

import json
import requests
from datetime import datetime
from requests.auth import HTTPBasicAuth

# Method to trigger a scheduled batch via Dispatch
def schedule_dispatch_batch():
    # Define the bits necessary for communication with Dispatch
    dispatch_communication_id = "" # The ID of your communication
    dispatch_communication_url = "https://apps.its.uiowa.edu/dispatch/api/v1/communications/" + dispatch_communication_id + "/schedules"
    dispatch_client = "" # The client name
    dispatch_key = "" # The API key found in Client Settings

    # Construct the payload to create the schedule
    schedule = dict()
    schedule['occurrence'] = "ONE_TIME"
    schedule['startTime'] =  datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") # The date/time you want the batch to go in YYYY-MM-DD HH:mm:ss format.
    schedule['businessDaysOnly'] = False
    schedule['includeBatchResponse'] = True
    schedule['createPublicArchive'] = False;

    dispatch_json = json.dumps(schedule)

    # Send request to Dispatch
    r = requests.post(url=dispatch_communication_url,
                      data=dispatch_json,
                      auth=HTTPBasicAuth(dispatch_client, dispatch_key))

    # Throw error if we got anything other than a 200
    r.raise_for_status()

if __name__ == "__main__":
    # Call the method to make the request to Dispatch
    schedule_dispatch_batch()

Java

import uiowa.dispatch.*;

public class DisaptchAdHocExample {
    public static void main(String[] args) {
        //Create the Dispatch client
        Dispatch dispatch = new Dispatch(Dispatch.Environment.PROD, "my-api-key");

        //Find your client
        Client client = dispatch.clients.getFirst(Client.Filter.NAME, "my-client-name");

        //Locate your campaign
        Campaign campaign = client.campaigns.getFirst(Campaign.Filter.NAME, "my-campaign-name");

        //Find your communication
        Communication communication = campaign.communications.getFirst(Communication.Filter.NAME, "my-communication-name");

        //Create an array of members
        ArrayList members = new ArrayList<Map<String,String>>();

        //Add a member to that array
        Map<String,String> map = new HashMap<>();
        map.put("toAddress", "herky-hawk@uiowa.edu");
        map.put("toName", "Herky Hawk");
        map.put("customAttribute", "Foo Bar");
        members.add(map);

        //Construct the AdHoc population
        Adhoc adhoc = new Adhoc();
        adhoc.members = members;

        //and Send it
        communication.adhocs.create(adhoc);

        System.out.println("Communication sent.");
    }
}