Quick Start Guide

Quick Start Guide - Get started using Whispir's API

To get started using the Whispir API, you'll need a few things:

  1. Register with Whispir.io
  2. Check your connectivity to the API
  3. Try it out! Send an SMS Message
  4. Start building your application!

Step 1 - Register with Whispir.io

There are 2 options available to get access to the Whispir API:

Existing Users

If you're already a Whispir customer, great! Your existing username and password will work straight away.  You don't even need to contact us.  Simply use your Username and Password to the Whispir Platform to generate your Basic Authentication and you'll already have access to the API.

New Users

To start using the API, head over to whispir.io and register for your free 30 day trial. No credit card required.

The username and password that you enter into this form will be what you use to generate your Basic Authentication.

Once you've got your Whispir Username and Password, you're ready to move to Step 2.

Step 2 - Check your connectivity to the API

The first thing you'll need to do is generate the Authorization Header for your API requests. You'll need to use this on every request that you submit to the Whispir API.

Whispir is currently using BASIC HTTP Authentication, with a view of OAuth 2.0 in the future.

You can generate this header by filling in the form below.  

Note: Your Whispir authentication information is not submitted or stored anywhere, it is only used as part of the algorithm to automatically generate the header.

Whispir Username: 
Whispir Password: 

Authorization Header: 

Once you have generated this header, you can use it in a request to the API.  This will ensure everything is working correctly.  To do this you can use a cURL script, or another generic REST client.

Using cURL

Using the information above, you can use the following cURL script: 

curl -H "Authorization: <Your Authorization Header>" http://api.whispir.com?apikey=<Your API Key>

e.g.

curl -H "Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk" http://api.whispir.com?apikey=89asdfohasd89023rsdfhio8923 

If all is well, you should get back a HTTP 200OK and the body of the response will be the Company resource in XML. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:company xmlns="http://schemas.api.whispir.com/dap" xmlns:ns2="http://schemas.api.whispir.com">
    <link method="GET" rel="retrieveWorkspaces" uri="http://api.whispir.com/workspaces?apikey=<your API key>"/>
    ...
</ns2:company>

This may look a bit scary at first, but it will all make sense shortly. All you need to know now is you've got access to the API!

Using a generic REST Client

If you're unsure about using cURL, you can install a REST Client plugin in your browser and test the calls through there.  You recommend using the RESTClient plugin for Firefox (https://addons.mozilla.org/en-US/firefox/addon/restclient/).

To test your connectivity, you need to enter your Whispir username and password and provide the API URL that you would like to call.

The HTTP call will look more like the following:

HTTP 1.1 GET http://api.whispir.com?apikey=89asdfohasd89023rsdfhio8923 
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

You should still get the same response as above.

Resolving connectivity issues

If you get a different response than HTTP 200 OK, perform the following:

HTTP 403 Forbidden, or HTTP 401 Unauthorized

  • Your Authorization header may not be quite right, verify your username and password by logging in to Whispir,
  • Try and re-generate the Base64 encoded username and password using the form above. 

Other HTTP errors or no connectivity at all

If you're still having issues, contact us at support@whispir.io

Step 3: Try it out! Send an SMS message using the API

By now you should be able to connect to the API and can issue requests and receive responses. Based on this, you can now send your first SMS message using the API.

This is very similar to the previous request, but instead of using a HTTP GET to retrieve information, this time you're going to use a HTTP POST to push information to Whispir. 

As you're sending a message, you need to tell Whispir who to send it to, and what the content is.

You're going to use the URL http://api.whispir.com/messages as the API endpoint. 

For example:

HTTP 1.1 POST http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923 
Authorization: BASIC am9obi5zbWl0aDpteXBhc3N3b3Jk

The next thing you need to do is tell Whispir what information you're sending.  You can just blindly send some XML or JSON content, but life is much easier if Whispir knows exatly what it is you are sending.

You're going to tell Whispir what you are sending by using the Content-Type HTTP header.  As you are going to send your message content using JSON, your Content-Type header is going to be: application/vnd.whispir.message-v1+json.

This tells Whispir that you are sending content that conforms to Version 1 of the message schema.  As Whispir adds more features to each schema, our version numbers will increase, this is described in much more detail later on in the documentation.

So now your request looks as follows:

HTTP 1.1 POST http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923
Authorization: BASIC am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.message-v1+json

Now you need to tell Whispir what to send back to you as a response.  By default the API will respond with XML, but lets say you want to receive your response in JSON.  To do this, you'll use the Accept HTTP Header.  The value for the Accept header is going to be: application/vnd.whispir.message-v1+json (the same as the Content-Type header).

So now your request looks as follows:

HTTP 1.1 POST http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923
Authorization: BASIC am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json

Almost there! Now you just need to provide some content to send.  The simplest message that can be sent is an SMS.  It must contain the following information:

  • To - the recipient of the message
  • Subject - The first line of the SMS
  • Body - The content of the message

Given this information, the request could look as follows:

HTTP 1.1 POST http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923
Authorization: BASIC am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.message-v1+json
Accept: application/vnd.whispir.message-v1+json
{
"to": "<DESTINATION PHONE NUMBER>", 
"subject": "This is the first line of my SMS",
"body": "This is the content of my SMS"
}

Or in cURL:

curl -H "Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk" 
-H "Content-Type: application/vnd.whispir.message-v1+json" 
-H "Accept: application/vnd.whispir.message-v1+json" 
-d '{ "to": "<DESTINATION PHONE NUMBER>",
"subject": "This is the first line of my SMS",
"body": "This is the content of my SMS"
}' 
http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923

Once you submit this, Whispir will send you back an HTTP 202 Accepted stating that your request has been accepted for processing.  Within a few seconds your phone should be buzzing away.

Update: Some users have reported the curl statement used above does not work in Windows versions of curl.  You may need to escape the double quote characters with backslashes to ge this to work e.g.

curl -H "Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk" 
-H "Content-Type: application/vnd.whispir.message-v1+json" 
-H "Accept: application/vnd.whispir.message-v1+json" 
-d "{ \"to\": \"<DESTINATION PHONE NUMBER>\",
\"subject\": \"This is the first line of my SMS\",
\"body\": \"This is the content of my SMS\"
}" 
http://api.whispir.com/messages?apikey=89asdfohasd89023rsdfhio8923

Thats it for the quick start guide. 


Step 4: Start building your application!

For more information on Messages and all the other Whispir resources please continue through the documentation, or browse straight to Sending Messages for more information.