Skip to main content

Sending from other systems

Anything on the local network that can call a web address can send a message through the driver: an alarm panel, a network video recorder, a PLC, Home Assistant or a script. It can send one of your templates, or a message of its own. The message goes to the same people, webhooks and inbox as one sent from Crestron Home programming.

The send address and token​

Open the API tab in the setup app. It shows:

  • the Send URL, which is the processor's address followed by /cws/, the driver instance's path, and /send;
  • the Send token, which every caller must add to the address as ?token=.

Choose whether callers use http or https. With https, the caller must accept the processor's own certificate. Use Copy to take the address or the token. New token replaces the token straight away, and anything still using the old one is refused. Do that if the token gets into the wrong hands.

Keep the token private

Anyone on the network who has the token can send messages to the household. Give it only to the systems that need it. The downloads on the API tab contain the token too.

Sending a template​

The Examples section of the API tab has a ready-made link for every template, with a cURL command for macOS and Linux and a PowerShell command for Windows. Copy the one you need into the other system.

As a link (GET), for devices that can only call a URL:

http://192.168.1.10/cws/<path>/send?token=<token>&template=Garage%20open&var.door=side

As a POST with a JSON body:

curl -X POST "http://192.168.1.10/cws/<path>/send?token=<token>" \
-d '{"template": "Garage open", "vars": {"door": "side"}}'

In Windows PowerShell, curl is a different command. Use Invoke-RestMethod instead:

Invoke-RestMethod -Method Post -Uri "http://192.168.1.10/cws/<path>/send?token=<token>" `
-ContentType 'application/json' -Body '{"template": "Garage open", "vars": {"door": "side"}}'

var.door=side in a link, or "vars": {"door": "side"} in a body, fills {var:door} in the template.

Sending a message of your own​

Send a subject and body instead of a template name:

{
"subject": "Front gate left open",
"body": "The gate has been open since 18:40.",
"level": "warning",
"tag": "gate"
}

The same fields work as query parameters in a link. Every field except subject and body is optional:

FieldWhat it does
templateSend this template. Use it instead of subject and body.
varsValues for the template's {var:name} placeholders. In a link: var.name=value.
subject, bodyThe message.
levelinfo, notice, warning or critical. Default info.
channelsThe people and webhooks to send to, by their id. The ids are listed in the OpenAPI download. Without it, the level decides. In a link, separate them with commas.
link, linkTitleA web address and its text. It must start with http:// or https://.
tagA key that replaces an older message with the same tag, and stops repeats.
inboxfalse to send without keeping it in the inbox.
keepForMinutes before the inbox drops it. 0 keeps it until someone clears it.
protectedtrue to make clearing it need the clear code.
actionsUp to three buttons, each {"label": "…", "confirm": "…", "event": "…"}. POST only.

A message can be up to 64 KB.

Answers​

The driver answers in JSON:

StatusMeaning
200Accepted. The answer says how many deliveries were queued, whether it went in the inbox, and any notes, such as a person in quiet hours. If notifications or the template are switched off, Accepted is false with the reason.
400Something is wrong with the message. The answer lists what.
401The token is missing or wrong.
402The driver isn't licensed, so nothing was sent.
405Use GET or POST.

Postman and OpenAPI​

The API tab has two downloads:

  • Download Postman collection: a Postman collection (v2.1) with one request per template. In Postman, choose Import and pick the file. The collection keeps the address and token in variables called baseUrl and token.
  • Download OpenAPI description: the same description in OpenAPI 3, for other tools.

Both are made from the setup as it is now. Download them again after you add or rename templates.