Tutorials
Uploading video and creating a draft Tweet
Relevant products
Introduction
Advertisers can promote Tweets in campaigns that include creatives, such as images, GIFs, and video. These creatives can be associated with Twitter cards that allow attaching rich photos, videos and media experiences to Tweets.
Advertisers can also promote videos in Tweets, directly or attached to cards, or separately as Pre-roll videos.
This tutorial will describe uploading a video asset via upload.twitter.com, creating a Video App Download Card, and creating a Tweet using the card
Requirements
- Video file
- Less than 500 MBs and less than 140 seconds. See restrictions and guidance.
- An aspect ratio of either 16:9 or 1:1 for a Video App Download Card
- Google or Apple App ID
- Access Tokens for a Twitter Ads account user with either Ad Manager or Account Admin roles
Steps
1. Upload the video
Using the chunked POST media/upload endpoints requires an adjusted workflow from single image uploads. The chunked upload tutorial provides a complete overview of uploading a video to Twitter.
For each video, the application will:
- Initialize the upload using the POST media/upload (INIT) endpoint
- Upload each chunk of bytes using the POST media/upload (APPEND) endpoint
- Complete the upload using the POST media/upload (FINALIZE)
When using the upload.twitter.com endpoint to upload media, use the additional_owners parameter when the media will be used by a user other than the authenticated user. This should be the promotable user for an ads account. See the POST accounts/:account_id/tweets endpoint for further discussion.
2. Verify the Video has been processed.
Periodically query whether Twitter has finished processing the video using GET media/upload (STATUS). If the FINALIZE command returns the field processing_info, you should the call this endpoint every few seconds until this returns "state": "succeeded".
twurl -X GET -H upload.twitter.com "/1.1/media/upload.json?command=STATUS&media_id=931263015239933952"
Response
{
"media_id": 1136358971441176600,
"media_id_string": "1136358971441176577",
"media_key": "13_1136358971441176577",
"size": 4948186,
"expires_after_secs": 1295797,
"video": {
"video_type": "video/mp4"
},
"processing_info": {
"state": "succeeded",
"progress_percent": 100
}
}
3. Move the Video to the Ads Media Library under the Twitter Ads account
After uploading the media, your application should add it to the Media Library using POST accounts/:account_id/media_library
twurl -X POST -H ads-api.x.com "/8/accounts/:account_id/media_library?file_name=myvideo.mpeg&media_category=AMPLIFY_VIDEO&media_key=13_1136358971441176577&name=Latte"
Response
{
"request": {
"params": {
"name": "Late",
"file_name": "myvideo.mpeg",
"media_category": "AMPLIFY_VIDEO",
"account_id": "18ce54uhdu0",
"media_key": 13_1136358971441176577
}
},
"data": {
"tweeted": false,
"duration": 13567,
"name": "Latte",
"file_name": "sample.mpeg",
"description": null,
"media_url": "https://video.twimg.com/amplify_video/1136670181575413760/vid/640x360/zz0E_jTRHjhUGNxK.mp4?tag=13",
"media_category": "AMPLIFY_VIDEO",
"poster_image_url": "https://pbs.twimg.com/amplify_video_thumb/1136670181575413760/img/d4KRzzc_IRHVQSiv.jpg",
"poster_image_media_key": "3_1136670181575413760",
"media_key": "13_1136358971441176577",
"created_at": "2019-06-06T16:24:24Z",
"media_status": "TRANSCODE_COMPLETED",
"media_id": "1136670181575413760",
"title": null,
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2019-06-06T16:25:49Z",
"deleted": false
}
}
Note: an error of "Unauthorized to use media xxxxx" indicates that the media was uploaded with the incorrect additional_owners parameter. Use the user ID of the promotable user for the Twitter Ads account (see step 5).
4. Create Video App Download Card
After the video has been uploaded and successfully processed, create a video app download card using the POST accounts/:account_id/cards/video_app_download endpoint.
twurl -H "ads-api.x.com" "/8/accounts/:account_id/cards/video_app_download" -d
"media_key=13_1136358971441176577&country_code=US&name=video app download&googleplay_app_id=com.company_name.android"
Response
{
"data": {
"name": "video app download",
"googleplay_app_id": "com.twitter.android",
"video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
"video_owner_id": "756201191646691328",
"video_content_id": "958231855240589313",
"id": "5a4z3",
"country_code": "US",
"video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
"created_at": "2018-01-30T07:00:24Z",
"card_uri": "card://958233417929261056",
"updated_at": "2018-01-30T07:00:24Z",
"video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
"app_cta": "INSTALL",
"deleted": false,
"card_type": "VIDEO_APP_DOWNLOAD"
},
"request": {
"params": {
"name": "video app download",
"googleplay_app_id": "com.twitter.android",
"video_id": "13_1119361956324855808",
"video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
"video_stream_content_type": "video/mp4; codecs='avc1.42E01E, mp4a.40.2'",
"video_owner_id": "756201191646691328",
"video_content_id": "958231855240589313",
"account_id": "18ce54uhdu0",
"country_code": "US",
"video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
"video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
"app_cta": "INSTALL",
"card_type": "VIDEO_APP_DOWNLOAD"
}
}
}
5. Verify the credentials have the ability to create Promoted Tweets (optional)
Creating Tweets for a Twitter ads account requires that the authenticated user has permissions to create promotable Tweets on behalf of the promotable user.
Note: calling the GET accounts/:account_id/promotable_users can return which users can be promoted for the ads account along with whether the account can create promoted tweets, FULL, or has been granted access to promote retweets, RETWEETS_ONLY.
If the credentials are not for a FULL promotable user on this account, verify that the authenticated user has permission to Tweet on behalf this user by making a request to the GET accounts/:account_id/authenticated_user_access endpoint. The request response will include a permission of TWEET_COMPOSER to indicate that the user may create nullcasted Tweets on behalf of the FULL promotable user.
6. Create a Draft Tweet using the Video App Download Card
We then associate this card with a Tweet using its card_uri in POST accounts/:account_id/tweet.
Request
twurl -H "ads-api.x.com" "/8/accounts/:account_id/draft_tweets" -d "card_uri=card://1119368073444638720&text=Sample Tweet with card_uri and twurl"
Applications can find the card_uri for existing video app download cards using the GET accounts/:account_id/cards/video_app_download.
Note: a common error is UNAUTHORIZED_ACCESS with a message of “User [X] is not authorized to create tweets for user id [X]” or “Promotable User [X] was not found for Account [X]”. Include as_user_id with the user_id of the FULL promotable user as a parameter.
Next Steps
You now have a Video App Download Card in the Twitter ads account. You can set up a campaign to promote this Tweet.
Ready to build your solution?