Wireless application Sensor Platform

A Low Power Wireless Bridge for the Internet of Things

Wasp
Honeycombs small

TalkBack API

TalkBack allows any device to act upon queued commands.

TalkBack Example

The following steps would allow you to control a door that opens only once:
  1. Create a new TalkBack using the web interface.
  2. Add some queued commands using the web interface or API, such as "OPENDOOR", "CLOSEDOOR".
  3. If the door (with Wi-Fi and a connected motion sensor) senses someone nearby, execute the next command from ThingSpeak: "OPENDOOR".
  4. After 5 minutes of no motion detected, execute the next command from ThingSpeak: "CLOSEDOOR".
  5. When someone else approaches the door, execute the next command from ThingSpeak, which will be empty--the door won't open again until more commands are added to the queue.

API Notes

If you don't require SSL, you can replace https with http in any URL.
You can change the response format by clicking the TEXT, JSON, or XML buttons.

Response in: TEXTJSONXML

Add a TalkBack Command


To add a TalkBack command, send an HTTP POST to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack. There is no limit to the number of commands that a single TalkBack can have.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)
  • command_string (string) - Command to be sent to your device. There is a limit of 255 characters per command_string.
  • position (integer) - The position you want this command to appear in. Any previous commands at or after this position will be shifted down. If the position is left blank, the command will automatically be added to the end of the queue (with the highest position).

Example POST: 
POST https://thingspeak.future.ca/talkbacks/3/commands.json.xml
     api_key=XXXXXXXXXXXXXXXX
     command_string=OPENDOOR
     position=5

The response will be the command ID, for example: 18
The response will be a JSON object of the new command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": null,
  "id": 18,
  "position": 5
}
The response will be an XML object of the new command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer">5</position>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime" nil="true"/>
</command>
Response in: TEXTJSONXML

Get a TalkBack Command

To show an existing TalkBack command, send an HTTP GET to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands/COMMAND_ID.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack and COMMAND_ID with the ID of the command.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example GET: 
GET https://thingspeak.future.ca/talkbacks/3/commands/18.json.xml?api_key=XXXXXXXXXXXXXXXX

The response will be the command string, for example: OPENDOOR
The response will be a JSON object of the new command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": null,
  "id": 18,
  "position": 5
}
The response will be an XML object of the new command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer">5</position>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime" nil="true"/>
</command>
Response in: TEXTJSONXML

Update a TalkBack Command


To update an existing TalkBack command, send an HTTP PUT to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands/COMMAND_ID.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack and COMMAND_ID with the ID of the command.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)
  • command_string (string) - Command to be sent to your device
  • position (integer) - The position you want this command to appear in. Any previous commands at or after this position will be shifted down.

Example PUT: 
PUT https://thingspeak.future.ca/talkbacks/3/commands/18.json.xml
    api_key=XXXXXXXXXXXXXXXX
    command_string=OPENDOOR
    position=5

The response will be the command string, for example: OPENDOOR
The response will be a JSON object of the updated command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": null,
  "id": 18,
  "position": 5
}
The response will be an XML object of the updated command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer">5</position>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime" nil="true"/>
</command>
Response in: TEXTJSONXML

Execute the Next TalkBack Command


To execute the next TalkBack command in the queue (normally in position 1), send an HTTP GET or POST to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands/execute.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack.

Executing a command removes it from the queue, sets executed_at to the current time, sets position to null, and reorders the remaining commands.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example POST: 
POST https://thingspeak.future.ca/talkbacks/3/commands/execute.json.xml
     api_key=XXXXXXXXXXXXXXXX

The response will be the command string, for example: OPENDOOR

If there are no commands left to execute, the response body will be empty.
The response will be a JSON object of the executed command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": "2013-12-30T17:53:40-05:00",
  "id": 18,
  "position": null
}


If there are no commands left to execute, the response will be an empty JSON object, for example: 
{}
The response will be an XML object of the executed command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer" nil="true"/>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime">2013-12-31T16:51:17-05:00</executed-at>
</command>


If there are no commands left to execute, the response will be an empty XML hash, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<hash></hash>
Response in: TEXTJSONXML

Update a Channel and Execute the Next TalkBack Command


The next TalkBack command in the queue (normally in position 1) can be executed at the same time a Channel is updated by sending an HTTP GET or POST to https://thingspeak.future.ca/update.json.xml.

Executing a command removes it from the queue, sets executed_at to the current time, sets position to null, and reorders the remaining commands.

Please note that the parameters for this action are different than other TalkBack commands. Since a Channel is being updated, the key parameter refers to the Channel API write key, while the talkback_key refers to the TalkBack API key.

Valid parameters:
  • key (string) - API key for the Channel (required)
  • talkback_key (string) - API key for this specific TalkBack (required)
Additional parameters for updating a Channel can be found in the Channel API documentation.

Example POST: 
POST https://thingspeak.future.ca/update.json.xml
     field1=70
     key=XXXXXXXXXXXXXXXX
     talkback_key=XXXXXXXXXXXXXXXX

The response will be the command string, for example: OPENDOOR
The response will be a JSON object of the executed command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": "2013-12-30T17:53:40-05:00",
  "id": 18,
  "position": null
}
The response will be an XML object of the executed command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer" nil="true"/>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime">2013-12-31T16:51:17-05:00</executed-at>
</command>
Response in: TEXTJSONXML

Get the Last Executed Command

To show the most recently executed TalkBack command, send an HTTP GET to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands/last.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example GET: 
GET https://thingspeak.future.ca/talkbacks/3/commands/last.json.xml?api_key=XXXXXXXXXXXXXXXX

The response will be the command string, for example: OPENDOOR
The response will be a JSON object of the new command, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": "2013-12-30T17:53:40-05:00",
  "id": 18,
  "position": null
}
The response will be an XML object of the new command, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer" nil="true"/>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime">2013-12-31T16:51:17-05:00</executed-at>
</command>
Response in: TEXTJSONXML

Delete a TalkBack Command

To delete an existing TalkBack command, send an HTTP DELETE to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands/COMMAND_ID.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack and COMMAND_ID with the ID of the command.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example DELETE: 
DELETE https://thingspeak.future.ca/talkbacks/3/commands/18.json.xml
       api_key=XXXXXXXXXXXXXXXX

The response will be the deleted command string, for example: OPENDOOR
The response will be a JSON object of the command before it was deleted, for example: 
{
  "command_string": "OPENDOOR",
  "created_at": "2013-12-29T17:53:40-05:00",
  "executed_at": null,
  "id": 18,
  "position": 5
}
The response will be an XML object of the command before it was deleted, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<command>
  <id type="integer">18</id>
  <command-string>OPENDOOR</command-string>
  <position type="integer">5</position>
  <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
  <executed-at type="datetime" nil="true"/>
</command>
Response in: TEXTJSONXML

List All TalkBack Commands

To show all of a TalkBack's commands, send an HTTP GET to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example GET: 
GET https://thingspeak.future.ca/talkbacks/3/commands.json.xml?api_key=XXXXXXXXXXXXXXXX

The response will be the command strings in a comma-separated quoted list, for example: "OPENDOOR","CLOSEDOOR"
The response will be a JSON array of all the commands, for example: 
[
  {
    "command_string": "OPENDOOR",
    "created_at": "2013-12-29T17:53:40-05:00",
    "executed_at": null,
    "id": 18,
    "position": 1
  },
  {
    "command_string": "CLOSEDOOR",
    "created_at": "2013-12-30T17:53:40-05:00",
    "executed_at": null,
    "id": 19,
    "position": 2
  }
]
The response will be an XML list of all the commands, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<commands type="array">
  <command>
    <id type="integer">18</id>
    <command-string>OPENDOOR</command-string>
    <position type="integer">1</position>
    <created-at type="datetime">2013-12-29T16:51:17-05:00</created-at>
    <executed-at type="datetime" nil="true"/>
  </command>
  <command>
    <id type="integer">19</id>
    <command-string>CLOSEDOOR</command-string>
    <position type="integer">2</position>
    <created-at type="datetime">2013-12-30T16:51:17-05:00</created-at>
    <executed-at type="datetime" nil="true"/>
  </command>
</commands>
Response in: TEXTJSONXML

Delete All TalkBack Commands

To delete all of a TalkBack's commands, send an HTTP DELETE to https://thingspeak.future.ca/talkbacks/TALKBACK_ID/commands.json.xml, replacing TALKBACK_ID with the actual ID of your TalkBack. Commands that have already been executed will not be deleted.

Valid parameters:
  • api_key (string) - API key for this specific TalkBack (required)

Example DELETE: 
DELETE https://thingspeak.future.ca/talkbacks/3/commands.json.xml
       api_key=XXXXXXXXXXXXXXXX

The response body will be empty.
The response will be an empty JSON array, for example: 
[]
The response will be an empty XML array, for example: 
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array" />