Write Data and Execute TalkBack Command

Update channel data with HTTP GET or POST and execute TalkBack command

Request

HTTP Method

POST or GET

URL

https://api.thingspeak.com/update.<format>

URL Parameters

Name	Description
<format>	Format for the HTTP response, specified as json or xml.

Example: https://api.thingspeak.com/update.json?api_key=XXXXXXXXXXXXXXXXtalkback_key=YYYYYYYYYYYYYYYY

Body

Name	Description	Value Type
api_key	(Required) Specify Write API Key for this specific channel. You can also send the Write API Key using a THINGSPEAKAPIKEY HTTP header. The Write API Key is found on the API Keys tab of the channel view.	string
talkback_key	(Required) API key for a specific instance of TalkBack. Including the TalkBack API key causes the next command in the queue to be removed and returns the command in the response.	string
field<X>	(Optional) Field X data, where X is the field ID	any
lat	(Optional) Latitude in degrees	decimal
long	(Optional) Longitude in degrees	decimal
elevation	(Optional) Elevation in meters	integer
status	(Optional) Status update message	string
twitter	(Optional) Twitter® username linked to ThingTweet	string
tweet	(Optional) Twitter status update	string
created_at	(Optional) Date when feed entry was created, in ISO 8601 format, for example, 2014-12-31 23:59:59. Must be unique within the channel. Time zones can be specified using the timezone parameter.	datetime

Content-Type

Content-Type is required only for the POST method, not for the GET method.

Use application/json for updates in JSON format.

Use application/x-www-form-urlencoded for all other updates.

Response

Success

HTTP Status Code

200 OK

Body

 Text Example

POST https://api.thingspeak.com/update api_key=XXXXXXXXXXXXXXXX field1=73 talkback_key=YYYYYYYYYYYYYYYY

Response The response is the command string of the next TalkBack command in the TalkBack queue with the specified TalkBack API key. If the update fails, the response is 0.

 JSON Example

POST https://api.thingspeak.com/update.json api_key=XXXXXXXXXXXXXXXX field1=73 talkback_key=YYYYYYYYYYYYYYYY

The response is a JSON object of the next command in the TalkBack queue with the specified TalkBack API key, for example: { "id": 15254213, "command_string": "OPENDOOR", "position": null, "executed_at": "2019-03-05T15:48:29Z", "created_at": "2019-02-26T13:45:09Z" }

 XML Example

POST https://api.thingspeak.com/update.xml api_key=XXXXXXXXXXXXXXXX field1=73 talkback_key=YYYYYYYYYYYYYYYY

The response is an XML object of the next command in the TalkBack queue with the specified TalkBack API key, for example: <command> <id type="integer">15338752</id> <command-string>OPENDOOR</command-string> <position type="integer" nil="true"/> <executed-at type="dateTime">2019-03-05T15:52:08Z</executed-at> <created-at type="dateTime">2019-03-05T15:51:54Z</created-at> </command>

Error

For the full list, see Error Codes.

Examples

Use POSTMAN to Add a TalkBack Command

You can use POSTMAN to try out your HTTP requests using the RESTful API for ThingSpeak. This example shows how to simultaneously update a channel and execute a TalkBack command from an existing queue using POSTMAN.

Write 123 to field 1 of a channel and return the next TalkBack command in an existing TalkBack queue.

POST https://api.thingspeak.com/update
     api_key=XXXXXXXXXXXXXXXX
     talkback_key=YYYYYYYYYYYYYYYYY

1. In POSTMAN, select POST from the drop-down list of HTTP verbs, and enter https://api.thingspeak.com/update in the address bar.

2. Enter the additional parameters and values:

   • Key: api_key, Value: XXXXXXXXXXXXXXXX

   • Key: talkback_key, Value: YYYYYYYYYYYYYYYY

The response is in text format. Note the server response value of 200 OK, which indicates successful channel update and execution of the TalkBack command.

The executed command is shown in the response.

Limitations

All timestamps must be unique. You cannot write new data using timestamps that match existing data in the channel.