ToastWorx API v1.0.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Welcome to the ToastWorx API documentation.
Get started by POST-ing to /accounts to create a new ToastWorx account and your first channel.
Use the apiKeyFull returned from the POST request to authenticate requests to all of the API endpoints - see Authentication below for details.
Share your channel's QR code provided at the qrCodeURL with your subscribers so they can join the channel.
POST to the /channels/{channelUUID}/toasts endpoint to send rich push notifications to all your channel subscribers.
Take a look at our demo pages (1, 2, 3, 4, 5, 6) to see examples of how to combine different toast elements.
Please do contact us if we can help in any way!
Base URL:
Authentication
We use Bearer authentication for requests to the ToastWorx API endpoints.
When your account is created you receive two API keys: apiKeyFull and apiKeyReadOnly. Authenticate your requests by passing one of these keys in the Authorization header as "Bearer {your-api-key}". We suggest you use apiKeyFull to get started.
You can rotate your API keys by calling the /rotate endpoint.
Note: all requests require authentication apart from the request to create an account.
Accounts
The /accounts endpoint is for managing your overall Account. POST to /accounts to create a new account. GET /accounts/{accountUUID} to retrieve the account details as well as all channels on the account.
Create an account
Code samples
curl -X POST https://api.toastworx.com/accounts \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
const inputBody = '{
"name": "My Account Name",
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"user": {
"name": "Jane",
"email": "jane@example.com",
"password": "XXXXXXXX"
},
"channel": {
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.toastworx.com/accounts',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/accounts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.toastworx.com/accounts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://api.toastworx.com/accounts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/accounts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /accounts
Create a new account. Also creates the first channel for this account.
The details of the owner of this account (email and password) must be provided. Other fields such as account name and channel details are optional and can then be updated later through a PATCH request.
Body parameter
{
"name": "My Account Name",
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"user": {
"name": "Jane",
"email": "jane@example.com",
"password": "XXXXXXXX"
},
"channel": {
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
name | body | string | false | Accoutn name |
callbackURL | body | string | false | Optional callback URL that receives POST events when subscribers tap on callback buttons |
user | body | NewUser | false | New user values. Email and password required. |
» name | body | string | false | Optional user name |
body | string | true | User email | |
» password | body | string | true | User password |
channel | body | NewChannel | false | Optional new channel values |
» name | body | string | false | none |
» description | body | string | false | none |
» iconURL | body | string | false | none |
» infoURL | body | string | false | none |
Example responses
200 Response
{
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Account |
List all accounts
Code samples
curl -X GET https://api.toastworx.com/accounts \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/accounts',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/accounts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/accounts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/accounts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/accounts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /accounts
Get the accounts and channels associated with the API key - will always return just one account
Example responses
200 Response
[
{
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [Account] | false | none | [Account information] |
» uuid | string | false | none | Unique identifier for this account |
» name | string | false | none | Account name |
» apiKeyFull | string | false | none | Account API key - full access |
» apiKeyReadOnly | string | false | none | Account API Key - read only access |
» maxChannels | integer(int64) | false | none | The maximum number of channels for this account |
» maxSubscribersPerChannel | integer(int64) | false | none | The maximum number of subscribers per channel for this account |
» maxToastsPerMonth | integer(int32) | false | none | The maximum number of toasts that can be sent per 30 day period |
» toastExpiryDays | integer(int32) | false | none | The number of days before toasts on this account expire |
» maxUsers | integer(int64) | false | none | The maximum number of users for this account |
» callbackURL | string | false | none | Optional callback URL that receives POST events when subscribers tap on callback buttons |
» isDemo | boolean | false | none | Flag indicating if this is a demonstration account |
» channels | [Channel] | false | none | The channels for this account |
»» uuid | string | false | none | Unique identifier for this channel |
»» name | string | false | none | Channel name |
»» description | string | false | none | Optional channel description |
»» qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
»» iconURL | string | false | none | Optional icon for this channel |
»» infoURL | string | false | none | Optional link to more information about this channel |
»» isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
»» timestamp | integer(int32) | false | none | Timestamp when this channel was created |
Retrieve an account
Code samples
curl -X GET https://api.toastworx.com/accounts/{accountUUID} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/accounts/{accountUUID}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/accounts/{accountUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/accounts/{accountUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/accounts/{accountUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/accounts/{accountUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts/{accountUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /accounts/{accountUUID}
Get the account details including a list of all channels on this account
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Account |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Update an account
Code samples
curl -X PATCH https://api.toastworx.com/accounts/{accountUUID} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "My New Account Name"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/accounts/{accountUUID}',
{
method: 'PATCH',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PATCH','https://api.toastworx.com/accounts/{accountUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.patch('https://api.toastworx.com/accounts/{accountUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.patch 'https://api.toastworx.com/accounts/{accountUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PATCH", "https://api.toastworx.com/accounts/{accountUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts/{accountUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
PATCH /accounts/{accountUUID}
Uppdate the account name
Body parameter
{
"name": "My New Account Name"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountUUID | path | string | true | none |
name | body | string | false | none |
Example responses
200 Response
{
"uuid": "2dc92910-d87b-486c-933e-9c8977636c9e"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» uuid | string | false | none | The account UUID |
Delete an account
Code samples
curl -X DELETE https://api.toastworx.com/accounts/{accountUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/accounts/{accountUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/accounts/{accountUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/accounts/{accountUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/accounts/{accountUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/accounts/{accountUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts/{accountUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /accounts/{accountUUID}
Delete this account including all channels, toasts and subscribers.
Caution - this cannot be undone!
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Rotate API keys
Code samples
curl -X PUT https://api.toastworx.com/accounts/{accountUUID}/rotate \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/accounts/{accountUUID}/rotate',
{
method: 'PUT',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PUT','https://api.toastworx.com/accounts/{accountUUID}/rotate', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.put('https://api.toastworx.com/accounts/{accountUUID}/rotate', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.put 'https://api.toastworx.com/accounts/{accountUUID}/rotate',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PUT", "https://api.toastworx.com/accounts/{accountUUID}/rotate", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/accounts/{accountUUID}/rotate");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
PUT /accounts/{accountUUID}/rotate
Rotate the API keys on the account - creates new apiKeyFull and apiKeyReadOnly
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Account |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Channels
End-users subscribe to your Channel by scanning the channel's QR code - provided in the qrCodeURL field.
You send Toasts to all channel subscribers by POST-ing to the /channels/{channelUUID}/toasts endpoint.
Create a new channel by POST-ing to the /channels endpoint.
Create a channel
Code samples
curl -X POST https://api.toastworx.com/channels \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/channels', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.post('https://api.toastworx.com/channels', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.post 'https://api.toastworx.com/channels',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/channels", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /channels
Create a new channel on this account.
The request body can be left blank and defaults will be used instead. These can then be updated later through a PATCH request. Alternatively provide channel name and other optional fields to customise the channel setup.
Body parameter
{
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | NewChannel | false | none |
name | body | string | false | none |
description | body | string | false | none |
iconURL | body | string | false | none |
infoURL | body | string | false | none |
Example responses
200 Response
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Channel |
401 | Unauthorized | unauthorised - invalid API token | None |
402 | Payment Required | account has reached limit of maximum number of channels | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
List all channels
Code samples
curl -X GET https://api.toastworx.com/channels \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/channels', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/channels', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/channels',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/channels", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /channels
Get all the channels for this account
Example responses
200 Response
[
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221,
"subscriberCount": 51,
"toastCount": 173
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [ChannelWithCounts] | false | none | [Channel information including number of channel subscribers and channel toasts] |
» uuid | string | false | none | Unique identifier for this channel |
» name | string | false | none | Channel name |
» description | string | false | none | Optional channel description |
» qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
» iconURL | string | false | none | Optional icon for this channel |
» infoURL | string | false | none | Optional link to more information about this channel |
» isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
» timestamp | integer(int32) | false | none | Timestamp when this channel was created |
» subscriberCount | integer(int32) | false | none | Number of channel subscribers |
» toastCount | integer(int32) | false | none | Number of channel toasts |
Retrieve a channel
Code samples
curl -X GET https://api.toastworx.com/channels/{channelUUID} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/channels/{channelUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/channels/{channelUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/channels/{channelUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/channels/{channelUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /channels/{channelUUID}
Get the information for this channel
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221,
"subscriberCount": 51,
"toastCount": 173
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | ChannelWithCounts |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Update a channel
Code samples
curl -X PATCH https://api.toastworx.com/channels/{channelUUID} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}',
{
method: 'PATCH',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PATCH','https://api.toastworx.com/channels/{channelUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.patch('https://api.toastworx.com/channels/{channelUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.patch 'https://api.toastworx.com/channels/{channelUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PATCH", "https://api.toastworx.com/channels/{channelUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
PATCH /channels/{channelUUID}
Update the channel name, description, iconURL or infoURL
Body parameter
{
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
body | body | NewChannel | true | none |
name | body | string | false | none |
description | body | string | false | none |
iconURL | body | string | false | none |
infoURL | body | string | false | none |
Example responses
200 Response
{
"uuid": "2dc92910-d87b-486c-933e-9c8977636c9e"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» uuid | string | false | none | The channel UUID |
Delete a channel
Code samples
curl -X DELETE https://api.toastworx.com/channels/{channelUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/channels/{channelUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/channels/{channelUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/channels/{channelUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/channels/{channelUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /channels/{channelUUID}
Delete this channel. Removes all subscribers to the channel and all toasts.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
Create a toast
Code samples
curl -X POST https://api.toastworx.com/channels/{channelUUID}/toasts \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/toasts',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/channels/{channelUUID}/toasts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.post('https://api.toastworx.com/channels/{channelUUID}/toasts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.post 'https://api.toastworx.com/channels/{channelUUID}/toasts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/channels/{channelUUID}/toasts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/toasts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /channels/{channelUUID}/toasts
Create a new toast on this channel. The toast will be sent to all the channel subscribers.
We support 12 different types of toast content which can be combined together to create a rich message to end users - text, email, url, telephone, SMS, maps, webviews, callbacks, charts, images, json and spacers. Take a look at our demo pages (1, 2, 3, 4, 5, 6) to see the content types in action.
The simplest content is 'text'. Set the 'type' to 'text', set the 'text' to the message you want to send, optionally set the 'style' to one of 4 text styles - headline, subhead, body or footnote.
The different content types have their own payloads. See the definitions of the content types and payloads below.
Body parameter
{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
]
}
alert: Here is your word of the day
sound: toaster 1
content:
- type: text
text: Nalebinding - A fabric creation technique predating knitting and crochet.
style: body
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
body | body | NewToast | true | none |
alert | body | string | true | The message shown on the mobile app as a push notification |
sound | body | ToastSound | false | The sound played when this notification is received on the mobile app |
content | body | [anyOf] | false | The payload for this toast, up to 10kb, as a JSON array |
» anonymous | body | ToastElementText | false | Displays text with one of four styles. See this demo for an example of different text elements. |
»» type | body | string | true | none |
»» text | body | string | true | none |
»» style | body | string | false | none |
» anonymous | body | ToastElementEmail | false | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the email address |
»» to | body | string | true | Email address. Provide multiple email addresses separated by commas. |
»» subject | body | string | false | Optional email subject |
»» body | body | string | false | Optional email body |
» anonymous | body | ToastElementUrl | false | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
»» type | body | string | false | none |
»» title | body | string | false | Optional title shown above the URL |
»» url | body | string | false | The link URL to show |
» anonymous | body | ToastElementTel | false | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the telephone number |
»» number | body | string | true | The telephone number to call. Include + with country code for international calling. |
» anonymous | body | ToastElementSms | false | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the SMS number |
»» to | body | string | true | SMS number. Provide multiple numbers separated by commas. |
»» body | body | string | false | Optional SMS body |
» anonymous | body | ToastElementMap | false | Displays a map centred on a location you provide. See this demo for an example map. |
»» type | body | string | true | none |
»» lat | body | number(double) | true | Latitude of the location |
»» lng | body | number(double) | true | Longitude of the location |
»» zoom | body | integer(int32) | false | Zoom level for the map between 1 and 20. Defaults to 10. |
»» height | body | integer(int32) | false | Optional map height in pixels. Defaults to 300px. |
»» style | body | string | false | none |
»» isZoomEnabled | body | boolean | false | none |
»» isScrollEnabled | body | boolean | false | none |
» anonymous | body | ToastElementWebview | false | Displays an embedded web page. |
»» type | body | string | true | none |
»» url | body | string | true | The URL for the webpage |
»» height | body | integer(int32) | false | Optional webpage height in pixels. Defaults to 300px. |
» anonymous | body | ToastElementCallback | false | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
»» type | body | string | true | none |
»» titles | body | [string] | true | An array of string labels for the callback buttons. Maximum of 4 buttons. |
»» identifiers | body | [string] | true | An array of string identifiers for the callback buttons. These enable you to identify which callback button was pressed. |
» anonymous | body | ToastElementChart | false | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
»» type | body | string | true | none |
»» chartType | body | string | true | The type of chart to display |
»» title | body | string | false | Optional chart title |
»» xAxis | body | string | false | Optional chart x axis title |
»» yAxis | body | string | false | Optional chart y axis title |
»» xAxisType | body | string | false | Optional time format for x axis using timestamps |
»» markerSize | body | integer(int32) | false | Optional marker size for line and scatter charts. Defaults to 3px. |
»» height | body | integer(int32) | false | Optional chart in pixels. Defaults to 300px. |
»» legend | body | boolean | false | none |
»» dataset | body | [array] | true | none |
»»» anonymous | body | [string] | false | none |
»»» anonymous | body | [number] | false | Array of data items. First value is x axis, 2..n values are the different y values. Use unix timestamps in seconds for x-axis values and set xAxisType to one of sec, min, hour, day, month for time series data. |
»»» anonymous | body | [allOf] | false | Array with two items for the pie chart. The first item is the value and the second item is the label. |
»»»» anonymous | body | number | false | none |
»»»» anonymous | body | string | false | none |
anonymous | body | ToastElementImageUrl | false | Displays an image in the toast. See this demo for an example. |
type | body | string | true | none |
url | body | string | true | Image URL - the image is pulled from the URL |
anonymous | body | ToastElementJson | false | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
type | body | string | true | none |
json | body | object | true | The JSON object to display. Supports standard JSON data types. |
anonymous | body | ToastElementSpacer | false | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
type | body | string | true | none |
height | body | integer(int32) | false | Spacer height in pixels. Defaults to 10px. |
Enumerated Values
Parameter | Value |
---|---|
»» type | text |
»» style | headline |
»» style | subhead |
»» style | body |
»» style | footnote |
»» type | |
»» type | url |
»» type | tel |
»» type | sms |
»» type | map |
»» style | standard |
»» style | satellite |
»» style | hybrid |
»» type | webview |
»» type | callback |
»» type | chart |
»» chartType | line |
»» chartType | bar |
»» chartType | horizontalbar |
»» chartType | pie |
»» chartType | scatter |
»» xAxisType | sec |
»» xAxisType | min |
»» xAxisType | hour |
»» xAxisType | day |
»» xAxisType | month |
type | image |
type | json |
type | spacer |
Example responses
200 Response
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"pushCount": 45
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | ToastUUIDWithPushCount |
401 | Unauthorized | unauthorised - invalid API token | None |
402 | Payment Required | account has reached limit of maximum toasts in a 30 day period (maxToastsPerMonth setting) | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
422 | Unprocessable Entity | unprocessable request body - see msg for details | None |
List all channel toasts
Code samples
curl -X GET https://api.toastworx.com/channels/{channelUUID}/toasts \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/toasts',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/channels/{channelUUID}/toasts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/channels/{channelUUID}/toasts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/channels/{channelUUID}/toasts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/channels/{channelUUID}/toasts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/toasts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /channels/{channelUUID}/toasts
Get all the toasts for this channel
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
],
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | ToastWithCounts |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Delete all toasts
Code samples
curl -X DELETE https://api.toastworx.com/channels/{channelUUID}/toasts \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/toasts',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/channels/{channelUUID}/toasts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/channels/{channelUUID}/toasts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/channels/{channelUUID}/toasts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/channels/{channelUUID}/toasts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/toasts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /channels/{channelUUID}/toasts
Delete all the toasts on this channel
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
List all channel subscribers
Code samples
curl -X GET https://api.toastworx.com/channels/{channelUUID}/subscribers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/subscribers',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/channels/{channelUUID}/subscribers', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/channels/{channelUUID}/subscribers', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/channels/{channelUUID}/subscribers',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/channels/{channelUUID}/subscribers", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/subscribers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /channels/{channelUUID}/subscribers
Get all the subscribers for this channel
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Example responses
200 Response
[
{
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f",
"name": "Unnamed",
"deviceName": "iPad Pro",
"deviceModel": "iPad",
"countryCode": "US",
"appVersion": 1
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [Subscriber] | false | none | none |
» uuid | string | false | none | Unique identifier for this subscriber |
» name | string | false | none | Optional name set by the subscriber |
» deviceName | string | false | none | The subscriber's device name as reported by the device |
» deviceModel | string | false | none | The subscriber's device model as reported by the device |
» countryCode | string | false | none | The subscriber's ISO 3166 two digit country code as reported by the device |
» appVersion | string | false | none | The version of the ToastWorx app this subscriber is using |
Delete a channel subscriber
Code samples
curl -X DELETE https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/subscribers/{subscriberUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /channels/{channelUUID}/subscribers/{subscriberUUID}
Remove this subscriber from this channel
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
subscriberUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or subscriber not found | None |
List all channel subscriber events
Code samples
curl -X GET https://api.toastworx.com/channels/{channelUUID}/events \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/events',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/channels/{channelUUID}/events', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/channels/{channelUUID}/events', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/channels/{channelUUID}/events',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/channels/{channelUUID}/events", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /channels/{channelUUID}/events
Get the subscriber events for this channel - didSubscribe, didUnsubscribe, didDeleteSubscriber, didMute, didUnmute
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Example responses
200 Response
[
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didSubscribe",
"timestamp": 1595725890,
"subscriber": {
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f"
}
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [ChannelEvent] | false | none | none |
» uuid | string | false | none | Unique identifier for this event |
» eventType | string | false | none | Subscriber event type for this channel |
» timestamp | integer(int32) | false | none | Timestamp when this event occurred |
» subscriber | object | false | none | none |
»» uuid | string | false | none | Unique identifier for this subscriber |
Enumerated Values
Property | Value |
---|---|
eventType | didSubscribe |
eventType | didUnsubscribe |
eventType | didDeleteSubscriber |
eventType | didMute |
eventType | didUnmute |
Set default channel
Code samples
curl -X PUT https://api.toastworx.com/channels/{channelUUID}/default \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/channels/{channelUUID}/default',
{
method: 'PUT',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PUT','https://api.toastworx.com/channels/{channelUUID}/default', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.put('https://api.toastworx.com/channels/{channelUUID}/default', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.put 'https://api.toastworx.com/channels/{channelUUID}/default',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PUT", "https://api.toastworx.com/channels/{channelUUID}/default", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/channels/{channelUUID}/default");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
PUT /channels/{channelUUID}/default
The default channel is set initially as the first channel created on the account. Use this request to set the specified channel to be the default channel.
The default channel is used when you create a toast by POST-ing to the /toasts endpoint. This is a convenience feature to allow you to create a toast without needing the channel UUID.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
channelUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Toasts
Toasts are the messages you send to your channel subscribers. Toasts can be a simple text alert or can be rich messages combining many elements like charts, images and maps, and can include actions and callbacks to allow subscribers to respond to a Toast.
Toasts belong to a channel and so you create them by POST-ing to the /channels/{channelUUID}/toasts endpoint. The /toasts endpoint allows you to list, retrieve and delete toasts.
Create toast on default channel
Code samples
curl -X POST https://api.toastworx.com/toasts \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/toasts',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/toasts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.post('https://api.toastworx.com/toasts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.post 'https://api.toastworx.com/toasts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/toasts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/toasts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /toasts
Create a new toast on the default channel.
This is a convenience endpoint to allow toasts to be sent without needing the channel UUID. The default channel is set initially as the first channel created and can be changed by calling the /default endpoint - details here.
See Create a toast for more info on toast creation.
Body parameter
{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
]
}
alert: Here is your word of the day
sound: toaster 1
content:
- type: text
text: Nalebinding - A fabric creation technique predating knitting and crochet.
style: body
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | NewToast | true | none |
alert | body | string | true | The message shown on the mobile app as a push notification |
sound | body | ToastSound | false | The sound played when this notification is received on the mobile app |
content | body | [anyOf] | false | The payload for this toast, up to 10kb, as a JSON array |
» anonymous | body | ToastElementText | false | Displays text with one of four styles. See this demo for an example of different text elements. |
»» type | body | string | true | none |
»» text | body | string | true | none |
»» style | body | string | false | none |
» anonymous | body | ToastElementEmail | false | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the email address |
»» to | body | string | true | Email address. Provide multiple email addresses separated by commas. |
»» subject | body | string | false | Optional email subject |
»» body | body | string | false | Optional email body |
» anonymous | body | ToastElementUrl | false | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
»» type | body | string | false | none |
»» title | body | string | false | Optional title shown above the URL |
»» url | body | string | false | The link URL to show |
» anonymous | body | ToastElementTel | false | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the telephone number |
»» number | body | string | true | The telephone number to call. Include + with country code for international calling. |
» anonymous | body | ToastElementSms | false | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
»» type | body | string | true | none |
»» title | body | string | false | Optional title shown above the SMS number |
»» to | body | string | true | SMS number. Provide multiple numbers separated by commas. |
»» body | body | string | false | Optional SMS body |
» anonymous | body | ToastElementMap | false | Displays a map centred on a location you provide. See this demo for an example map. |
»» type | body | string | true | none |
»» lat | body | number(double) | true | Latitude of the location |
»» lng | body | number(double) | true | Longitude of the location |
»» zoom | body | integer(int32) | false | Zoom level for the map between 1 and 20. Defaults to 10. |
»» height | body | integer(int32) | false | Optional map height in pixels. Defaults to 300px. |
»» style | body | string | false | none |
»» isZoomEnabled | body | boolean | false | none |
»» isScrollEnabled | body | boolean | false | none |
» anonymous | body | ToastElementWebview | false | Displays an embedded web page. |
»» type | body | string | true | none |
»» url | body | string | true | The URL for the webpage |
»» height | body | integer(int32) | false | Optional webpage height in pixels. Defaults to 300px. |
» anonymous | body | ToastElementCallback | false | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
»» type | body | string | true | none |
»» titles | body | [string] | true | An array of string labels for the callback buttons. Maximum of 4 buttons. |
»» identifiers | body | [string] | true | An array of string identifiers for the callback buttons. These enable you to identify which callback button was pressed. |
» anonymous | body | ToastElementChart | false | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
»» type | body | string | true | none |
»» chartType | body | string | true | The type of chart to display |
»» title | body | string | false | Optional chart title |
»» xAxis | body | string | false | Optional chart x axis title |
»» yAxis | body | string | false | Optional chart y axis title |
»» xAxisType | body | string | false | Optional time format for x axis using timestamps |
»» markerSize | body | integer(int32) | false | Optional marker size for line and scatter charts. Defaults to 3px. |
»» height | body | integer(int32) | false | Optional chart in pixels. Defaults to 300px. |
»» legend | body | boolean | false | none |
»» dataset | body | [array] | true | none |
»»» anonymous | body | [string] | false | none |
»»» anonymous | body | [number] | false | Array of data items. First value is x axis, 2..n values are the different y values. Use unix timestamps in seconds for x-axis values and set xAxisType to one of sec, min, hour, day, month for time series data. |
»»» anonymous | body | [allOf] | false | Array with two items for the pie chart. The first item is the value and the second item is the label. |
»»»» anonymous | body | number | false | none |
»»»» anonymous | body | string | false | none |
anonymous | body | ToastElementImageUrl | false | Displays an image in the toast. See this demo for an example. |
type | body | string | true | none |
url | body | string | true | Image URL - the image is pulled from the URL |
anonymous | body | ToastElementJson | false | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
type | body | string | true | none |
json | body | object | true | The JSON object to display. Supports standard JSON data types. |
anonymous | body | ToastElementSpacer | false | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
type | body | string | true | none |
height | body | integer(int32) | false | Spacer height in pixels. Defaults to 10px. |
Enumerated Values
Parameter | Value |
---|---|
»» type | text |
»» style | headline |
»» style | subhead |
»» style | body |
»» style | footnote |
»» type | |
»» type | url |
»» type | tel |
»» type | sms |
»» type | map |
»» style | standard |
»» style | satellite |
»» style | hybrid |
»» type | webview |
»» type | callback |
»» type | chart |
»» chartType | line |
»» chartType | bar |
»» chartType | horizontalbar |
»» chartType | pie |
»» chartType | scatter |
»» xAxisType | sec |
»» xAxisType | min |
»» xAxisType | hour |
»» xAxisType | day |
»» xAxisType | month |
type | image |
type | json |
type | spacer |
Example responses
200 Response
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"pushCount": 45
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | ToastUUIDWithPushCount |
401 | Unauthorized | unauthorised - invalid API token | None |
402 | Payment Required | account has reached limit of maximum toasts in a 30 day period (maxToastsPerMonth setting) | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or default channel not found | None |
422 | Unprocessable Entity | unprocessable request body - see msg for details | None |
List all toasts
Code samples
curl -X GET https://api.toastworx.com/toasts \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/toasts',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/toasts', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/toasts', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/toasts',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/toasts", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/toasts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /toasts
Get all the toasts for this account, grouped by channel
Example responses
200 Response
[
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221,
"toasts": [
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
]
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [ChannelWithToasts] | false | none | none |
» uuid | string | false | none | Unique identifier for this channel |
» name | string | false | none | Channel name |
» description | string | false | none | Optional channel description |
» qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
» iconURL | string | false | none | Optional icon for this channel |
» infoURL | string | false | none | Optional link to more information about this channel |
» isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
» timestamp | integer(int32) | false | none | Timestamp when this channel was created |
» toasts | [ToastWithElementTypeAndCounts] | false | none | The toasts for this channel |
»» uuid | string | false | none | Unique identifier for this toast |
»» alert | string | false | none | The title of the push notification |
»» sound | ToastSound | false | none | The sound played when the subscriber receives this toast |
»» contentTypes | [ToastElementType] | false | none | Toast contentTypes |
»» timestamp | integer(int32) | false | none | Timestamp when this toast was created |
»» hasExpired | boolean | false | none | Flag indicating whether this toast has past the toastExpiryDays since creation |
»» pushCount | integer(int32) | false | none | Number of subscribers this toast was pushed to |
»» didReceiveCount | integer(int32) | false | none | Number of subscribers that received this toast |
»» didReadCount | integer(int32) | false | none | Number of subscribers that read this toast |
Retrieve a toast
Code samples
curl -X GET https://api.toastworx.com/toasts/{toastUUID} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/toasts/{toastUUID}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/toasts/{toastUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/toasts/{toastUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/toasts/{toastUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/toasts/{toastUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/toasts/{toastUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /toasts/{toastUUID}
Get the information for this toast
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
toastUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
],
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | ToastWithCounts |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or toast not found | None |
Delete a toast
Code samples
curl -X DELETE https://api.toastworx.com/toasts/{toastUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/toasts/{toastUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/toasts/{toastUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/toasts/{toastUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/toasts/{toastUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/toasts/{toastUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/toasts/{toastUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /toasts/{toastUUID}
Delete a toast
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
toastUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Retrieve toast events
Code samples
curl -X GET https://api.toastworx.com/toasts/{toastUUID}/events \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/toasts/{toastUUID}/events',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/toasts/{toastUUID}/events', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/toasts/{toastUUID}/events', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/toasts/{toastUUID}/events',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/toasts/{toastUUID}/events", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/toasts/{toastUUID}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /toasts/{toastUUID}/events
Get the subscriber events for this toast - subscriber didReceive, didRead and didCallback the toast
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
toastUUID | path | string | true | none |
Example responses
200 Response
[
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didReceive",
"timestamp": 1595729436,
"subscriber": {
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f"
}
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or toast not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [ToastEvent] | false | none | none |
» uuid | string | false | none | Unique identifier for this toast event |
» eventType | string | false | none | Subscriber event type for this toast |
» timestamp | integer(int32) | false | none | Timestamp when this event occurred |
» subscriber | object | false | none | none |
»» uuid | string | false | none | Unique identifier for this subscriber |
Enumerated Values
Property | Value |
---|---|
eventType | didReceive |
eventType | didRead |
eventType | didCallback |
Subscribers
Subscribers are the end users who have subscribed to one of your channels by scanning the channel's QR code.
You can see the details of who has subscribed to your channel as well as remove subscribers using the /subscribers endpoint.
Retrieve a subscriber
Code samples
curl -X GET https://api.toastworx.com/subscribers/{subscriberUUID} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/subscribers/{subscriberUUID}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/subscribers/{subscriberUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/subscribers/{subscriberUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/subscribers/{subscriberUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/subscribers/{subscriberUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/subscribers/{subscriberUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /subscribers/{subscriberUUID}
Get the subscriber information - if subscriber is subscribed to a channel on this account
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
subscriberUUID | path | string | true | none |
Example responses
200 Response
{
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f",
"name": "Unnamed",
"deviceName": "iPad Pro",
"deviceModel": "iPad",
"countryCode": "US",
"appVersion": 1
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Subscriber |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or subscriber not found | None |
Remove subscriber
Code samples
curl -X DELETE https://api.toastworx.com/subscribers/{subscriberUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/subscribers/{subscriberUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/subscribers/{subscriberUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/subscribers/{subscriberUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/subscribers/{subscriberUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/subscribers/{subscriberUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/subscribers/{subscriberUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /subscribers/{subscriberUUID}
Remove a subscriber from all of the channels of this account
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
subscriberUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or subscriber not found | None |
Retrieve subscriber events
Code samples
curl -X GET https://api.toastworx.com/subscribers/{subscriberUUID}/events \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/subscribers/{subscriberUUID}/events',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/subscribers/{subscriberUUID}/events', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/subscribers/{subscriberUUID}/events', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/subscribers/{subscriberUUID}/events',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/subscribers/{subscriberUUID}/events", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/subscribers/{subscriberUUID}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /subscribers/{subscriberUUID}/events
Get the events for this subscriber - didSubscribe, didUnsubscribe, didDeleteSubscriber, didReceive, didRead, didMute, didUnmute
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
subscriberUUID | path | string | true | none |
Example responses
200 Response
[
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didSubscribe",
"timestamp": 1595725890,
"toast": {
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6"
}
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account or channel not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [SubscriberEvent] | false | none | none |
» uuid | string | false | none | Unique identifier for this subscriber event |
» eventType | string | false | none | Subscriber event type |
» timestamp | integer(int32) | false | none | Timestamp for when this event occurred |
» toast | object | false | none | none |
»» uuid | string | false | none | Unique identifier for this toast |
Enumerated Values
Property | Value |
---|---|
eventType | didSubscribe |
eventType | didUnsubscribe |
eventType | didDeleteSubscriber |
eventType | didReceive |
eventType | didRead |
eventType | didCallback |
eventType | didMute |
eventType | didUnmute |
Users and Login
Users allow you to provide access to your Account via email and password.
Initially your Account has one User which is created when you create the Account. Create additional Users by POST-ing to the /users endpoint.
Users login to get the account API keys and other account information using the /login endpoint. Call /login/reset to reset a user's password.
Login
Code samples
curl -X POST https://api.toastworx.com/login \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
const inputBody = '{
"email": "jane@example.com",
"password": "XXXXXXXX"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.toastworx.com/login',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/login', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.toastworx.com/login', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://api.toastworx.com/login',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/login", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/login");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /login
Login a user with an email and password. Returns the user, account and channels information include account api keys.
Body parameter
{
"email": "jane@example.com",
"password": "XXXXXXXX"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | string | true | none | |
password | body | string | true | none |
Example responses
200 Response
{
"name": "Jane",
"email": "jane@example.com",
"account": {
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Login |
401 | Unauthorized | unauthorised - missing email and/or password or user not found | None |
Reset
Code samples
curl -X POST https://api.toastworx.com/login/reset \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
const inputBody = '{
"email": "jane@example.com"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.toastworx.com/login/reset',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/login/reset', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.toastworx.com/login/reset', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://api.toastworx.com/login/reset',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/login/reset", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/login/reset");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /login/reset
Reset the password for this user.
A new password is generated and sent to the user by email.
Body parameter
{
"email": "jane@example.com"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | string | true | none |
Example responses
200 Response
{
"uuid": "2dc92910-d87b-486c-933e-9c8977636c9e"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - missing email or email not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» uuid | string | false | none | The user UUID |
Create a user
Code samples
curl -X POST https://api.toastworx.com/users \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "Jane",
"email": "jane@example.com",
"password": "XXXXXXXX"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/users',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.toastworx.com/users', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.post('https://api.toastworx.com/users', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.post 'https://api.toastworx.com/users',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.toastworx.com/users", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/users");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
POST /users
Create a new user for this account
Body parameter
{
"name": "Jane",
"email": "jane@example.com",
"password": "XXXXXXXX"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | NewUser | true | none |
name | body | string | false | Optional user name |
body | string | true | User email | |
password | body | string | true | User password |
Example responses
200 Response
{
"uuid": "2dc92910-d87b-486c-933e-9c8977636c9e"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
402 | Payment Required | account has reached limit of maximum users (maxUsers) | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
409 | Conflict | the email address is already in use | None |
422 | Unprocessable Entity | unprocessable request body - see msg for details | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» uuid | string | false | none | The user UUID |
List all users
Code samples
curl -X GET https://api.toastworx.com/users \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/users',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.toastworx.com/users', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your-api-key}'
}
r = requests.get('https://api.toastworx.com/users', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.get 'https://api.toastworx.com/users',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.toastworx.com/users", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/users");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
GET /users
Get the users for this account
Example responses
200 Response
[
{
"uuid": "c9933554-91a3-46ae-af7e-cf0c62caa933",
"name": "Jane",
"email": "jane@example.com",
"role": {
"name": "Admin",
"description": "Full access"
}
}
]
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successful operation | Inline |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [UsersWithRole] | false | none | [User and role information] |
» uuid | string | false | none | Unique identifier for this user |
» name | string | false | none | Optional user name |
string | false | none | User email | |
» role | Role | false | none | Role information |
»» name | string | false | none | Role name |
»» description | string | false | none | Role description |
Delete a user
Code samples
curl -X DELETE https://api.toastworx.com/users/{userUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.toastworx.com/users/{userUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.toastworx.com/users/{userUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
import requests
headers = {
'Authorization': 'Bearer {your-api-key}'
}
r = requests.delete('https://api.toastworx.com/users/{userUUID}', headers = headers)
print(r.json())
require 'rest-client'
require 'json'
headers = {
'Authorization' => 'Bearer {your-api-key}'
}
result = RestClient.delete 'https://api.toastworx.com/users/{userUUID}',
params: {
}, headers: headers
p JSON.parse(result)
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Authorization": []string{"Bearer {your-api-key}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.toastworx.com/users/{userUUID}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
URL obj = new URL("https://api.toastworx.com/users/{userUUID}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
DELETE /users/{userUUID}
Delete a user from this account
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
userUUID | path | string | true | none |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | successful operation | None |
401 | Unauthorized | unauthorised - invalid API token | None |
403 | Forbidden | unauthorised - API token does not allow this request | None |
404 | Not Found | account not found | None |
Schemas
Account
{
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
Account information
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this account |
name | string | false | none | Account name |
apiKeyFull | string | false | none | Account API key - full access |
apiKeyReadOnly | string | false | none | Account API Key - read only access |
maxChannels | integer(int64) | false | none | The maximum number of channels for this account |
maxSubscribersPerChannel | integer(int64) | false | none | The maximum number of subscribers per channel for this account |
maxToastsPerMonth | integer(int32) | false | none | The maximum number of toasts that can be sent per 30 day period |
toastExpiryDays | integer(int32) | false | none | The number of days before toasts on this account expire |
maxUsers | integer(int64) | false | none | The maximum number of users for this account |
callbackURL | string | false | none | Optional callback URL that receives POST events when subscribers tap on callback buttons |
isDemo | boolean | false | none | Flag indicating if this is a demonstration account |
channels | [Channel] | false | none | The channels for this account |
NewChannel
{
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html"
}
Optional new channel values
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | none |
description | string | false | none | none |
iconURL | string | false | none | none |
infoURL | string | false | none | none |
Channel
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
Channel information
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this channel |
name | string | false | none | Channel name |
description | string | false | none | Optional channel description |
qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
iconURL | string | false | none | Optional icon for this channel |
infoURL | string | false | none | Optional link to more information about this channel |
isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
timestamp | integer(int32) | false | none | Timestamp when this channel was created |
ChannelWithCounts
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221,
"subscriberCount": 51,
"toastCount": 173
}
Channel information including number of channel subscribers and channel toasts
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this channel |
name | string | false | none | Channel name |
description | string | false | none | Optional channel description |
qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
iconURL | string | false | none | Optional icon for this channel |
infoURL | string | false | none | Optional link to more information about this channel |
isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
timestamp | integer(int32) | false | none | Timestamp when this channel was created |
subscriberCount | integer(int32) | false | none | Number of channel subscribers |
toastCount | integer(int32) | false | none | Number of channel toasts |
ChannelWithToasts
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221,
"toasts": [
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this channel |
name | string | false | none | Channel name |
description | string | false | none | Optional channel description |
qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
iconURL | string | false | none | Optional icon for this channel |
infoURL | string | false | none | Optional link to more information about this channel |
isDefault | boolean | false | none | Flag indicating if this is the default channel for toasts. The default channel is used when you create a POST to the /toasts endpoint. |
timestamp | integer(int32) | false | none | Timestamp when this channel was created |
toasts | [ToastWithElementTypeAndCounts] | false | none | The toasts for this channel |
ChannelEvent
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didSubscribe",
"timestamp": 1595725890,
"subscriber": {
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this event |
eventType | string | false | none | Subscriber event type for this channel |
timestamp | integer(int32) | false | none | Timestamp when this event occurred |
subscriber | object | false | none | none |
» uuid | string | false | none | Unique identifier for this subscriber |
Enumerated Values
Property | Value |
---|---|
eventType | didSubscribe |
eventType | didUnsubscribe |
eventType | didDeleteSubscriber |
eventType | didMute |
eventType | didUnmute |
ChannelForSubscriber
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique identifier for this channel",
"example": "64a42d64-b64a-4ef7-93d8-8187b817b8d7"
},
"name": {
"type": "string",
"description": "Channel name",
"example": "My Channel Name"
},
"description": {
"type": "string",
"description": "Optional channel description",
"example": "Receive daily updates on server response times from ABC server"
},
"qrCodeURL": {
"type": "string",
"description": "The URL for the QR code image for this channel, to allow easy user sign-up to the channel",
"example": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png"
},
"iconURL": {
"type": "string",
"description": "Optional icon for this channel",
"example": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png"
},
"infoURL": {
"type": "string",
"description": "Optional link to more information about this channel",
"example": "https://www.toastworx.com/demo1.html"
},
"account": {
"type": "object",
"properties": {
"name": null,
"type": "string",
"description": "Account name"
}
}
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this channel |
name | string | false | none | Channel name |
description | string | false | none | Optional channel description |
qrCodeURL | string | false | none | The URL for the QR code image for this channel, to allow easy user sign-up to the channel |
iconURL | string | false | none | Optional icon for this channel |
infoURL | string | false | none | Optional link to more information about this channel |
account | object | false | none | none |
» type | any | false | none | none |
» description | any | false | none | none |
Login
{
"name": "Jane",
"email": "jane@example.com",
"account": {
"uuid": "59475060-6b60-4712-a9b7-4cc946c175d7",
"name": "My Account Name",
"apiKeyFull": "keyFull_3f40ee78-c8d8-47fb-9859-8b0ea8c62bff",
"apiKeyReadOnly": "keyReadOnly_7fc4cac5-11ac-4dca-95ca-de5b6663bf84",
"maxChannels": 1000,
"maxSubscribersPerChannel": 1000,
"maxToastsPerMonth": 100000,
"toastExpiryDays": 7,
"maxUsers": 100,
"callbackURL": "https://optional_path_to_your_endpoint.com/",
"isDemo": true,
"channels": [
{
"uuid": "64a42d64-b64a-4ef7-93d8-8187b817b8d7",
"name": "My Channel Name",
"description": "Receive daily updates on server response times from ABC server",
"qrCodeURL": "https://s3-eu-west-1.amazonaws.com/toastworx.qrcodes/64a42d64-b64a-4ef7-93d8-8187b817b8d7.png",
"iconURL": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png",
"infoURL": "https://www.toastworx.com/demo1.html",
"isDefault": true,
"timestamp": 1595675221
}
]
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Optional user name |
string | false | none | User email | |
account | Account | false | none | Account information |
Subscriber
{
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f",
"name": "Unnamed",
"deviceName": "iPad Pro",
"deviceModel": "iPad",
"countryCode": "US",
"appVersion": 1
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this subscriber |
name | string | false | none | Optional name set by the subscriber |
deviceName | string | false | none | The subscriber's device name as reported by the device |
deviceModel | string | false | none | The subscriber's device model as reported by the device |
countryCode | string | false | none | The subscriber's ISO 3166 two digit country code as reported by the device |
appVersion | string | false | none | The version of the ToastWorx app this subscriber is using |
SubscriberEvent
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didSubscribe",
"timestamp": 1595725890,
"toast": {
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this subscriber event |
eventType | string | false | none | Subscriber event type |
timestamp | integer(int32) | false | none | Timestamp for when this event occurred |
toast | object | false | none | none |
» uuid | string | false | none | Unique identifier for this toast |
Enumerated Values
Property | Value |
---|---|
eventType | didSubscribe |
eventType | didUnsubscribe |
eventType | didDeleteSubscriber |
eventType | didReceive |
eventType | didRead |
eventType | didCallback |
eventType | didMute |
eventType | didUnmute |
NewToast
{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
]
}
New toast values. Only alert is required - other values are optional
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
alert | string | true | none | The message shown on the mobile app as a push notification |
sound | ToastSound | false | none | The sound played when this notification is received on the mobile app |
content | [anyOf] | false | none | The payload for this toast, up to 10kb, as a JSON array |
anyOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementText | false | none | Displays text with one of four styles. See this demo for an example of different text elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementEmail | false | none | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementUrl | false | none | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementTel | false | none | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSms | false | none | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementMap | false | none | Displays a map centred on a location you provide. See this demo for an example map. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementWebview | false | none | Displays an embedded web page. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementCallback | false | none | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementChart | false | none | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementImageUrl | false | none | Displays an image in the toast. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementJson | false | none | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSpacer | false | none | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
NewToastWithImageData
{
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
],
"file": "string"
}
New toast values. Only alert is required - other values are optional
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
alert | string | true | none | The message shown on the mobile app as a push notification |
sound | ToastSound | false | none | The sound played when this notification is received on the mobile app |
content | [anyOf] | false | none | The payload for this toast, up to 10kb, as a JSON array |
anyOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementText | false | none | Displays text with one of four styles. See this demo for an example of different text elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementEmail | false | none | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementUrl | false | none | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementTel | false | none | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSms | false | none | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementMap | false | none | Displays a map centred on a location you provide. See this demo for an example map. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementWebview | false | none | Displays an embedded web page. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementCallback | false | none | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementChart | false | none | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementImageData | false | none | Displays an image in the toast. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementJson | false | none | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSpacer | false | none | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
continued
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
file | string(binary) | false | none | The image for this toast. Maximum file size 1MB. Valid formats gif, jpg, png. |
ToastElementType
"text"
We support 12 different types of toast elements.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | We support 12 different types of toast elements. |
Enumerated Values
Property | Value |
---|---|
anonymous | text |
anonymous | |
anonymous | url |
anonymous | tel |
anonymous | sms |
anonymous | map |
anonymous | webview |
anonymous | callback |
anonymous | chart |
anonymous | image |
anonymous | json |
anonymous | spacer |
ToastElementText
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
Displays text with one of four styles. See this demo for an example of different text elements.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
text | string | true | none | none |
style | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
type | text |
style | headline |
style | subhead |
style | body |
style | footnote |
ToastElementEmail
{
"type": "email",
"title": "string",
"to": "support@toastworx.com",
"subject": "string",
"body": "string"
}
Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
title | string | false | none | Optional title shown above the email address |
to | string | true | none | Email address. Provide multiple email addresses separated by commas. |
subject | string | false | none | Optional email subject |
body | string | false | none | Optional email body |
Enumerated Values
Property | Value |
---|---|
type |
ToastElementUrl
{
"type": "url",
"title": "string",
"url": "https://www.toastworx.com"
}
Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | false | none | none |
title | string | false | none | Optional title shown above the URL |
url | string | false | none | The link URL to show |
Enumerated Values
Property | Value |
---|---|
type | url |
ToastElementTel
{
"type": "tel",
"title": "string",
"number": "+442071234567"
}
Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
title | string | false | none | Optional title shown above the telephone number |
number | string | true | none | The telephone number to call. Include + with country code for international calling. |
Enumerated Values
Property | Value |
---|---|
type | tel |
ToastElementSms
{
"type": "sms",
"title": "string",
"to": "+447785123456,+447785123457",
"body": "string"
}
Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
title | string | false | none | Optional title shown above the SMS number |
to | string | true | none | SMS number. Provide multiple numbers separated by commas. |
body | string | false | none | Optional SMS body |
Enumerated Values
Property | Value |
---|---|
type | sms |
ToastElementMap
{
"type": "map",
"lat": 40.71,
"lng": -74.02,
"zoom": 15,
"height": 400,
"style": "satellite",
"isZoomEnabled": true,
"isScrollEnabled": true
}
Displays a map centred on a location you provide. See this demo for an example map.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
lat | number(double) | true | none | Latitude of the location |
lng | number(double) | true | none | Longitude of the location |
zoom | integer(int32) | false | none | Zoom level for the map between 1 and 20. Defaults to 10. |
height | integer(int32) | false | none | Optional map height in pixels. Defaults to 300px. |
style | string | false | none | none |
isZoomEnabled | boolean | false | none | none |
isScrollEnabled | boolean | false | none | none |
Enumerated Values
Property | Value |
---|---|
type | map |
style | standard |
style | satellite |
style | hybrid |
ToastElementWebview
{
"type": "webview",
"url": "https://www.toastworx.com",
"height": 350
}
Displays an embedded web page.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
url | string | true | none | The URL for the webpage |
height | integer(int32) | false | none | Optional webpage height in pixels. Defaults to 300px. |
Enumerated Values
Property | Value |
---|---|
type | webview |
ToastElementCallback
{
"type": "callback",
"titles": [
"My Action Button"
],
"identifiers": [
"1001"
]
}
Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
titles | [string] | true | none | An array of string labels for the callback buttons. Maximum of 4 buttons. |
identifiers | [string] | true | none | An array of string identifiers for the callback buttons. These enable you to identify which callback button was pressed. |
Enumerated Values
Property | Value |
---|---|
type | callback |
ToastElementChart
{
"type": "chart",
"chartType": "line",
"title": "My Line Chart",
"xAxis": "Readings",
"yAxis": "Values",
"xAxisType": "sec",
"markerSize": 0,
"height": 400,
"legend": true,
"dataset": [
[
[
"string"
]
]
]
}
Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
chartType | string | true | none | The type of chart to display |
title | string | false | none | Optional chart title |
xAxis | string | false | none | Optional chart x axis title |
yAxis | string | false | none | Optional chart y axis title |
xAxisType | string | false | none | Optional time format for x axis using timestamps |
markerSize | integer(int32) | false | none | Optional marker size for line and scatter charts. Defaults to 3px. |
height | integer(int32) | false | none | Optional chart in pixels. Defaults to 300px. |
legend | boolean | false | none | none |
dataset | [array] | true | none | none |
anyOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ChartLabels | false | none | none |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ChartLineBarScatterDataItem | false | none | Array of data items. First value is x axis, 2..n values are the different y values. Use unix timestamps in seconds for x-axis values and set xAxisType to one of sec, min, hour, day, month for time series data. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ChartPieDataItem | false | none | Array with two items for the pie chart. The first item is the value and the second item is the label. |
Enumerated Values
Property | Value |
---|---|
type | chart |
chartType | line |
chartType | bar |
chartType | horizontalbar |
chartType | pie |
chartType | scatter |
xAxisType | sec |
xAxisType | min |
xAxisType | hour |
xAxisType | day |
xAxisType | month |
ToastElementImageUrl
{
"type": "image",
"url": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png"
}
Displays an image in the toast. See this demo for an example.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
url | string | true | none | Image URL - the image is pulled from the URL |
Enumerated Values
Property | Value |
---|---|
type | image |
ToastElementImageData
{
"type": "image",
"file": null
}
Displays an image in the toast. See this demo for an example.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
file | binary | true | none | Image data - the image is stored on ToastWorx servers |
Enumerated Values
Property | Value |
---|---|
type | image |
ToastElementImageWithUrl
{
"type": "image",
"url": "https://s3-eu-west-1.amazonaws.com/toastworx.images/earth.png"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
url | string | true | none | Image URL |
Enumerated Values
Property | Value |
---|---|
type | image |
ToastElementJson
{
"type": "json",
"json": {}
}
Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
json | object | true | none | The JSON object to display. Supports standard JSON data types. |
Enumerated Values
Property | Value |
---|---|
type | json |
ToastElementSpacer
{
"type": "spacer",
"height": 20
}
Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
type | string | true | none | none |
height | integer(int32) | false | none | Spacer height in pixels. Defaults to 10px. |
Enumerated Values
Property | Value |
---|---|
type | spacer |
ToastSound
"toaster 1"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
anonymous | default |
anonymous | bell 1 |
anonymous | bell 2 |
anonymous | buzz |
anonymous | claps |
anonymous | glitch |
anonymous | klaxon |
anonymous | oops |
anonymous | register |
anonymous | toaster 1 |
anonymous | toaster 2 |
anonymous | yippee |
Toast
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
],
"timestamp": 1595729436
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this toast |
alert | string | false | none | The title of the push notification |
sound | ToastSound | false | none | The sound played when the subscriber receives this toast |
content | [anyOf] | false | none | The payload for this toast |
anyOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementText | false | none | Displays text with one of four styles. See this demo for an example of different text elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementEmail | false | none | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementUrl | false | none | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementTel | false | none | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSms | false | none | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementMap | false | none | Displays a map centred on a location you provide. See this demo for an example map. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementWebview | false | none | Displays an embedded web page. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementCallback | false | none | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementChart | false | none | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementImageWithUrl | false | none | none |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementJson | false | none | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSpacer | false | none | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
continued
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
timestamp | integer(int32) | false | none | Timestamp when this toast was created |
ToastWithCounts
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"content": [
{
"type": "text",
"text": "Nalebinding - A fabric creation technique predating knitting and crochet.",
"style": "body"
}
],
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this toast |
alert | string | false | none | The title of the push notification |
sound | ToastSound | false | none | The sound played when the subscriber receives this toast |
content | [anyOf] | false | none | The payload for this toast |
anyOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementText | false | none | Displays text with one of four styles. See this demo for an example of different text elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementEmail | false | none | Displays an action button that when tapped allows the customer to send an email to the provided address. See this demo for an example email element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementUrl | false | none | Displays an action button that when tapped opens a browser window to the provided url. See this demo for an example URL element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementTel | false | none | Displays an action button that when tapped allows the customer to call the provided number. See this demo for an example telephone element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSms | false | none | Displays an action button that when tapped allows the customer to send an SMS to the provided number. See this demo for an example SMS element. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementMap | false | none | Displays a map centred on a location you provide. See this demo for an example map. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementWebview | false | none | Displays an embedded web page. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementCallback | false | none | Displays between one and four buttons with labels you choose. When a subscriber taps on one of the buttons we make a POST request to the callbackURL for your account. See this demo for an example. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementChart | false | none | Displays one of five different types of chart. See this demo for a single chart and this demo for many chart types. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementImageWithUrl | false | none | none |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementJson | false | none | Displays pretty-printed JSON arrays and objects. See this demo for an example of different JSON elements. |
or
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
» anonymous | ToastElementSpacer | false | none | Displays a blank space used to make the toasts look more beautiful. See this demo for an example spacer element. |
continued
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
contentTypes | [ToastElementType] | false | none | Toast contentTypes |
timestamp | integer(int32) | false | none | Timestamp when this toast was created |
hasExpired | boolean | false | none | Flag indicating whether this toast has past the toastExpiryDays since creation |
pushCount | integer(int32) | false | none | Number of subscribers this toast was sent to as a push notification |
didReceiveCount | integer(int32) | false | none | Number of subscribers that received this toast |
didReadCount | integer(int32) | false | none | Number of subscribers that read this toast |
ToastWithElementTypeAndCounts
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"alert": "Here is your word of the day",
"sound": "toaster 1",
"contentTypes": [
"text"
],
"timestamp": 1595729436,
"hasExpired": false,
"pushCount": 45,
"didReceiveCount": 42,
"didReadCount": 26
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this toast |
alert | string | false | none | The title of the push notification |
sound | ToastSound | false | none | The sound played when the subscriber receives this toast |
contentTypes | [ToastElementType] | false | none | Toast contentTypes |
timestamp | integer(int32) | false | none | Timestamp when this toast was created |
hasExpired | boolean | false | none | Flag indicating whether this toast has past the toastExpiryDays since creation |
pushCount | integer(int32) | false | none | Number of subscribers this toast was pushed to |
didReceiveCount | integer(int32) | false | none | Number of subscribers that received this toast |
didReadCount | integer(int32) | false | none | Number of subscribers that read this toast |
ToastUUIDWithPushCount
{
"uuid": "db47dd8b-a2c3-4a2e-86a2-f66473f839f6",
"pushCount": 45
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this toast |
pushCount | integer(int64) | false | none | The number of subscribers who received this push notification |
ToastEvent
{
"uuid": "728c93ae-f4fa-46e2-94aa-1e271e893c99",
"eventType": "didReceive",
"timestamp": 1595729436,
"subscriber": {
"uuid": "2cb833ed-2b17-4414-baaf-d60529bcbb6f"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this toast event |
eventType | string | false | none | Subscriber event type for this toast |
timestamp | integer(int32) | false | none | Timestamp when this event occurred |
subscriber | object | false | none | none |
» uuid | string | false | none | Unique identifier for this subscriber |
Enumerated Values
Property | Value |
---|---|
eventType | didReceive |
eventType | didRead |
eventType | didCallback |
ChartLabels
[
"string"
]
Properties
None
ChartLineBarScatterDataItem
[
0
]
Array of data items. First value is x axis, 2..n values are the different y values. Use unix timestamps in seconds for x-axis values and set xAxisType to one of sec, min, hour, day, month for time series data.
Properties
None
ChartPieDataItem
[
[
100,
"UK"
]
]
Array with two items for the pie chart. The first item is the value and the second item is the label.
Properties
allOf
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | number | false | none | none |
and
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
NewUser
{
"name": "Jane",
"email": "jane@example.com",
"password": "XXXXXXXX"
}
New user values. Email and password required.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Optional user name |
string | true | none | User email | |
password | string | true | none | User password |
UsersWithRole
{
"uuid": "c9933554-91a3-46ae-af7e-cf0c62caa933",
"name": "Jane",
"email": "jane@example.com",
"role": {
"name": "Admin",
"description": "Full access"
}
}
User and role information
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
uuid | string | false | none | Unique identifier for this user |
name | string | false | none | Optional user name |
string | false | none | User email | |
role | Role | false | none | Role information |
Role
{
"name": "Admin",
"description": "Full access"
}
Role information
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Role name |
description | string | false | none | Role description |