YouTube

YouTube API v2.0 – Messages and Video Sharing

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

We are reworking YouTube's messaging functionality. While the v2 API has already been deprecated, some API functionality related to messages and video sharing will begin returning errors as early as March 31, 2014.

At that time, the API will return 403 (Forbidden) HTTP responses to requests to send or delete messages. The API will continue to support retrieval of a user's inbox for around six months after that date. After that time, the API will return an empty list in response to a request to retrieve a user's inbox.

We're excited to provide a new and better API for messaging and video sharing later this year.

Video messages enable YouTube users to easily share videos with other YouTube users. On the YouTube website, a video page displays a link, allowing the user to share that video with one or more people from the user's contact list or with other YouTube users.

The YouTube Data API enables you to retrieve video messages sent to the currently logged-in user's inbox, send a video message from that user to another user, and delete video messages from that user's inbox. Note that the API does not retrieve other types of messages in the user's inbox.

  1. Retrieving messages from a user's inbox
  2. Sending a video message
  3. Deleting a message

Retrieving messages from a user's inbox

To retrieve a feed containing a list of the messages in the currently logged-in user's inbox, send a GET request to the following URL. Note: For this request, you must provide an authentication token. The authentication token enables YouTube to identify the user, and this restriction ensures that a user can only retrieve messages from her own inbox.

https://gdata.youtube.com/feeds/api/users/default/inbox

An API response to a request for an inbox feed contains a series of <entry> tags. Each entry contains information about a video message sent to the user, and inbox feed entries are very similar to entries in a video feed. Inbox entries contain the following key differences:

  • The <name> tag identifies the sender of the message rather than the owner of the video being sent.

  • The <title> tag contains the subject of the message rather than the video title. The video title still appears in the <media:title> tag.

  • The <summary> tag is included in an inbox feed entry. The tag contains the text of the message.

  • The <content> tag contains the text of the message. This tag contains the same value as the <summary> tag.

  • The <published> tag specifies the date and time that the message was sent rather than the date and time that a video was uploaded.

  • The <link> tag that has a rel attribute value of alternate specifies the URL for the video sent in the message. The user can watch the video at that URL.

  • The <link> tag that has a rel attribute value of edit specifies the edit URL for the message. You would send a DELETE request to this URL to delete the message.

The following XML shows a sample API response containing an inbox feed:


<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
  <id>tag:youtube,2008:user:GoogleDevelopers:inbox</id>
  <updated>2008-07-21T17:54:30.236Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
  <title>Inbox of GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com/my_messages?folder=inbox&amp;filter=videos'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
    <id>tag:youtube,2008:user:GoogleDevelopers:inbox:D_uaXzLRX1U</id>
    <published>2008-06-10T13:55:32.000-07:00</published>
    <updated>2008-06-10T13:55:32.000-07:00</updated>
    <app:edited
  xmlns:app='http://www.w3.org/2007/app'>2008-06-10T20:55:32.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
      term='surfing'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
      term='People' label='People &amp; Blogs'/>
    <title>GoogleDeveloperssFriend sent you a video!</title>
    <summary>Check out this video!</summary>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/watch?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/responses?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/ratings?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/complaints?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#mobile'
      type='text/html' href='https://m.youtube.com/details?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.related'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/related?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox/ffb9a5f32cd5f55?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/inbox/ffb9a5f32cd5f55?v=2'/>
    <author>
      <name>GoogleDeveloperssFriend</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDeveloperssFriend</uri>
      <yt:userId>tXKDgv1AVoG88PLl8nGXmw<</yt:userId>
    </author>
    <media:group>
      <media:title type='plain'>Learning the ABCs</media:title>
      <media:description type='plain'>
        A great method for teaching kids the alphabet.
      </media:description>
      <media:keywords>alphabet, teaching, children</media:keywords>
      <yt:duration seconds='202'/>
      <yt:videoid>jXE6G9CYcJs</yt:videoid>
      <media:credit role='uploader' scheme='urn:youtube'
          yt:display='GoogleDeveloperssFriend'>GoogleDeveloperssFriend</media:credit>
      <media:category label='Education'
        scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>
        Education</media:category>
      <media:content url='http://www.youtube.com/v/jXE6G9CYcJs'
        type='application/x-shockwave-flash' medium='video' isDefault='true'
        expression='full' duration='202' yt:format='5'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySANFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='1'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySARFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='6'/>
      <media:player url='https://www.youtube.com/watch?v=jXE6G9CYcJs'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/default.jpg'
        height='90' width='120' time='00:01:41' yt:name='default'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/hqdefault.jpg'
        height='360' width='480' yt:name='hqdefault'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/mqdefault.jpg'
        height='180' width='320' yt:name='mqdefault'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/1.jpg'
        height='90' width='120' time='00:00:50.500' yt:name='start'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/2.jpg'
        height='90' width='120' time='00:01:41' yt:name='end'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/3.jpg'
        height='90' width='120' time='00:02:31.500' yt:name='middle'/>
    </media:group>
    <yt:statistics viewCount='286355' favoriteCount='201'/>
    <gd:rating min='1' max='5' numRaters='877' average='3.88'/>
    <gd:comments>
      <gd:feedLink
        href='https://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/comments'
        countHint='1088'/>
    </gd:comments>
  </entry>
</feed>

Sending a video message

To send a message, you will send an authenticated POST request that identifies the user to whom the message is being sent. The XML sent in the request body specifies the <yt:videoid> of the video being sent and the text of the message.

The following sample request demonstrates how to send a video through the API:

POST /feeds/api/users/MESSAGE_RECIPIENT_USERNAME/inbox HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY


<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <id>Qm6znjThL2Y</id>
  <summary>sending a message from the api</summary>
</entry>

Note: A user can only send videos to users in his contact list.

The following steps describe a common use case for sending a message:

  1. This use case begins with a request to retrieve information about a specific video.

  2. After watching the video, the user clicks a link to share the video.

  3. Your application submits a request to retrieve the contact list for the currently authenticated user.

  4. Your application displays a form that allows the user to select one or more contacts to send the video to. The form could also display a text area to allow the user to write a message to those contacts.

  5. After the user submits the completed form, your application loops through the list of selected contacts and submits an API request to send the video to each user.

Deleting a message

The following sample API request demonstrates how to delete a message:

DELETE /feeds/api/users/default/inbox/MESSAGE_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following steps describe a common use case for deleting a message:

  1. This use case begins with a request to retrieve the video messages in a user's inbox.

  2. Your application displays the list of video messages as well as a checkbox next to each message allowing the user to delete that message from her inbox.

  3. The user checks one or more messages and submits her changes.

  4. Your application loops through the messages and sends a DELETE request to delete each selected message. Your application would send each API request to the edit URL for the corresponding message.

pagination links

« Previous
Contacts
Next »
Retrieving Live Events

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.