Getting started

Connect to the API

The first thing you’ll need to do is generate your Authorisation header for your API requests. You’ll need to use the Authorisation header on every request that you submit to the developers.whispir.com API.

Note: Whispir uses Basic HTTP Authentication for all API requests.

You can generate the Authorisation header in most programming languages very easily. However, for convenience you can generate it here by filling in the form below.

Note: Your Whispir authentication information is not submitted or stored. It’s only used as part of an algorithm to automatically generate your header.

Authorization Header:


Once you’ve 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 programming language, a curl script or a generic REST client

Connect using a programming language

developers.whispir.com provides some basic code samples in a range of languages to assist users in getting started with the API. Once you’ve created your app in the developers.whispir.com dashboard, click the Code tab on the left side of the screen.

Select the app and the action that you want to perform (for example, Send an SMS message). This automatically generates the code for you. You can copy this code into your IDE, import any required dependencies and run it.

You will need to replace the following elements of the request:

  1. App API key
  2. Authorisation header
  3. Recipient information
  4. Message subject
  5. Message content

Once you’ve verified that you have replaced all of these, run the request in your IDE and you’ll receive your first message using the developers.whispir.com API.

Using cURL

cURL is a computer software project providing a library and command-line tool for transferring data using various protocols. One key use of cURL is to make HTTP requests.

In order to test your ability to use the developers.whispir.com API, cURL is a very quick mechanism to enter into a command line interface and make sure everything is set up correctly.

Using a generic REST client

If you’re unsure about using cURL, you can install a REST client in your browser and test the calls through there. Whispir recommends the following clients:

To test your connectivity, enter the following parameters:

  • The URL that you would like to request.
  • Your app API key.
  • Your Authorisation header.
  • (optional) The Content-Type/Accept Headers.

The HTTP call will look like this:

GET https://api.<region>.whispir.com?apikey=89asdfohasd89023rsd

... with the following headers (as a minimum):

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk and x-api-key: 89asdfohasd89023rsd

Once you have executed this request, you should receive a 200 OK response from the REST client. This means that you have connectivity to the developers.whispir.com API and can start building your app.

If you received a different response, continue to the next section to understand how to resolve your issues.

Resolving connectivity issues

If you get a response other 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 browsing to developers.whispir.com and clicking Log In
  • If you can't log in it’s possible that your account isn’t active. Contact your Whispir Company Administrator or send an email to the Whispir Support Team.

Other HTTP errors or no connectivity at all

If you’re still having issues contact the Whispir Support Team.

  • JSON
  • XML

Connect to the API

Using the information above, you can execute the following cURL statement:

{{codeStart}}

curl -H "Authorization: <Your Authorization Header>" -H "x-api-key: <YOUR API KEY>"

https://api.<region>.whispir.com?apikey=<Your API Key>

# with sample values

curl -H "Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk" -H "x-api-key: 89asdfohasd89023rsd"

https://api.<region>.whispir.com?apikey=89asdfohasd89023rsd

# If all is correct, the following response should be expected (The API defaults to an XML response)

<?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="https://api.<region>.whispir.com/workspaces?apikey=89asdfohasd89023rsd"/>

...

</ns2:company>

{{codeEnd}}

Note: When you change your password you’ll need a new authorization header.