An introduction to the use of the Shoutlet Developer API, including details of authentication and common API features.
About the API
The Shoutlet developer API provides a wide range of methods that allow you to create and manipulate many features of the Shoutlet system from within applications running on your own network. The API is exposed as a number of RESTful web services, allowing it to be accessed via any programming language that has an HTTP library available. Additionally, at a later date we shall be releasing API Client SDKs for a number of languages, allowing developers to use the API via local procedure calls or method invocations. For security reasons, an SSL connection should be used for all API calls.
The first method that you'll encounter will be shoutlet_time, a simple parameterless method that returns as its results the current Unix epoch time on the Shoutlet server that requires no authentication. We prefer that you use shoutlet_time at least for the initial authentication simply to help avoid possible synchronization issues. If you're calling the API from a machine that uses NTP to ensure accurate time, the clock skew is likely to be minimal. The exact method used to do this is detailed on the appropriate page of this documentation.
There are four parameters and two return values that are common to all Shoutlet API methods. These four parameters are required in every API method call and are detailed in the standard parameter list below.
Every call to the API, with the notable exception of the Single-Sign on method, includes two standard fields in its result data. Although all of the examples in this guide show these as being the first two fields in the XML return data (and the first two (key, value) pairs in the JSON results) these may appear anywhere at the top level of the returned data. This is expected behavior with JSON (where no order on the values in a tuple is defined) but may cause confusion when parsing XML return data. The standard returned fields are described in the standard results below.
There are four parameters and two return values that are common to all Shoutlet API methods. These four parameters are required in every API method call.
- apikey (required string)
- The Shoutlet API key that you have generated for the application.
- timestamp (required integer)
- The current Shoutlet epoch time. This can be obtained via the shoutlet_time method, from the timestamp returned by most methods or, if your server clock is accurate, via a local system call.
- sha_hash (required string)
- This is a SHA-512 digest obtained by concatenating the following values in the order specified:
- the API key you passed as the first parameter
- the timestamp (as used for the second parameter)
- your API secret
- the name of the method you are calling
- mode (required string)
- error (integer)
- This field is always present. If no error occurred, the value of this field will be 0, otherwise it will be set to 1 and the result will also include a message field describing the error.
- time (integer)
- A Basic Guide To Shouts
- Your primary means of getting information to your customers is the shout. Any type of shout that can be created from the user interface can also be created via the API, so it's possible to have your own system generate simple text messages, upload or reference video clips, upload or reference audio files, or just send an image. These can then be shouted to any combination of valid channels that you want to send them to. The API calls are particularly useful where you want to communicate the same information to a large number of channels, some of which are limited in the formats of data they can take. Please Note: All Shouts created through our API are scheduled in the Central Time Zone. No user timezones will impact Shouts.
- Working With Profiles
- If you need to work with your Shoutlet profile list from an external application, these calls are available. It's possible to create or modify existing profiles, find out what information you do or don't have for a profile, list the different segments that you've separated your profiles into, and export profile data for a particular segment for use in an external application.
- Managing Connections
- Managing third-party API connections is a key component of the Shoutlet systems. An account's connection to Facebook, Twitter, Youtube and a variety of other services can be managed via the API. The Shoutlet API provides several methods for managing connections to these external APIs focusing on listing, editing and assinging variables to connections.
- Using The Social Switchboard
- The social switchboard provides a powerful mechanism for triggering activities based on a wide range of events within the system. The API to the switchboard is intended to make it possible for external applications to trigger such events, thus integrating them into Shoutlet.
- Working With Contests
- The Shoutlet contest platform provides an engaging and social means of interacting with your followers. The API for the contest allows you to work directly with the system.
- Knowing Your Customers
- While it's very useful to be able to get messages out to your customers, it's just as important to be able to find out the response your information is getting - who is reading it, whether it's getting a lot of views, is the response to it positive, has it gone viral? The Shoutlet analytical API calls provide the means to do this. Currently it's possible to retrieve analytical data for both Twitter and Facebook. Please note that due to the sheer volume of data that these services make accessible to you, the API methods are rather more complex than most of those currently in the API - they may only take a single method-specific parameter, but that parameter contains a potentially complex JSON data structure specifying exactly what information you want to retrieve.
- Enterprise Accounts
- These methods are of use to Enterprise account customers who may need to manage numerous sub-accounts and users programmatically. The API allows, for example, local representatives to have access to the system in a controlled way, or to limit the resources to which certain users have access. By doing so, they considerably reduce the effort required to maintain large numbers of Shoutlet resources.
- Utility Methods
- Some API methods only purpose it to make life easier for the API developer and don't fit with other actions that you might want to take with the Shoutlet API. Shoutlet's API provides a Single Sign-On mechanism whereby external applications can create links to authenticate Shoutlet users bypassing the login screen. This is primarily so that external applications can redirect users to specific sections of the Shoutlet UI without having to require the user to authenticate themselves repeatedly. The other utility calls provide help with checking the current API version, getting what time Shoutlet thinks it is and testing your API connection routines.