{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"How They Work","type":"basic","slug":"how-subscriptions-work","excerpt":"","body":"Subscriptions allow messages from one device to be automatically delivered to another. This document will explain how subscriptions work in the context of [Subscriptions 2.0](doc:subscriptions-2-0) and the [Firehose](doc:firehose). Prior subscription mechanisms in Meshblu are deprecated.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/vjXxHQ70So2Pwb6Wba0o_Subscription%201.svg\",\n \"Subscription 1.svg\",\n \"0\",\n \"0\",\n \"#323232\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIn this example, `Device B` subscribes to all broadcasts sent from `Device A`. Using the [Subscriptions 2.0](doc:subscriptions-2-0) API the subscription would look like this:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device A\\\",\\n \\\"subscriberUuid\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Permissions\",\n \"body\": \"Subscriptions will only be activated if the proper permissions are available. Device B must be in Device A's `broadcast.sent` whitelist. Device A may revoke that permission at any time that will instantly deactivate the subscription.\\n\\nSee [Permissions 2.0](doc:permissions-2-0) for more detailed information.\"\n}\n[/block]\nIn this scenario, `Device B` must also subscribe to its own `broadcast.received` messages. This allows each device to control what messages it automatically receives from Meshblu.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device B\\\",\\n \\\"subscriberUuid\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Routes\"\n}\n[/block]\nKnowing the origin of a message can be very important when building automations. Meshblu will provide metadata that shows the path each subscription took.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"metadata\\\": {\\n \\\"route\\\": [\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device A\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n }\\n ]\\n },\\n \\\"data\\\": {\\n \\\"devices\\\": [\\\"*\\\"]\\n }\\n} \",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nEach hop in a chain of subscriptions is appended to the `route` property in chronological order. The `from` in the first route in the list is the originator of the message. This information allows you to determine how your device received a particular message.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Advanced Subscriptions\"\n}\n[/block]\n[Subscriptions 2.0](doc:subscriptions-2-0) allow fine grained control over message types. In some advanced cases, a device may want to subscribe to messages received by another device, instead of messages emitted from that device.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/nufNSfMmToixiBx9ssWI_What%20is%20Subscription%20Broadcast%20Received.svg\",\n \"What is Subscription Broadcast Received.svg\",\n \"0\",\n \"0\",\n \"#323232\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIn this example, `Device C` will receive any broadcasts that `Device B` receives. `Device C` will not receive any broadcasts that are sent by `Device B` without creating an additional subscription.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device B\\\",\\n \\\"subscriberUuid\\\": \\\"Device C\\\",\\n \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nThe message route will also reflect the additional hop taken by the new subscription.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"metadata\\\": {\\n \\\"route\\\": [\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device A\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device C\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n }\\n ]\\n },\\n \\\"data\\\": {\\n \\\"devices\\\": [\\\"*\\\"]\\n }\\n} \",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"573b6d2537fcf72000a2e6d2","project":"5564f26a1fd04c0d00dc9aaa","user":"5564f227f0f70f0d00a9ab20","createdAt":"2016-05-17T19:12:37.807Z","githubsync":"","version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5564f26b1fd04c0d00dc9aae","556741d17acd550d0075eaca","556741d87acd550d0075eacb","556742f87acd550d0075ead1","556781cd6976ef0d0099c545","5568d666d33aad0d00ec8d2e","557f6b2d38249b0d00d0d12b","55b67be9c2e909190073ed38","564e56c601e80e0d00396684","56731b714b2a680d00524daf","573612ac652bd80e00a90027","57365e2cf8ebd31700769f50","57366131f8ebd31700769f58","573b93514e029d19000b8669","573bbfdb7ac6f6170033bd35"],"_id":"5564f26a1fd04c0d00dc9aad","createdAt":"2015-05-26T22:23:38.671Z","project":"5564f26a1fd04c0d00dc9aaa","releaseDate":"2015-05-26T22:23:38.671Z","__v":15},"parentDoc":null,"__v":14,"category":{"sync":{"isSync":false,"url":""},"pages":["56731edc58c4890d00bb5439"],"title":"Subscriptions","slug":"subscriptions","order":3,"from_sync":false,"reference":false,"_id":"56731b714b2a680d00524daf","project":"5564f26a1fd04c0d00dc9aaa","version":"5564f26a1fd04c0d00dc9aad","__v":1,"createdAt":"2015-12-17T20:30:41.290Z"}}