Native message variables

When sending messages using the Whispir API you can automatically customise your communications including recipients information as part of the message. This is facilitated by the Whispir's native message variables [or native tags] that will be resolved against the recipients MRIs

IMPORTANT: the following tags can be included in any SMS, email or voice message. They are NOT meant to be used in rich messages. In this case recipient-specific fields can be populated using the Whispir JavaScript API. See Rich Messages for an example

Native Contacts tags


Recipient’s first name.

For example, John.


Recipient’s last name.

For example, Smith.


Recipient’s primary email address.

For example,


Recipient’s primary mobile phone number.

For example, 61400400400.


Recipient’s primary phone number for voice calls.

For example, 61400400400.


Whispir message retrieval service call back PIN (only populated when voice is used).

For example, 1234.


Resolves to the recipient’s ‘Role’ field.

For example, Manager.


Resolves to the recipient’s ‘Additional Role’ field.

For example, Team Leader.


Resolves to the recipient’s ‘Team Name’ field.

For example, Red Team.


Resolves to the label field of the sent message.

For example, Incident #1234.


Resolves to the list of categories used in the message, separated with commas.

For example, Product Update.

  • JSON
  • XML


# To call from a User-defined workspace

POST https://api.<region> 

# To call from the default workspace

POST https://api.<region>


Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

Accept: application/vnd.whispir.message-v1+json



"to" : "",

"subject" : "Test SMS Message with tags",

"body" : "Hi @@first_name@@. This is your message."



The main difference with the examples seen so far is given here by the to field of the payloads

Request Body Details


Defined Whispir recipients

  • Contact MRI:
  • User MRI:
  • Distribution List MRI:

Native system tags

When sending messages using the Whispir API, you can automatically include system-generated information via system variables. Each of them will resolve to the value obtained when you send the message. Unlike the preceding ones, they don't depend from the Contacts information stored in Whispir, so they can be included also in messages where the recipients are not represented by their MRI


Current day with leading zero.

For example, 08.


Current month with leading zero.

For example, 06.


Current year, short form.

For example, 19.


Current year, long form.

For example, 2019.


Day in spoken form.

For example, Wednesday.


Month in spoken form.

For example, June.


Current hour with leading zero, in 24 hour format.

For example, 16.


Current minute with leading zero.

For example, 07.


Current date in format (yyyy-mm-dd)

For example, 2019-02-02.


Current time in 24-hour format.

For example, 14:37.