YouTube Connector

These endpoints control the YouTube Connector module.

Note

For the YouTube Connector module, the base URL for the API gateway endpoints is https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube.

Get YouTube Channel ID

HTTP Request Example

GET /getUserId/discord HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "userId": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "userName": "discord",
    "displayName": "Discord"
}

This endpoint retrieves the channel ID of a YouTube channel, given its title.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/getUserId/:userName

HTTP Response

The response object contains the following parameters:

Parameter	Type	Description
userId	String	The ID of the YouTube channel.
userName	String	The custom URL alias of the YouTube channel, if set. Otherwise, the ID of the YouTube channel.
displayName	String	The title of the YouTube channel.

Get YouTube Feeds

HTTP Request Example

GET /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "feeds": [
        {
            "id": "6254614394036b506e6d08c2",
            "feed_identifier": "UCPuGLlmOHLb2xwl82pxqHBA",
            "webhook_options": {
                "filter_event": [
                    "added"
                ],
                "filter_words": null,
                "filter_mode": "OR",
                "filter_excl": false,
                "nsfw": null,
                "custom_header": null,
                "webhook-name": null,
                "no-username-overwrite": false,
                "no-avatar-overwrite": false
            },
            "display_info": {
                "user_name": "UCPuGLlmOHLb2xwl82pxqHBA",
                "display_name": "GiselleBot",
                "user_url": "https://www.youtube.com/channel/UCPuGLlmOHLb2xwl82pxqHBA"
            },
            "webhook_info": {
                "name": "GiselleBot Social Feeds",
                "avatar": null,
                "channel_id": "598433171641729024"
            }
        },
        ...
    ]
}

This endpoint retrieves the list of feeds for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds

HTTP Response

The response contains the feeds array. Each element of the array has the following parameters:

Parameter	Type	Description
id	String	The feed unique ID.
feed_identifier	String	The feed-specific identifier.
webhook_options	Object	The feed-specific webhook options.
webhook_info	Object	The information about the webhook the feed is streaming to.

The webhook_options object contains the following parameters:

Parameter	Type	Description
filter_event	?Array<String>	An array of event types to filter (i.e. whitelist) when posting items to the feed. `null` means that the filter is disabled. When populated, this array can only contain one of these values: `added`, `updated`.
filter_mode	String	The filter behavior when more than one word is added to the whitelist filter (`filter_words`). This can be either `AND` or `OR`.
nsfw	?String	The NSFW behavior to apply when posting items to the feed if they are deemed to be so. `null` means that the NSFW behavior is disabled. When populated, this can be either `censor`, `skip` or `only`.
filter_words	?Array<String>	An array of words to filter (i.e. whitelist or blacklist, depending on `filter_excl`) when posting items to the feed. `null` means that the filter is disabled.
filter_excl	Boolean	When set to `true`, items will be posted to the feed only if they do not contain the filtered word(s). When set to `false`, items will be posted to the feed only if they do contain the filtered word(s).
custom_header	?String	A custom template to use as message content when posting items to the feed. Custom headers can have a maximum of 1024 characters. `null` means that the default header will be used.
webhook-name	?String	A custom name to use as webhook name (i.e. author) when posting items to the feed. Custom names can have a maximum of 32 characters. `null` means that the default webhook name will be used.
no-username-overwrite	Boolean	When set to `true`, the webhook name defined within the "Integrations" section of Discord will not be overwritten by the default or custom webhook name.
no-avatar-overwrite	Boolean	When set to `true`, the webhook avatar defined within the "Integrations" section of Discord will not be overwritten by the default webhook avatar.

The display_info object contains the following parameters:

Parameter	Type	Description
user_name	String	The custom URL alias of the YouTube channel, if set. Otherwise, the ID of the YouTube channel.
display_name	String	The title of the YouTube channel.
user_url	String	The URL of the YouTube channel.

The webhook_info object contains the following parameters:

Parameter	Type	Description
name	String	The name of the webhook.
avatar	String	The avatar hash of the webhook.
channel_id	String	The ID of the channel the webhook belongs to.

Create YouTube Feed

HTTP Request Example

POST /feeds HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "feed_identifier": "discord",
    "webhook_channel": "598433171641729024",
    "webhook_options": {
        "filter_event": ["added"]
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625461a794036b506e6d08c4",
    "feed_identifier": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "webhook_options": {
        "filter_event": [
            "added"
        ],
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": false,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.youtube.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint creates a new feed in a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds

Request body parameters:

Parameter	Type	Required	Description
feed_identifier	String	true	The feed-specific identifier.
webhook_channel	String	true*	The ID of the channel the feed will be posted to. If the channel ID is specified, the bot will attempt to create a webhook in that channel (if a usable one isn't already present). At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_url	String	true*	The URL of the webhook the feed will be posted to. At least one between `webhook_channel` and `webhook_url` must be filled.
webhook_options	Object	false	The options for the feed, as described in the corresponding object in Get YouTube Feeds. If you don't pass one or more options, or don't pass the whole object, default options will be used.

feed_identifier must be a YouTube channel title (unreliable) or channel ID. The corresponding parameter of the response will always be the YouTube channel ID.

Note

To find the YouTube channel ID from a YouTube channel title (unreliable), use Get YouTube Channel ID.

HTTP Response

The response consists of a feed object.

Refer to Get YouTube Feeds for the full list of parameters.

Update YouTube Feed

HTTP Request Example

PATCH /feeds/625461a794036b506e6d08c4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

{
    "webhook_options": {
        "no-username-overwrite": true
    }
}

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "625461a794036b506e6d08c4",
    "feed_identifier": "UCZ5XnGb-3t7jCkXdawN2tkA",
    "webhook_options": {
        "filter_event": null,
        "filter_words": null,
        "filter_mode": "OR",
        "filter_excl": false,
        "nsfw": null,
        "custom_header": null,
        "webhook-name": null,
        "no-username-overwrite": true,
        "no-avatar-overwrite": false
    },
    "display_info": {
        "user_name": "discord",
        "display_name": "Discord",
        "user_url": "https://www.youtube.com/discord"
    },
    "webhook_info": {
        "name": "GiselleBot Social Feeds",
        "avatar": null,
        "channel_id": "598433171641729024"
    }
}

This endpoint updates a feed in a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds/:feedId

You must send a body with the updated webhook_options object. Refer to Get YouTube Feeds for the full list of parameters. You cannot update the feed_identifier, webhook_channel or webhook_url for an existing feed.

HTTP Response

The response consists of a feed object.

Refer to Get YouTube Feeds for the full list of parameters.

Delete YouTube Feed

HTTP Request Example

DELETE /feeds/625461a794036b506e6d08c4 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

This endpoint deletes a feed in a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/youtube/feeds/:feedId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the feed was successfully deleted.