Tutorials / Promoting another user's Tweets

Promoting another user's Tweets

Relevant products

Promoted Users API >
Promoted Tweet API >
Scheduled Promoted Tweet API >
Ads API >

Introduction

Advertisers can promote another user's Tweets after obtaining permission to promote their content. You can make requests to the promoted Tweet endpoints by directly referencing the Tweet ID of the Tweet you'd like to promote.

This tutorial describes identifying the RETWEET_ONLY Promotable User, verifying the credentials uses have permission to create Promoted Tweets , and Option A creating a Promoted Tweet immediately or Option B scheduling a Promoted Tweet for a future time.

Requirements

  • A Twitter Ad account that has a RETWEET_ONLY Promotable User
  • Access to the Twitter RETWEET_ONLY Promotable User account with a published Tweet and Scheduled Tweet. 
  • Access Tokens for a Twitter Ads account user with either Ad Manager or Account Admin roles and ability to create promoted-only Tweets. 
  • An Twitter Ad account that has a campaign and line item set up to promote Tweets, such as ENGAGEMENTS.

Steps

1. List the Promotable Users

Calling the GET accounts/:account_id/promotable_users endpoint returns a list of users whose Tweets can be promoted by the ads account. The promotable user type may be FULL or RETWEETS_ONLY. The FULL promotable user is the owner of the ads account. (An ads account can only be owned by one user.) If the ads account is has been granted access to promote Tweets for another user, the promotable user type will be RETWEETS_ONLY.

twurl -H ads-api.x.com "/8/accounts/abc123/promotable_users"

      {
  "request": {
  "params": {
      "account_id": "abc123"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "user_id": "12345",
      "id": "l310s",
      "created_at": "2016-07-21T22:42:09Z",
      "updated_at": "2016-07-21T22:42:09Z",
      "deleted": false,
      "promotable_user_type": "FULL"
    },
    {
      "user_id": "56789",
      "id": "ozor5",
      "created_at": "2017-03-10T17:51:24Z",
      "updated_at": "2019-07-02T08:06:44Z",
      "deleted": false,
      "promotable_user_type": "RETWEETS_ONLY"
    }
  ]
}

2. Verify the credentials have the ability to create Promoted Tweets (optional)

In order to create Tweets on behalf of another user, the authenticated user must have the TWEET_COMPOSER permission. This will only allow them to create nullcasted (or "Promoted-only") Tweets. Use the GET accounts/:account_id/authenticated_user_access endpoint in order to verify that the authenticated user has this permission.

 

Option A. Promoting an existing Tweet

3. Obtain the user's public Tweet

Find a Tweet for the user you have the ability to promote using the GET accounts/:account_id/tweets passing in the user_id from the previous request.

$ twurl -H ads-api.x.com "/8/accounts/18ce54d4x5t/tweets?tweet_type=PUBLISHED&trim_user=trueuser_id=2417045708"

      [
  {
    "created_at": "Sat Jul 27 18:20:40 +0000 2019",
    "id": 1143347463765426177,
    "id_str": "1143347463765426177",
    "text": "One year ago",
    ...
   }
]

4. Create a Promoted Tweet

Call the Promoted Tweets endpoint and include the Tweet ID of a published Tweet from a promotable user's account as well as the line item ID which you'd like to associate the Tweet with.

$ twurl -X POST -H ads-api.x.com "/5/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1143347463765426177"

      {
   "request": {
     "params": {
       "tweet_ids": [
         1143347463765426177
       ],
       "line_item_id": "6c62d",
       "account_id": "18ce54d4x5t"
     }
   },
   "data": [
     {
       "line_item_id": "6c62d",
       "id": "3jzjq6",
       "entity_status": "ACTIVE",
       "created_at": "2019-07-11T21:29:48Z",
       "updated_at": "2019-07-11T21:29:48Z",
       "approval_status": "ACCEPTED",
       "tweet_id": "1149430614224855040",
       "deleted": false
     }
   ],
   "total_count": 1
 }

This Tweet will now be promoted when the campaign is active.

 

Option B. Scheduling a Promoted Tweet for the future

3. Obtain the Scheduled Tweet (unpublished Tweet)

You will need the Scheduled Tweet for the RETWEET_ONLY user's ads account. The following request demonstrates accessing the Scheduled Tweets for 18ce54aymz3.

twurl -H ads-api.x.com "/5/accounts/18ce54aymz3/scheduled_tweets/1149433959404539904"

      {
 "request": {
     "params": {
      "scheduled_tweet_id": 1149433959404539904
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "1149433959404539904",
    "text": "18ce54d4x5t will promote this in the future",
    "user_id": "2417045708",
    "scheduled_status": "SCHEDULED",
    "id": 1149433959404539904,
    "media_ids": [],
    "nullcast": true,
    "created_at": "2019-07-11T21:43:06Z",
    "scheduled_at": "2019-11-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2019-07-11T21:43:05Z",
    "tweet_id": null,
    "media_keys": []
  }
}

4. Create a Scheduled Promoted Tweet

We create a Scheduled Promoted Tweet on our Ads account, 18ce54d4x5t, using the Scheduled Tweet id_str from the RETWEET_ONLY ads account.

twurl -X POST -H ads-api.x.com "/5/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=6c62d&scheduled_tweet_id=1149433959404539904"

      {
  "data": {  "line_item_id": "6c62d",
    "id": "300dd",
    "created_at": "2019-07-11T21:43:51Z",
    "updated_at": "2019-07-11T21:43:51Z",
    "scheduled_tweet_id": "1149433959404539904",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "6c62d",
      "scheduled_tweet_id": 1149433959404539904,
      "account_id": "18ce54d4x5t"
    }
  }
}

This Scheduled Promoted Tweet will be served on the scheduled_at date of the Scheduled Tweet. 

Ready to build your solution?

Sign up for developer access to get started

Sign up for access