{"_id":"56ad38d71c09150d00a183ad","category":{"_id":"56ad356a2a7860170013f714","__v":5,"version":"56acd71213ac890d001c3c7d","pages":["56ad35e23fc1020d009776e3","56ad37781a7ee417009ced1d","56ad3859693f0a0d0085f0cd","56ad38d71c09150d00a183ad","56ad4721cdbb3d170064eaf9"],"project":"56acd71213ac890d001c3c7a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-30T22:12:58.236Z","from_sync":false,"order":10,"slug":"singularity-on-demand-events","title":"Singularity: On-Demand Events"},"parentDoc":null,"project":"56acd71213ac890d001c3c7a","user":"56acd6caa040860d00ac94a2","githubsync":"","version":{"_id":"56acd71213ac890d001c3c7d","project":"56acd71213ac890d001c3c7a","__v":15,"createdAt":"2016-01-30T15:30:26.928Z","releaseDate":"2016-01-30T15:30:26.928Z","categories":["56acd71313ac890d001c3c7e","56acd8f113ac890d001c3c81","56acd8f95ac4060d0027865e","56acd93a13ac890d001c3c82","56ad20660ab3c00d00ce3347","56ad356a2a7860170013f714","56ad47eb0ab3c00d00ce334f","56afd523bc304a0d00ace1df","56b29a019621f20d00efb37e","56b657e11bc6970d009feee7","5845cc3c39950c1b002afe77","5845cde163c11b250037967e","5846efd45d064323007b17b4","588604da4674e32300efd160","588627882393d50f00f1322c"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":8,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-30T22:27:35.398Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"This event is used to return the current subscribers for a channel. It is used as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"socket.emit('channel-subscribers', {\\n  access_token: \\\"channel OAuth2 access token\\\",\\n  params: {\\n      array: [<gamewisp-identifiers>],\\n      status: 'all', \\n      sort: 'newest', \\n      benefits: true, \\n      tier: true, \\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**params** is a JSON object of optional parameters that can be used to request particular subscriber data for the specified channel. Each element of **params** is described as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"array\",\n    \"0-1\": \"Array\",\n    \"0-2\": \"An array of** GameWisp user ids, twitch usernames, or GameWisp usernames or any combination thereof**. If any of the specified elements belong to a subscriber of the particular channel, that subscriber’s information will be returned. Specifying a list of users in this parameter limits all other optional parameters to only the list of specified users. The default parameter is an empty array, which returns all of the subscribers for the channel.\",\n    \"1-0\": \"status\",\n    \"1-1\": \"String\",\n    \"1-2\": \"Filter by subscriber status. Options include:\\n* **all** -  Default. Does not filter the list of subscribers by status.\\n* **active**: Only returns subscribers that are active.\\n* **inactive**: Only returns subscribers if they are inactive.\\n* **twitch**: Only returns subscribers if they are subscribed on Twitch. This only works for partnered channels.\",\n    \"2-0\": \"sort\",\n    \"2-1\": \"String\",\n    \"2-2\": \"Applies a sort to the returned results. Options include:\\n\\n* **newest** - Default. Sort from newest subscriber to oldest\\n* **oldest** - Sort from oldest subscriber to newest.\",\n    \"3-0\": \"benefits\",\n    \"3-1\": \"Boolean\",\n    \"3-2\": \"Default is false. If true, returns the benefits for each subscriber.\",\n    \"4-0\": \"tier\",\n    \"4-1\": \"Boolean\",\n    \"4-2\": \"Default is false. If true, returns tier information for the subscriber.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nThis event emits **app-channel-subscribers** back to your application upon completion. You can listen for this event using Socket.IO as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"  socket.on('app-channel-subscribers', function(response){\\n    // Do something with response.\\n  });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThe **response** object has the following structure:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   result: {\\n      status: 1,\\n      message: \\\"Channel Subscribers.\\\"\\n   },\\n   channel: {\\n      names: {\\n         gamewisp: \\\"GameWisp channel name\\\",\\n         twitch: \\\"twitch channel name\\\",\\n         youtube: \\\"youtube channel name\\\"\\n      },\\n      ids: {\\n         gamewisp: \\\"channel identifier\\\",\\n         twitch: \\\"12312312q\\\",\\n         youtube: \\\"UCiqp4J8asdkssssssssdfae\\\"\\n      }  \\n   },\\n   data: \\n      {\\n       channel_id: \\\"channel-identifier\\\",\\n       status: \\\"authenticated\\\",\\n       subscribers: [\\n          {\\n             benefits: [\\n                {\\n                   benefit: {\\n                      id: \\\"3\\\",\\n                      delivery: \\\"delivery-messaging\\\",\\n                      title: \\\"Subscriber Messaging\\\",\\n                      description: \\\"Receive Subscriber-only messages from me.\\\",\\n                      channel_data: null,\\n                      type: \\\"unknown-type\\\",\\n                      month_delay: null,\\n                      recurring: false,\\n                      recurring_input: false,\\n                      receieve_immediately: false,\\n                      removed_at: null,\\n                      subscriber_limit: null,\\n                      tier_bonus: false,\\n                      quantity: 1,\\n                      multiplier: 1\\n                   },\\n                   fulfillment: {\\n                      id: \\\"49917\\\",\\n                      benefit_id: \\\"3\\\",\\n                      tier_id: \\\"856\\\",\\n                      channel_fulfillment_response: null,\\n                      fulfilled_at: \\\"2015-12-24 03:55:17\\\",\\n                      previously_fulfilled_at: null,\\n                      disabled_at: null,\\n                      user_input_provided_at: null,\\n                      recurring: true,\\n                      granted_at: {\\n                         date: \\\"2015-12-24 03:55:17.000000\\\",\\n                         timezone_type: 3,\\n                         timezone: \\\"UTC\\\"\\n                      },\\n                      channel_cancelled_at: null,\\n                      status: \\\"active\\\",\\n                      user_input: null\\n                   }\\n                },\\n                //...\\n             ],\\n             ids: {\\n                gamewisp: \\\"12323\\\",\\n                twitch: \\\"455552422\\\"\\n             },\\n             usernames: {\\n                gamewisp: \\\"gamewisp-user-name\\\",\\n                twitch: \\\"twitch-user-name\\\"\\n             },\\n             status: \\\"active\\\",\\n             amount: \\\"4.99\\\",\\n             subscribed_at: \\\"2015-12-24 00:00:00\\\",\\n             end_of_access: \\\"2016-01-24 23:59:00\\\",\\n             tier: {\\n                id: \\\"123\\\",\\n                title: \\\"Tier Title\\\",\\n                level: \\\"1\\\",\\n                cost: \\\"4.99\\\",\\n                description: \\\"Tier description\\\",\\n                published: true\\n             }\\n          },\\n          //...\\n\\n      }\\n   ],\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe response object contains subscriber information (described in detail in the [subscriber-new](https://gamewisp.readme.io/docs/subscriber-new) event documentation), benefit-fulfillment pairs for the subscriber (see [subscriber-benefits-change](https://gamewisp.readme.io/docs/subscriber-benefits-change) ), and the subscriber’s tier (see [subscriber-status-change](https://gamewisp.readme.io/docs/subscriber-status-change) ). Note that you will only receive the full object for a subscriber if both the **benefit** and **tier** parameters of **channel-subscribers** are true.\n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"This response may be very large\",\n  \"body\": \"Depending on how you use this event, the resulting response object can be very large. \\n\\nIt is not recommended to grab all the benefit and tier information for every subscriber simultaneously. \\n\\nIt is preferred to use this event to get a full list of subscribers for a channel, and then check the benefits of individual subscribers through subsequent calls.\"\n}\n[/block]","excerpt":"Used to request all of the subscribers for a channel. Can be filtered via input parameters","slug":"channel-subscribers","type":"fn","title":"channel-subscribers"}

channel-subscribers

Used to request all of the subscribers for a channel. Can be filtered via input parameters

This event is used to return the current subscribers for a channel. It is used as follows: [block:code] { "codes": [ { "code": "socket.emit('channel-subscribers', {\n access_token: \"channel OAuth2 access token\",\n params: {\n array: [<gamewisp-identifiers>],\n status: 'all', \n sort: 'newest', \n benefits: true, \n tier: true, \n }\n});", "language": "javascript" } ] } [/block] **params** is a JSON object of optional parameters that can be used to request particular subscriber data for the specified channel. Each element of **params** is described as follows: [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "array", "0-1": "Array", "0-2": "An array of** GameWisp user ids, twitch usernames, or GameWisp usernames or any combination thereof**. If any of the specified elements belong to a subscriber of the particular channel, that subscriber’s information will be returned. Specifying a list of users in this parameter limits all other optional parameters to only the list of specified users. The default parameter is an empty array, which returns all of the subscribers for the channel.", "1-0": "status", "1-1": "String", "1-2": "Filter by subscriber status. Options include:\n* **all** - Default. Does not filter the list of subscribers by status.\n* **active**: Only returns subscribers that are active.\n* **inactive**: Only returns subscribers if they are inactive.\n* **twitch**: Only returns subscribers if they are subscribed on Twitch. This only works for partnered channels.", "2-0": "sort", "2-1": "String", "2-2": "Applies a sort to the returned results. Options include:\n\n* **newest** - Default. Sort from newest subscriber to oldest\n* **oldest** - Sort from oldest subscriber to newest.", "3-0": "benefits", "3-1": "Boolean", "3-2": "Default is false. If true, returns the benefits for each subscriber.", "4-0": "tier", "4-1": "Boolean", "4-2": "Default is false. If true, returns tier information for the subscriber." }, "cols": 3, "rows": 5 } [/block] This event emits **app-channel-subscribers** back to your application upon completion. You can listen for this event using Socket.IO as follows: [block:code] { "codes": [ { "code": " socket.on('app-channel-subscribers', function(response){\n // Do something with response.\n });", "language": "javascript" } ] } [/block] The **response** object has the following structure: [block:code] { "codes": [ { "code": "{\n result: {\n status: 1,\n message: \"Channel Subscribers.\"\n },\n channel: {\n names: {\n gamewisp: \"GameWisp channel name\",\n twitch: \"twitch channel name\",\n youtube: \"youtube channel name\"\n },\n ids: {\n gamewisp: \"channel identifier\",\n twitch: \"12312312q\",\n youtube: \"UCiqp4J8asdkssssssssdfae\"\n } \n },\n data: \n {\n channel_id: \"channel-identifier\",\n status: \"authenticated\",\n subscribers: [\n {\n benefits: [\n {\n benefit: {\n id: \"3\",\n delivery: \"delivery-messaging\",\n title: \"Subscriber Messaging\",\n description: \"Receive Subscriber-only messages from me.\",\n channel_data: null,\n type: \"unknown-type\",\n month_delay: null,\n recurring: false,\n recurring_input: false,\n receieve_immediately: false,\n removed_at: null,\n subscriber_limit: null,\n tier_bonus: false,\n quantity: 1,\n multiplier: 1\n },\n fulfillment: {\n id: \"49917\",\n benefit_id: \"3\",\n tier_id: \"856\",\n channel_fulfillment_response: null,\n fulfilled_at: \"2015-12-24 03:55:17\",\n previously_fulfilled_at: null,\n disabled_at: null,\n user_input_provided_at: null,\n recurring: true,\n granted_at: {\n date: \"2015-12-24 03:55:17.000000\",\n timezone_type: 3,\n timezone: \"UTC\"\n },\n channel_cancelled_at: null,\n status: \"active\",\n user_input: null\n }\n },\n //...\n ],\n ids: {\n gamewisp: \"12323\",\n twitch: \"455552422\"\n },\n usernames: {\n gamewisp: \"gamewisp-user-name\",\n twitch: \"twitch-user-name\"\n },\n status: \"active\",\n amount: \"4.99\",\n subscribed_at: \"2015-12-24 00:00:00\",\n end_of_access: \"2016-01-24 23:59:00\",\n tier: {\n id: \"123\",\n title: \"Tier Title\",\n level: \"1\",\n cost: \"4.99\",\n description: \"Tier description\",\n published: true\n }\n },\n //...\n\n }\n ],\n}", "language": "json" } ] } [/block] The response object contains subscriber information (described in detail in the [subscriber-new](https://gamewisp.readme.io/docs/subscriber-new) event documentation), benefit-fulfillment pairs for the subscriber (see [subscriber-benefits-change](https://gamewisp.readme.io/docs/subscriber-benefits-change) ), and the subscriber’s tier (see [subscriber-status-change](https://gamewisp.readme.io/docs/subscriber-status-change) ). Note that you will only receive the full object for a subscriber if both the **benefit** and **tier** parameters of **channel-subscribers** are true. [block:callout] { "type": "warning", "title": "This response may be very large", "body": "Depending on how you use this event, the resulting response object can be very large. \n\nIt is not recommended to grab all the benefit and tier information for every subscriber simultaneously. \n\nIt is preferred to use this event to get a full list of subscribers for a channel, and then check the benefits of individual subscribers through subsequent calls." } [/block]