YouTube Integration

Connect YouTube to import video content into your knowledge base.

Overview

The YouTube integration allows you to:

• Add individual YouTube videos
• Import entire channels
• Import playlists
• Automatic transcription

Connecting YouTube

1. Go to "Integrations" > "YouTube"
2. Click "Connect YouTube"
3. Sign in with your Google account
4. Grant WizChat access to YouTube
5. Click "Allow"

A YouTube connection belongs to the individual who connected it — your Google login is never shared with anyone else.

Sharing a Connected Channel With Your Team

You don't share your Google credentials to let teammates pull videos from your channel. Instead, you link the channel to a chatbot and then grant per-member access, so chosen members can browse and load videos under your connection.

1. As the chatbot's owner or an admin, open the chatbot's Add Content → YouTube screen and browse your channel once. This first browse links the channel to that chatbot — it now uses your connection.
2. Open the chatbot's Manage Access dialog → select the member → tick "YouTube channel access" → Save. (See Sharing Chatbots → YouTube Channel Access.)
3. The granted member can now browse and load that channel's videos from the chatbot's Add Content → YouTube screen, under your connection.

Keep in mind:

• Off by default for regular members — owners, per-chatbot Admins, and team owners/admins can already browse a linked channel; everyone else needs the explicit grant. The toggle stays disabled until a channel is linked.
• Loading still requires document-upload permission (see who can upload). Browse access alone lets a member view the channel; loading also needs upload permission.
• Private videos are hidden from granted members unless you enable "Let granted members see private videos" on the chatbot. You (the member who connected the channel) always see its private videos.
• A video a member loads is attributed to that member, but it is fetched and transcribed under your connection.

Adding Videos

From Connected Account

1. Go to "Knowledge Base"
2. Click "Add Content" > "YouTube"
3. Browse your videos
4. Select videos to import
5. Click "Import"

Add by link

The channel browse grid doesn't always list every video on your connected channel — YouTube's uploads playlist can omit some. If a video is missing, add it directly by pasting its link, in the "Add by link" box on the same "Add Content" > "YouTube" screen:

1. Paste one or more video links into the box — one per line is the tidiest, but links separated by spaces or commas are read the same way. Standard youtube.com/watch, youtu.be, /embed, /shorts, /live, and legacy /v/ URLs are accepted, as is a bare 11-character video ID. Duplicate links are collapsed automatically.
2. If your knowledge base has scopes, optionally pick one under "Add to scope" to file the videos there; otherwise they go to the chatbot's default scope.
3. Click "Add by link".

Pasted videos are ingested through your connected channel exactly like ones you select from the grid — the same processing steps (fetch, transcribe, chunk, embed) and progress bar. When the batch finishes, a short summary reports how many were added and, if any failed, groups the reasons. Any line that isn't a recognizable YouTube link is ignored and called out before the run starts.

Dashboard-added videos are public

Videos added from the dashboard — by link or from the browse grid — are added as public, meaning every user of the chatbot can query them. This differs from the Management API's ingest endpoint, whose isPublic field defaults to false. Use the API if you need the videos to start private.

note

"Add by link" reaches videos on your connected channel — it's for videos the browse grid doesn't list, not for arbitrary videos on channels you don't own. The Management API ingest endpoint does the same thing programmatically, accepting the same link formats in a links array.

Importing Channels

Import all videos from a channel:

1. Go to "Knowledge Base"
2. Click "Add Content" > "YouTube Channel"
3. Enter the channel URL or search
4. Select the channel
5. Choose import options:
   • All videos
   • Recent videos only
   • Specific playlists
6. Click "Import"

Importing Playlists

1. Go to "Knowledge Base"
2. Click "Add Content" > "YouTube Playlist"
3. Enter the playlist URL
4. Click "Import"

Processing

When you add a video:

1. Fetch - Video metadata is retrieved
2. Transcribe - Audio is transcribed to text
3. Process - Text is chunked and embedded
4. Ready - Content is searchable

Processing Time

Video Length	Estimated Time
< 10 minutes	1-2 minutes
10-30 minutes	2-5 minutes
30-60 minutes	5-10 minutes
> 60 minutes	10+ minutes

Automatic Updates

Keep channel content synced:

1. Go to "Integrations" > "YouTube"
2. Click on a connected channel
3. Enable "Auto-sync"
4. Set frequency (daily, weekly)
5. Click "Save"

Data Retention and Removal

WizChat keeps your imported YouTube content in step with your channel, in line with YouTube's API data policies. This happens automatically while your YouTube account stays connected — you don't need to do anything.

• Videos you remove from YouTube are removed from your chatbot. If you delete a video, take it down, or your channel is removed, a daily check notices the video is gone and automatically deletes its stored transcript and searchable content from that chatbot's knowledge base. Videos you simply make private or unlisted are kept — you still have access to them, so they stay in your knowledge base. If the daily check can't reach YouTube, nothing is deleted: an outage or API error is never read as "the video is gone."
• The cached list of your channel's videos is refreshed within 30 days. So you can browse and pick videos, WizChat keeps a cached copy of your channel's video list. That cache is re-synced at least every 30 days so it never goes stale, and if you revoke WizChat's access to YouTube it is cleared instead. The cache is separate from the videos you have already imported — clearing it removes nothing from your knowledge base.

Disconnecting YouTube does not wipe videos you've already imported — they remain in your knowledge base until you delete them there (or remove them from YouTube).

Viewing Transcripts

1. Go to "Knowledge Base"
2. Find the video document
3. Click to view
4. See full transcript

You can edit transcripts to fix errors.

Limits and Constraints

YouTube imports are subject to:

• Your plan's storage limits
• Provider/API rate limits
• Processing timeouts for very long videos

For direct video file uploads, see Subscription Plans.

Troubleshooting

Video Not Processing

• Check if video is public
• Very long videos may hit processing timeouts
• Ensure video has audio

Poor Transcription

• Original audio quality affects results
• Non-English may have lower accuracy
• Edit transcript manually if needed

OAuth Issues

• Reconnect YouTube if tokens expire
• Check Google account permissions
• Verify API access in Google Console

Management API

The YouTube integration is accessible via the Management API. Connection and video-list endpoints are account-scoped: they operate on the authenticated caller's YouTube connection. Ingesting videos into a chatbot additionally requires edit/upload access to that chatbot.

Check connection status

GET /api/v1/youtube/status

Required scope: videos:read

Returns { connected: boolean, channelTitle?: string }. Account-scoped (not per-chatbot).

Start the YouTube OAuth flow

POST /api/v1/youtube/connect

Required scope: videos:write

Returns an authorizeUrl to redirect the user to in order to grant YouTube access. The connection is completed by the browser callback. Account-scoped.

List your YouTube videos

GET /api/v1/youtube/videos

Required scope: videos:read

Lists videos from the caller's connected YouTube channel. Supports pagination (nextPageToken) and title search (search query parameter). Returns connected: false as a data field (not an error) when no channel is connected.

Response fields vary by mode:

• Normal pagination: connected, videos, nextPageToken, totalResults
• Title search (?search=): connected, videos, search, totalScanned, totalResults, truncated

Both modes may include message when the connected account has no YouTube channel or another non-error condition needs to be shown to the user.

Each video includes: id (YouTube video ID), title, publishedAt, thumbnail.

List a chatbot's linked YouTube channels

GET /api/v1/chatbots/{chatbotId}/youtube/channels

Required scope: videos:read

Returns the YouTube channels linked to the chatbot. A chatbot can have more than one linked channel. Each item includes a channel selector value and the channel title. Pass the channel value to the list-channel-videos and ingest endpoints to specify which channel to work with.

List a linked channel's videos

GET /api/v1/chatbots/{chatbotId}/youtube/channels/{channel}/videos

Required scope: videos:read

Lists videos from one of a chatbot's linked YouTube channels, so you can choose which to import. Use the channel selector from the list-linked-channels endpoint. Exposes only public video metadata — never tokens.

Query parameters:

Parameter	Type	Description
search	string	Case-insensitive title scan across the whole channel. Mutually exclusive with pageToken.
pageToken	string	Page cursor from a previous response's nextPageToken. Mutually exclusive with search.
maxResults	integer	Page size for a browse (default: 50, range 1–50). Ignored when search is used.

Without search, returns one page of videos plus a nextPageToken; with search, scans the whole channel by title.

Ingest YouTube videos into a chatbot

POST /api/v1/chatbots/{chatbotId}/youtube/videos

Required scope: videos:write

Ingests videos into the chatbot's knowledge base. Videos already in the knowledge base are skipped (returned in skippedAlreadyImported). Returns a jobId to track the async ingest.

Request body:

Field	Type	Description
videoIds	string[]	YouTube video IDs to ingest. Optional when links is provided.
links	string[]	YouTube video links (watch, youtu.be, embed, shorts, live, or legacy /v/ URLs) or bare 11-character IDs, parsed to video IDs. Useful for adding a video that is not shown in the channel list.
scopeId	string	Optional knowledge scope to attach the videos to.
isPublic	boolean	Whether the ingested videos are public. Defaults to false.
channel	string	The linked YouTube channel to import from, identified by the value returned by the list-channels endpoint. Optional when only one channel is linked; required when several are.

Provide at least one video via videoIds and/or links — you can mix both. Any link that cannot be parsed to a valid video ID is ignored and returned in the response's invalidLinks array.

See the full API reference for details.

Check an import's progress

GET /api/v1/chatbots/{chatbotId}/youtube/imports/{jobId}

Required scope: videos:read

Returns the progress of a YouTube import. Use the jobId returned when the import was started (see ingest). The response includes the overall status, counts, a per-video status map, and any per-video errors (for example, a video with no captions).

Response fields:

Field	Type	Description
jobId	string	The import job ID.
status	string	One of processing, completed, error, cancelled.
isComplete	boolean	true once the import reached a terminal state.
progress	integer	Percent complete (0–100).
totalVideos	integer	Total videos in the import.
processedVideos	integer	Videos that reached a terminal state.
failedVideos	integer	Videos that failed (for example, no captions).
remaining	integer	totalVideos − processedVideos.
paused	boolean	Whether the import is paused.
currentStage	string	Current processing stage, when running.
stageMessage	string	Human-readable stage detail.
videoStatuses	object	Per-video status keyed by video ID.

Poll this endpoint until isComplete is true (or status is no longer processing) to track an ingest to completion.

See the full API reference for details.

Related

• Uploading Videos
• Knowledge Base Overview
• Management API Reference — YouTube Status
• Management API Reference — Connect YouTube
• Management API Reference — List YouTube Videos
• Management API Reference — List Linked YouTube Channels
• Management API Reference — List a Linked Channel's Videos
• Management API Reference — Ingest YouTube Videos
• Management API Reference — Check a YouTube Import's Progress