Subscribe to a Channel Feed

Subscribe to updates from a channel feed with MQTT

ThingSpeak MQTT requires an MQTT API Key to subscribe to channel updates for both private and public channels. Supply any unique user name and your MQTT API key as a password parameter to the ThingSpeak MQTT broker when connecting. Choose Account > My Profile to see your MQTT API key. ThingSpeak™ MQTT supports only QoS 0. For more information,see Server Response for Connections.

Syntax

channels/<channelID>/subscribe/<format>

channels/<channelID>/subscribe/<format>/<apiKey>

Description

channels/<channelID>/subscribe/<format> subscribes to updates to a channel feed. Replace <channelID> with the channel ID and <format> with the format of the return message. Subscribing to a channel feed automatically returns the last entry in the channel to your subscription. Invalid subscription details such as API Key, channel number, or MQTT User API Key result in the client being disconnected.

channels/<channelID>/subscribe/<format>/<apiKey> subscribes to updates to a channel feed from a private channel. Replace <apikey> with the Read API key of the channel.

Input Arguments

<channelID> — channelID for the subscription target

(default) (default) | numeric

Channel ID for the subscription target, specified as a numeric.

Data Types: uint16 | int16 | int8 | uint8

<apikey> — channel Read API Key

Channel Read API Key, required to subscribe to a private channel. This value is different from the MQTT API Key used for connection.

Data Types: char

<format> — output format for returned message

Output format for returned message specified as JSON, XML, or CSV. Fields that are not enabled do not appear in the output.

Note

Latitude, longitude, and elevation are for the feed update, not the channel settings.

Example: JSON

Specify JSON output as <format> and the channel update messages are JSON objects with the format shown. For example, channels/1417/subscribe/json.

{
   "channel_id":1417,
   "created_at":"2017-09-05T07:40:09-04:00",
   "entry_id":931,
   "field1":null,
   "field2":"pink",
   "field3":null,
   "field4":null,
   "field5":null,
   "field6":null,
   "field7":null,
   "field8":null,
   "latitude":null,
   "longitude":null,
   "elevation":null,
   "status":null
}

Example: XML

Specify XML output as <format> to receive messages in XML format. For example, channels/1417/subscribe/xml.

<?xml version="1.0" encoding="UTF-8" ?>
<hash>
  <channel-id>1417</channel-id>
  <created-at>2020-03-24T18:01:42Z</created-at>
  <elevation nil="true" />
  <entry-id type="integer">18</entry-id>
  <field1>788888</field1>
  <field2 nil="true" />
  <field3 nil="true" />
  <field4 nil="true" />
  <field5 nil="true" />
  <field6 nil="true" />
  <field7 nil="true" />
  <field8 nil="true" />
  <latitude nil="true" />
  <longitude nil="true" />
  <status nil="true" />
</hash>

Example: CSV

Specify CSV output as <format> to receive messages as comma-separated variable text. For example, channels/1417/subscribe/csv.

channel_id,field1,field2,field3,field4,field5,field6,field7,field8,created_at,entry_id,status,latitude,longitude,elevation
1417,89,,,,,,,,2017-06-19T18:15:57Z,2,,,,

Response

If a connection is successful, the server responds with the last value in the subscribed channel. The <format> used in your topic subscription determines the format of the response.

Limitations

• Each ThingSpeak license type allows different number of concurrent MQTT subscriptions and has different restrictions on the number of messages delivered. For more information, see How to Buy and Frequently Asked Questions.

• MQTT subscriptions do not report updates to the channel from Bulk Write JSON Data or Bulk Write CSV Data.

• ThingSpeak MQTT honors all MQTT disconnect and unsubscribe messages. If you disconnect from the MQTT server, you are automatically unsubscribed from channel updates.

Examples

Configure MQTT.fx to subscribe to channel updates from the MathWorks^® weather station. Use mqtt.thingspeak.com and port 1883. Enter your MQTT API Key as the password.

Use the subscribe topic format channels/12397/subscribe/json. Since the MathWorks weather station is public, you do not need to include /<apikey>.

Now update the channel, and observe the messages in your client.

To unsubscribe from channel updates, click the Unsubscribe or Disconnect buttons.