TalkBox has a self-contained voucher system which allows TalkBox users to create, issue and redeem vouchers. Vouchers can be delivered via QR code or a string code in a TalkBox communication, this is the normal method for issuing a voucher to a contact.
Vouchers can be redeemed:
- Scanning with a mobile device camera,
- Directly in the TalkBox web application,
- By any suitably capable external application.
This article described how to write an external application that can read and redeem TalkBox vouchers.
Using the TalkBox API
The TalkBox API has two resources related to vouchers, these are offers and vouchers. Offers are the configuration of vouchers in TalkBox, where as vouchers relate to the individual vouchers issued to individuals.
For the purposes of this integration vouchers resource will be used to read and redeem vouchers. However, using offers external applications could also create new TalkBox voucher configurations.
Requesting Voucher Data
External applications can request TalkBox voucher data three ways:
- Scanning the voucher QR code from the recipients device or printed version.
- Looking up TalkBox vouchers based on contacts parameters (email, mobile, or external ID if account is in mirror mode.
- Looking up a TalkBox voucher based on the voucher string code
Looking Up Vouchers for a Contact
Some external applications may look for TalkBox vouchers for a contact without scanning a TalkBox voucher QR code. This could be, for example, for display within a mobile application or at a kiosk or POS terminal.
Using a GET request to /vouchers the vouchers and associated contact can be retrieved in one request by using a contact parameter and optionally a status parameter.
Contact parameter options:
- contact_id – the internal TalkBox ID for the contact.
- email – the email address for the contact.
- mobile – the mobile number for the contact.
- external_id – the external system ID for the contact (if the TalkBox account is in mirror mode)
Mirror mode is a mode of TalkBox where contacts are uniquely identified using their ID in an integrated external system. Read the understanding mirror mode article for more information and contact the account owner if you’re unsure of the account mode.
Status parameter options:
- redeemed – only returns redeemed vouchers
- redeemable – only returns voucher that are currently redeemable.
Example request:
https://talkbox.impactapp.com.au/service/v1/vouchers?external_identifier=abc123
The response is a json array of vouchers, for example:
{
"name":"Free Pie",
"description":"Footscray store only",
"created_at":"2016-07-08T13:45:55+10:00",
"redeemed_at":null,
"valid_to":null,
"valid_from":null,
"expires_at":"2016-08-09T00:00:00+10:00",
"user_data":{
},
"status":"redeemable",
"url":"https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
"contact_id":1,
"communication_id":2,
"promotion_id":3,
"external_identifier":"abc123"
}Scanning Voucher Codes
TalkBox vouchers are rendered as QR codes in communications to contacts. This is how vouchers are issued and delivered.
The QR codes resolve to URLs that return JSON data comprising all relevant information required by an external redemption application.
The following is an actual TalkBox voucher QR code:
This resolves to the URL:
Using a GET request to this URL returns the following JSON. This contains all data relevant to the voucher.
You will need to include “Accept: application/json” in your header.
Below is the JSON body for the above URL:
{
"name":"Free Pie",
"description":"Footscray store only",
"created_at":"2016-07-08T13:45:55+10:00",
"redeemed_at":null,
"valid_to":null,
"valid_from":null,
"expires_at":"2016-08-09T00:00:00+10:00",
"user_data":{
},
"status":"redeemable",
"url":"https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
"contact_id":1,
"communication_id":2,
"promotion_id":3,
"external_identifier":"abc123"
}Looking Up a Voucher using String Code
Read how to look up a TalkBox voucher based on the voucher string code here
Voucher Data Response
The parameters returned in a voucher data response will display all required information regarding a voucher. The parameters are:
| Name | Data Type | Optional |
| name | string | false |
| description | string | true |
| user_data | hash | true |
| created_at | date_time | false |
| valid_from | date_time | true |
| valid_to | date_time | true |
| expires_at | date_time | true |
| valid_weekdays | array | true |
| valid_time | array | true |
| redeemed_at | date_time | true |
| status | string | false |
Utilising User Data
The user_data field is available to store arbitrary key-value pairs that are meaningful to the external system redeeming the voucher. The data stored in this field has no functional meaning in TalkBox but can be useful to inform the system how to handle the voucher.
For example the user_data field may be configured to contain the data the system requires to know what kind of internal promotion or discount should be applied when the voucher is redeemed.
Any key and value can be placed here as long as it’s meaningful externally, for example: system_discount_code = 1
Handling of Voucher Status
A voucher request can return the following possible statuses:
- Redeemable = voucher is currently able to be redeemed.
- Redeemed = voucher has already been redeemed.
- Before_valid_period = voucher is not yet valid for redemption (date is in the future).
- After_valid_period = voucher has expired.
- Violates_weekday_time_restriction = voucher is not currently redeemable due to the weekday and/or time restrictions.
Valid Period
Voucher validity period can be set three ways in TalkBox:
- Never expires.
- Expires after N days.
- Valid from DATE to DATE.
This validity will always be expressed in the JSON body using valid_to and valid_from parameters below:
- If the voucher never expires the valid_to and valid_from will be NULL.
- If the voucher expires after N day valid_to will be returned and valid_from will be NULL.
- If the voucher is valid for a set date range valid_to and valid_from will both be returned.
Weekday & Time Restrictions
A voucher can be restricted by weekdays (Monday – Sunday) and by a time range in TalkBox.
These restrictions are expressed in the JSON body using valid_weekdays and valid_time parameters as below:
- If the voucher if valid for all weekdays valid_weekdays will return all days in an array.
- If the voucher if valid for some weekdays valid_weekdays will return the days valid in an array.
- If the voucher is valid for all time valid_time will be NULL.
- If the voucher is valid for only some times valid_time will return two values in an array. The first value will be the start time and the second value will be the end time.
Note: times returned in valid_time will be in local time for the venue as set in the TalkBox account.
Redeeming a Voucher
Once the external system has retrieved the voucher information and is able to validate the voucher as redeemable the voucher can be redeemed in TalkBox to complete the process.
A TalkBox voucher can be redeemed by an external system by issuing a PUT request to the URL from the QR code with the parameter voucher[redeemed]=1. If the voucher is successfully redeemed the server will respond with HTTP 200 and return the JSON data for the voucher; this time redeemed_at will have a value.