Announcement: Tweet Drafts

announcements

#1

Available today in v3 of the Ads API, Tweets can now be saved as Drafts, with the option to publish only when deemed ready by approved accounts. This update helps improve creative approval and quality assurance processes. In addition, Tweet Drafts are only visible to ad account contributors and will not appear in the Gnip Firehose.

Before starting a campaign, Tweets can be drafted, reviewed in the Draft preview, and edited as necessary. Once Tweets are ready to be shared, they can be scheduled for the future or published immediately. The subsequent Scheduled or published Tweets can then be added to a campaign and the draft can be deleted.

See our reference documentation. See below for a mini-guide.

Twitter Ads API Team


Create your first draft with text only.

$ twurl -X POST -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets?text=It's what's happening.&as_user_id=756201191646691328"
{
  "request": {
    "params": {
      "text": "It's what's happening.",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "id_str": "994662753636777984",
    "text": "It's what's happening.",
    "user_id": "756201191646691328",
    "id": 994662753636777984,
    "media_ids": [],
    "nullcast": true,
    "created_at": "2018-05-04T19:37:35Z",
    "card_uri": null,
    "updated_at": "2018-05-04T19:37:34Z",
    "media_keys": []
  }
}

Preview it to get a sense of what it’d look like.

$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/preview/994662753636777984"

Decide that the Tweet would be much better with an image. Upload the image using the POST media/upload endpoint.

$ twurl -X POST -H upload.twitter.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file coffee.jpeg --file-field "media"
{
  "media_id": 994665619999023105,
  "media_id_string": "994665619999023105",
  "size": 260835,
  "expires_after_secs": 86400,
  "image": {
    "image_type": "image/jpeg",
    "w": 1600,
    "h": 836
  }
}

Update the draft. Attach the image.

$ twurl -X PUT -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/994662753636777984?media_ids=994665619999023105"
{
  "request": {
    "params": {
      "draft_tweet_id": 994662753636777984,
      "media_ids": "994665619999023105"
    }
  },
  "data": {
    "id_str": "994662753636777984",
    "text": "It's what's happening.",
    "user_id": "756201191646691328",
    "id": 994662753636777984,
    "media_ids": [
      "994665619999023105"
    ],
    "nullcast": true,
    "created_at": "2018-05-04T19:37:35Z",
    "card_uri": null,
    "updated_at": "2018-05-04T19:51:09Z",
    "media_keys": [
      "3_994665619999023105"
    ]
  }
}

Preview the Tweet again.

$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/preview/994662753636777984"

Update the text.

$ twurl -X PUT -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/994662753636777984?text=Coffee is happening"
{  
   "request":{  
      "params":{  
         "draft_tweet_id":994662753636777984
      }
   },
   "data":{  
      "id_str":"994662753636777984",
      "text":"Coffee is happening",
      "user_id":"756201191646691328",
      "id":994662753636777984,
      "media_ids":[  
         "994665619999023105"
      ],
      "nullcast":true,
      "created_at":"2018-05-04T19:37:35Z",
      "card_uri":null,
      "updated_at":"2018-05-07T23:44:20Z",
      "media_keys":[  
         "3_994665619999023105"
      ]
   }
}

Preview it one last time to make sure it looks good before publishing it.

$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/preview/994662753636777984"

Next, capture the draft’s metadata, which will be used to create an actual Tweet.

$ draft=$(twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/994662753636777984")
$ text=$(echo $draft | jq -r '.data.text')
$ as_user_id=$(echo $draft | jq -r '.data.user_id')
$ media_ids=$(echo $draft | jq -r '.data.media_ids[0]')
$ nullcast=$(echo $draft | jq -r '.data.nullcast')

Create the Tweet.

$ twurl -X POST -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/tweet?text=$text&as_user_id=$as_user_id&media_ids=$media_ids&nullcast=$nullcast"
{  
   "data":{  
      "created_at":"Thu May 10 23:52:56 +0000 2018",
      "id":994727017688977408,
      "id_str":"994727017688977408",
      "text":"Coffee is happening https:\/\/t.co\/1n0pRX96v0",
      "truncated":false,
      "entities":{  
         "hashtags":[  

         ],
         "symbols":[  

         ],
         "user_mentions":[  

         ],
         "urls":[  

         ],
         "media":[  
            {  
               "id":994665619999023105,
               "id_str":"994665619999023105",
               "indices":[  
                  20,
                  43
               ],
               "media_url":"http:\/\/pbs.twimg.com\/media\/Dc3DHIZV4AEXW7I.jpg",
               "media_url_https":"https:\/\/pbs.twimg.com\/media\/Dc3DHIZV4AEXW7I.jpg",
               "url":"https:\/\/t.co\/1n0pRX96v0",
               "display_url":"pic.twitter.com\/1n0pRX96v0",
               "expanded_url":"https:\/\/twitter.com\/apimctestface\/status\/994727017688977408\/photo\/1",
               "type":"photo",
               "sizes":{  
                  "thumb":{  
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "small":{  
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  },
                  "large":{  
                     "w":1600,
                     "h":836,
                     "resize":"fit"
                  },
                  "medium":{  
                     "w":1200,
                     "h":627,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"\u003ca href=\"https:\/\/ads-api.twitter.com\" rel=\"nofollow\"\u003eAds API Internal Test App\u003c\/a\u003e",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{  
         "id":756201191646691328,
         "id_str":"756201191646691328",
         "name":"API McTestface",
         "screen_name":"apimctestface",
         "location":"San Francisco, CA",
         "url":null,
         "description":"Into testing and APIs",
         "protected":false,
         "followers_count":103,
         "friends_count":0,
         "listed_count":0,
         "created_at":"Thu Jul 21 18:56:28 +0000 2016",
         "favourites_count":1,
         "utc_offset":null,
         "time_zone":null,
         "geo_enabled":false,
         "verified":false,
         "statuses_count":7,
         "lang":"en",
         "contributors_enabled":false,
         "is_translator":false,
         "is_translation_enabled":false,
         "profile_background_color":"000000",
         "profile_background_image_url":"http:\/\/abs.twimg.com\/images\/themes\/theme1\/bg.png",
         "profile_background_image_url_https":"https:\/\/abs.twimg.com\/images\/themes\/theme1\/bg.png",
         "profile_background_tile":false,
         "profile_image_url":"http:\/\/pbs.twimg.com\/profile_images\/756348317458509825\/DTKcRCpS_normal.jpg",
         "profile_image_url_https":"https:\/\/pbs.twimg.com\/profile_images\/756348317458509825\/DTKcRCpS_normal.jpg",
         "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/756201191646691328\/1469162431",
         "profile_link_color":"000000",
         "profile_sidebar_border_color":"000000",
         "profile_sidebar_fill_color":"000000",
         "profile_text_color":"000000",
         "profile_use_background_image":false,
         "has_extended_profile":true,
         "default_profile":false,
         "default_profile_image":false,
         "following":true,
         "follow_request_sent":false,
         "notifications":false,
         "translator_type":"none"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[  
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{  
         "followers":false
      },
      "lang":"en"
   },
   "request":{  
      "params":{  
         "as_user_id":756201191646691328,
         "text":"Coffee is happening",
         "account_id":"18ce54d4x5t",
         "media_ids":[  
            994665619999023105
         ],
         "nullcast":true
      }
   }
}

Link to the actual Tweet.

Finally, clean up. Delete the draft.

$ twurl -X DELETE -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/draft_tweets/994662753636777984"
{
  "request": {
    "params": {
      "draft_tweet_id": 994662753636777984
    }
  },
  "data": {
    "id_str": "994662753636777984",
    "text": "Coffee is happening",
    "user_id": "756201191646691328",
    "id": 994662753636777984,
    "media_ids": [
      "994665619999023105"
    ],
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-04T19:37:35Z",
    "card_uri": null,
    "updated_at": "2018-05-10T23:53:07Z",
    "media_keys": [
      "3_994665619999023105"
    ]
  }
}

Twitter cards preview
GET tweet preview using image card/ website card
Announcement: Creative review tools now available
Tweet with card preview - V3