Using Workspaces
Using Workspaces
Using Workspaces, application developers are able to create new work areas for the varying use cases of each application.
Each of these work areas provides different functions and capabilities that can be provided to users of the application, e.g. creating messages, executing scenarios, or viewing distribution lists.
The following details describe how application developers can use the Workspaces through Whispir’s API.
- How to retrieve a list of Workspaces
- How to retrieve a single Workspace
- How to create new Workspaces
- How to update an existing Workspace
- How to delete an existing Workspace
How to retrieve a list of Workspaces
Name |
Value |
|
Service URL |
||
Method |
GET |
|
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
Accept |
application/vnd.whispir.workspace-v1+xml |
|
Query String |
apikey= |
The Mashery API key to authenticate the request. |
Response |
200 OK |
The request was processed successfully |
401 Unauthorized |
The authorization details were incorrect |
|
415 Unsupported Media Type |
The MIME type requested is not supported for the requested resource |
Request/Response Example
After performing this request, the response contains a list of URLs to each of the Workspaces that the API user has access to.
Each URL is stored within a 'Link' element. Each 'Link' element that is returned contains the following information:
Element Name |
Description |
Method |
The HTTP Method that is available on this particular URI |
Rel |
The searchable description about what this URI should be used for. |
URI | The URI in focus. This can be used by the developer to perform some action on the resource. |
Type (Optional) | When the type is update or create, the applicable Content Type header and Accept header are supplied for the developer to use. |
This information allows the application client to traverse the available resources easily:
HTTP1.1 GET https://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS Authorization: Basic asdf98nf89asdvasd2r398h8sdf Accept: application/vnd.whispir.workspace-v1+xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com"> <status>1 to 1 of 1</status> <ns2:workspaces> <ns2:workspace> <projectName>Community Recovery</projectName> <projectNumber></projectNumber> <status>A</status> <billingcostcentre></billingcostcentre> <ns2:link method="GET" rel="self" uri="https://api.whispir.com/workspaces/A4F978D7485B73A2?apikey=DFD0FD90u809SDF90832FDS"/> </ns2:workspace> </ns2:workspaces> </ns2:return>
The elements returned in the response are described as follows:
Element Name |
Description |
projectName |
The name of the Workspace. |
projectNumber |
The ID of the workspace. |
status |
The status of the Workspace: |
billingcostcentre | Only applicable to customers with the Billing Cost Centre Module enabled. Shows the billing cost centre set for the Workspace. |
link | The URL for the user/application to access this specific workspace. |
How to retrieve a single Workspace
Name |
Value |
|
Service URL |
||
Method |
GET |
|
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
Accept |
application/vnd.whispir.workspace-v1+xml |
|
Query String |
apikey= |
The Mashery API key to authenticate the request. |
Response |
200 OK |
The request was processed successfully |
401 Unauthorized |
The authorization details were incorrect |
|
404 Not Found |
The requested resource specified by the ID in the URL was not found, most likely this ID does not exist or has been deleted |
|
415 Unsupported Media Type |
The MIME type requested is not supported for the requested resource |
Request/Response Example
The response returns the specific details of the Workspace that the API user requested.
HTTP 1.1 GET https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=<your api key> Authorization: Basic asdf98nf89asdvasd2r398h8sdf Accept: application/vnd.whispir.workspace-v1+xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:workspace xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com/"> <projectName>Community Recovery</projectName> <projectNumber></projectNumber> <status>A</status> <billingcostcentre></billingcostcentre> <link method="GET" rel="retrieveMessage" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/messages?apikey=<your api key>"/> <link method="POST" rel="createMessage" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/messages?apikey=<your api key>" type="application/vnd.whispir.message-v1+xml, application/vnd.whispir.message-v1+json"/> <link method="GET" rel="retrieveContacts" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/contacts?apikey=<your api key>"/> <link method="POST" rel="createContact" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/contacts?apikey=<your api key>" type="application/vnd.whispir.contact-v1+xml, application/vnd.whispir.contact-v1+json"/> <link method="POST" rel="createUser" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/users?apikey=<your api key>" type="application/vnd.whispir.user-v1+xml, application/vnd.whispir.user-v1+json"/> <link method="GET" rel="retrieveUsers" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/users?apikey=<your api key>"/> <link method="POST" rel="createTemplate" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/templates?apikey=<your api key>" type="application/vnd.whispir.template-v1+xml, application/vnd.whispir.template-v1+json"/> <link method="GET" rel="retrieveTemplates" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/templates?apikey=<your api key>"/> <link method="POST" rel="createDistList" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/distributionlists?apikey=<your api key>" type="application/vnd.whispir.distributionlist-v1+xml, application/vnd.whispir.distributionlist-v1+json"/> <link method="GET" rel="retrieveDistLists" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/distributionlists?apikey=<your api key>"/> <link method="POST" rel="createScenario" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/scenarios?apikey=<your api key>" type="application/vnd.whispir.scenario-v1+xml, application/vnd.whispir.scenario-v1+json"/> <link method="GET" rel="retrieveScenarios" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/scenarios?apikey=<your api key>"/> <link method="GET" rel="retrieveResponseRules" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/responserules?apikey=<your api key>"/> <link method="POST" rel="createResponseRule" uri="http://api.whispir.com/workspaces/CFEF25E421A69BC4/responserules?apikey=<your api key>" type="application/vnd.whispir.responserule-v1+xml, application/vnd.whispir.responserule-v1+json"/> </ns3:workspace>
This response shows all of the available functions that the user can perform from within this Workspace. Think of this response as the website navigation. Each URL returned allows the user to perform a different function, as in visit a different web page.
Each URL is stored within a 'Link' element, and each 'Link' element that is returned contains the following information:
Function |
Rel |
URI |
Method |
Retrieve a listing of messages |
retrieveMessage | http://api.whispir.com/workspaces/[id]/messages | GET |
Create a new Message | createMessage |
POST |
|
Retrieve a listing of contacts | retrieveContacts | http://api.whispir.com/workspaces/[id]/contacts | GET |
Create a new contact | createContact | http://api.whispir.com/workspaces/[id]/contacts | POST |
Retrieve a listing of users | retrieveUsers | http://api.whispir.com/workspaces/[id]/users | GET |
Create a new user | createUser | http://api.whispir.com/workspaces/[id]/users | POST |
Retrieve a listing of message templates | retrieveTemplates | http://api.whispir.com/workspaces/[id]/templates | GET |
Create a new message template | createTemplate | http://api.whispir.com/workspaces/[id]/templates | POST |
Retrieve a listing of distribution lists | retrieveDistLists | http://api.whispir.com/workspaces/[id]/distributionlists | GET |
Create a new distribution list | createDistList | http://api.whispir.com/workspaces/[id]/distributionlists | POST |
Retrieve a listing of scenarios | retrieveScenarios | http://api.whispir.com/workspaces/[id]/scenarios | GET |
Create a new scenario | createScenario | http://api.whispir.com/workspaces/[id]/scenarios | POST |
Retrieve a listing of Response Rules | retrieveResponseRules | http://api.whispir.com/workspaces/[id]/responserules | GET |
Create a new Response Rule | createResponseRule | http://api.whispir.com/workspaces/[id]/responserules | POST |
Each of these URIs can be accessed using the REL and appropriate METHOD to perform the specified functionality.
How to create a new Workspace
Name |
Value |
|
Service URL |
||
Method |
POST |
|
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
Accept |
application/vnd.whispir.workspace-v1+xml |
|
Content-Type |
application/vnd.whispir.workspace-v1+xml |
|
Query String |
apikey= |
The Mashery API key to authenticate the request. |
Response |
202 Accepted |
The request has been accepted for processing |
401 Unauthorized |
The authorization details were incorrect |
|
415 Unsupported Media Type |
The MIME type requested is not supported for the requested resource |
Request/Response Example
The example below shows the Workspace that the API user is requesting to have created in the Whispir Platform.
There is no limit to the amount of workspaces each API user can create.
HTTP 1.1 POST https://api.whispir.com/workspaces?apikey= Authorization: Basic asdf98nf89asdvasd2r398h8sdf Accept: application/vnd.whispir.workspace-v1+xml Content-Type: application/vnd.whispir.workspace-v1+xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:workspace xmlns:ns2=http://schemas.api.whispir.com/dap xmlns:ns3="http://schemas.api.whispir.com"> <projectName>Sandbox 3</projectName> <projectNumber></projectNumber> <status>A</status> <billingcostcentre></billingcostcentre> </ns3:workspace>
The elements required in the request are described as follows:
Element Name |
Description |
projectName (mandatory) |
The name of the Workspace to be created. |
projectNumber (optional) |
The ID of the workspace, generally not used. |
status (mandatory) | The status of the Workspace being created. This should be 'A' for 'Active' when creating new workspaces. |
billingcostcentre (optional) | Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace. |
How to update an existing Workspace
This is useful if you are wanting to change the name of a workspace, or update some detail e.g. Workspace ID (projectNumber).
Name |
Value |
|
Service URL |
||
Method |
PUT |
|
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
Accept |
application/vnd.whispir.workspace-v1+xml |
|
Content-Type |
application/vnd.whispir.workspace-v1+xml |
|
Query String |
apikey= |
The Mashery API key to authenticate the request. |
Response |
204 No Content |
The request has been processed and no content was returned. This is a successful update. |
401 Unauthorized |
The authorization details were incorrect |
|
404 Not Found |
The resource specified in the URI could not be updated because it could not be found. |
|
415 Unsupported Media Type |
The MIME type requested is not supported for the requested resource |
Request/Response Example
The example XML shows the Workspace that the API user is requesting to have updated.
Note that the URL that is being specified in the request is locating a specific Workspace with the ID: CFEF25E421A69BC4. This is telling the API, here is the Workspace that I want to update, and here is the information that I want to update it with.
HTTP 1.1 PUT https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey= Authorization: Basic asdf98nf89asdvasd2r398h8sdf Accept: application/vnd.whispir.workspace-v1+xml Content-Type: application/vnd.whispir.workspace-v1+xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:workspace xmlns:ns2=http://schemas.api.whispir.com/dap xmlns:ns3="http://schemas.api.whispir.com"> <projectName>Sandbox 3</projectName> <projectNumber></projectNumber> <status>A</status> <billingcostcentre></billingcostcentre> </ns3:workspace>
The elements required in the request are described as follows:
Element Name |
Description |
projectName (mandatory) |
The name of the Workspace to be created. |
projectNumber (optional) |
The ID of the workspace, generally not used. |
status (mandatory) | The status of the Workspace being created. This should be 'A' for 'Active' when creating new workspaces. |
billingcostcentre (optional) | Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace. |
When using PUT it is important to remember that it is a replacement of the existing information. All information supplied in the body of the request will be used to replace the existing information. If you leave a field blank, it will remove the existing information.
Note: Performing a PUT on the Workspace does not modify any of the contents of the Workspace e.g. Templates or Distribution Lists. This operation only modifies the details of the actual Workspace.
How to delete an existing Workspace
Please be very careful when deleting Workspaces as this operation is irreversable.
Name |
Value |
|
Service URL |
||
Method |
DELETE |
|
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
Query String |
apikey= |
The Mashery API key to authenticate the request. |
Response |
204 No Content |
The DELETE request has been accepted for processing |
401 Unauthorized |
The authorization details were incorrect |
|
404 Not Found |
The workspace ID specified in the URI could not be deleted because it does not exist. |
Request/Response Example
The example XML shows the Workspace that the API user is requesting to be deleted
HTTP 1.1 DELETE https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=<your api key> Authorization: Basic asdf98nf89asdvasd2r398h8sdf
The DELETE request does not require any information to be supplied in the body, it is simply sending a DELETE to a URL.
Whispir will immediately delete all of the information within this Workspace, and this operation is irreversable (aside from restoring from backups which may result in support costs).
If you require more information about deleting Workspaces, please contact apisupport@whispir.com. or post a message in the forum.
Value |
||||
Service URL |
||||
Method |
GET |
|||
Request Headers |
Authorization |
The Base 64 representation of the Whispir Username and Password. |
|
|
Accept |
application/vnd.whispir.workspace-v1+xml application/vnd.whispir.workspace-v1+json |
|
||
Query String |
apikey= |
The Mashery API key to authenticate the request. |
||
limit= |
The number of results to return in the query |
|||
offset= |
The number from the first result to start returning records |
|||
name= |
The Name of the workspace to return |
|||
description= |
The description of the workspace to return |
|||
Response |
200 OK |
The request was processed successfully |
||
401 Unauthorized |
The authorization details were incorrect |
|||
404 Not Found |
The requested resource was not found |
|||
415 Unsupported Media Type |
The MIME type requested is not supported for the requested resource |
Docs Navigation
- Whispir API Features
- Quick Start Guide
- Sending Messages
- Advanced Messages
- Sending Dynamic Messages
- Message Status
- Message Responses
- Whispir API Callbacks
- API Architecture
- API Security
- Content Types & Versioning
- Resources
- Using the Company Workspace
- Using Workspaces
- Using Contacts
- Using Whispir to Manage Events
- Authoring Rich Push Messages