Messages

Message attributes

Whispir’s API customers who have message attributes configured within the Whispir platform can simplify their API message requests by using the message attributes directly from the API.

Using message attributes allows developers to focus on the data behind a message, rather than focusing on the presentation or messaging channels within the message. This separation ensures that, for example, the marketing or communications teams within an organisation can focus on what they do best, and the developers can ensure that system integrations are working as effectively as possible.

Example:
A message contains some content and a potential variable (such as the expiry of the invitation):

Reminder: Your invitation to the Acme Event will expire on 13/06/2019.

The API call to populate this without message attributes could look as shown in the code example.

  • JSON
  • XML

Sending an invitation message

{{codeStart}} 

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"to" : "john@api-example.com",

"subject" : "Reminder:",

"body" : "Your invitation to the Acme Event will expire on 13/06/2019.",

"email" : {

"type" : "text/plain",

"body" : "Your invitation to the Acme Event will expire on 13/06/2019."

}

}

{{codeEnd}}

Using templates to add attributes

Using message attributes and message templates allows developers to cleanly separate these responsibilities. This is done by combining the message channels being used for the message and the data driving the message.

Example:
The same message as in the previous example is saved into a Whispir message template (see code example).

  • JSON
  • XML

Using templates to add attributes

{{codeStart}}

HTTP 1.1 POST http://api.<region>.whispir.com/templates?apikey=<[your_api_key>

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"messageTemplateName" : "Event Reminder",

"subject" : "Reminder:",

"body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.",

"email" : {

"type" : "text/plain",

"body" : "Your invitation to the Acme Event will expire on @@event_expiry@@."

}

}

{{codeEnd}}

Response - template created

{{codeStart}}

HTTP 1.1 201 Created

Location: http://api.<region>.whispir.com/templates/DACADB02209CC93C

{

"id": "DACADB02209CC93C",

"messageTemplateName" : "Event Reminder",

"subject" : "Reminder:",

"body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.",

"email" : {

"type" : "text/plain",

"body" : "Your invitation to the Acme Event will expire on @@event_expiry@@."

}

}

{{codeEnd}}

Using template (with attributes) to send the message

{{codeStart}}

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"to" : "john@api-example.com",

"messageTemplateId" : "DACADB02209CC93C",

"messageattributes" : {

"attribute" : [{

"name" : "event_expiry",

"value" : "13/06/2019"

}]

}

}

{{codeEnd}}

Using template (with more than 1 attribute) to send the message

{{codeStart}}

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"to" : "john@api-example.com",

"messageTemplateId" : "DACADB02209CC93C",

"messageattributes" : {

"attribute" : [{

"name" : "event_expiry",

"value" : "13/06/2019"

},{

"name" : "event_expiry_time",

"value" : "23:59:59"

}]

}

}

{{codeEnd}}

 

Using this message template ID and now using the message attribute @@event_expiry@@, the updated code example (combining the message template and message attribute) is far simpler to implement and is more efficient.

Notes:

  • User-defined attributes available through the API are configured at the account level and require Whispir administrative assistance to enable.
  • You can start using user-defined attributes through the API by contacting your Whispir account manager or the Whispir Support Team.