Messages

Communications are at the core of what the developers.whispir.com API offers as a service to customers.

Whispir can send communications across 8 different channels in a single API request:

  • SMS: Up to 1600* characters per message, premium routes, delivery receipts.
  • Email: Free email messaging with HTML and plain text support.
  • Voice: High quality outbound voice calls delivered to mobile and landline phones within seconds.
  • Rich messages: Personalised, targeted rich messaging to drive conversations.
  • Push: Easily send push notifications to your apps.
  • Twitter: Support for instant publishing to multiple Twitter accounts.
  • Facebook: Simplify the process of publishing to multiple facebook accounts instantaneously.
  • RSS: Easily generate RSS feeds for consumption by other services.

*SMS character counts are limited in some countries. Contact your local Whispir account manager for information about the supported number of characters in your region.

All communications are driven from the /messages endpoint within the API. This endpoint allows a user to perform the following tasks:

  • Create and send a new message in a given workspace
  • Retrieve a list of previously sent messages in the given workspace

These are described in more detail below.

As message resources can exist in the default (‘Company’) workspace or other workspace, messages have two access URLs:

  • https://api.<region>.whispir.com/messages: For company workspace messages
  • https://api.<region>.whispir.com/workspaces/:id/messages: For other workspace messages where :id is the ID of the specific workspace.

Whispir strongly recommends that you use workspaces for all your messaging needs. If you don’t, it may lead to billing and data privacy concerns within your company account. See Workspaces.

High-level request elements

to

String

Specifies the recipients of the message. For example:

  • Mobile phone: 61423456789
  • Email address: john.smith@test.com.au
  • Landline: 61386000000

Note: Multiple recipients can be specified by separating them with semicolons (;).

subject

String

Specifies the first line of the SMS message or voice call, and the subject of the email message.

body

String

Specifies the content of the SMS message.

email

Object

The Email object is described further down in this section. Used for sending email messages.

voice

Object

The Voice object is described further down in this section. Used for sending voice calls to mobile phones and landlines.

web

Object

The Web object is described further down in this section. Used for web publishing and rich messages.

social

Object

The Social object is described further down in this section. Used for publishing content to social media (Twitter, Facebook, LinkedIn).

type

String

Allows the user to modify the message behaviour for replies. For example:

  • defaultNoReply: Used to reject any replies to this message. It’s also used to mask the sender’s phone number when not using a message alias.

dlr

Object

Allows the user to turn ON or OFF the DLRs (delivery receipts) via the ‘type’ option. For example:

  • NoDlr: Used to specify that DLRs should not be enabled for this message.

Usage:

  • for XML: NoDlr
  • for JSON: "dlr":{ "type": "NoDlr" }

senderAlias

String
Allows to set the alias dynamically for the current message without the need for using a template or Alias Manager.

However, to use this feature, you should be at minimum on the Enterprise Licence, and should provide the alias details to Whispir beforehand for approval.

features

Object

Allows the user to modify the push notifications properties if these are configured in the company.

pushOptions:

  • notifications: Enabled/disabled.
  • escalationMins: The number of minutes to wait for a push notification response.
  • appId: The appId that the push notification has to be sent to.
  • JSON
  • XML

API endpoint

The following calls describe how to access messages from within your workspaces:

 

{{codeStart}}

# From the default workspace 

https://api.<region>.whispir.com/messages/?apikey=<your_api_key> Accept: application/vnd.whispir.message-v1+json

  

# Or from a defined workspace

https://api.<region>.whispir.com/workspaces/{:id}/messages/?apikey=<your_api_key> Content-Type: application/vnd.whispir.message-v1+json

{{codeEnd}}

  

The following resource types are supported for messages:

application/vnd.whispir.message-v1+xml
application/vnd.whispir.message-v1+json

 

The following methods are supported for the /messages endpoint:

GET
POST
DELETE

 

Messages

Sample to send an SMS, email, voice message and web publishing in one request:

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic <YOUR AUTH HEADER>

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "+1000000000",

"subject" : "Test Message",

"body" : "This is the body of my test SMS message",

"email" : {

"body" : "This is the body of my test Email message",

"footer" : "This is the footer of my message

(generally where a signature would go)",

"type" : "text/plain"

},

"voice" : {

"header" : "This is the introduction,

read out prior to any key press",

"body" : "This is the body of the voice call,

read out after the key press",

"type" : "ConfCall:,

ConfAccountNo:,

ConfPinNo:,

ConfModPinNo:,

Pin:"

},

"web" : {

"body" : "This is the content of my web publishing

or Rich Push Message",

"type" : "text/plain"

},

"social" : {

"social" : [

{

"id" : "social",

"body" : "Twitter Content."

},

{

"id" : "social_long",

"body" : "Facebook Content.",

"type" : "text/plain"

}

]

},

"type" : "defaultNoReply",

"features" : {

"pushOptions" : {

"notifications" : "enabled",

"escalationMins" : "3"

}

}

}

{{codeEnd}}