7 “Gotchas” while launching a twitter sweepstake campaign
Authors: Joydeep Ghosh & Madhusudan RA
Recently our team implemented a sweepstake campaign for a CPG (Consumer Packaged Good) customer. The campaign was held for few days only. Any valid twitter user who followed the customer official twitter handle and retweeted the promotional tweet during those days, became an automatic participant of the sweepstake and received a Direct Message on twitter revealing the news of her winning a reward or a “try next time” message.
While implementing this ostensibly simple requirement, we came across a series of learnings and discoveries throughout the design and development phase, which we would like to share here.
1) Follow me on the Big Day
Since the requirement revolves around a specific tweet, it is of utmost importance that the tweet ID of that specific tweet is identified and captured at the beginning itself. It is required for filtering the subsequent actions from Account Activity API, like retweet, reply etc. against that tweet, which are building block to decide a user’s participation eligibility.
Now, it would not be possible to have the tweet ID available before it was posted. So, where do we get the tweet ID. Two options we evaluated –
Identify the tweet with unique hashtag for the first ever post and then use the tweet ID post the first identification. But this will not work if the post has been scheduled beforehand. This is because, the “post tweet” action will never occur during the campaign execution timeframe for a scheduled post.
In case the tweet is scheduled one, find the tweet ID of the scheduled tweet and use it for filtering purpose. This is a much preferred option because it does not have any dependency on a hashtag, since hashtag is business driven, any control on that for technical purpose is not recommended.
2) #ChooseAPIwiselyTheySaid
While it may sound a no-brainer to choose v2.0 over v1.0 or v1.1, you may soon discover that v2 version is available for only handful of APIs. And for our use case, none of those fundamental & tweet APIs listed under v2 are of any use. And then we found, as of now this is just “Early Access” API list and Twitter says — “We intend for this new v2 Twitter API to replace the standard v1.1, premium v1.1, and enterprise APIs in the future. For more detail about our plans for the new Twitter API, visit our Guide to the future.”
So, definitely sticking to v1.1 is the option to proceed, at least the time we are writing this article.
3) Catch me if you can
User action like “retweet” against the promotional tweet can be captured through various approach. Our primary thought was to use Search API periodically to pull all “retweet of” information for the promotion tweet. However, soon we realized the limit of records returned by the Search API will not support our cause. At a maximum only 500 rows can be pulled using Search API at a time. And even though paginated call is possible, this is not a scalable approach to find a new retweet.
So, we decided to avoid any pull option because all such options has a limit and focus on Push action from twitter side, which can help. We discovered “Account Activity API” which answers this mystery pretty well. (Ref: https://developer.twitter.com/en/docs/twitter-api/enterprise/account-activity-api/overview ). It is a web-hook setup, which provides the ability to subscribe to real-time activities related to a user account.
We also noticed, there is a limit on how many webhook can be deployed based on the Sandbox vs Premium vs Enterprise version of the API as well as Retries/Replay capability attached with it. After pondering over all three variations, we went ahead with Premium one because it has two webhook setup capability as well as Retries which ensures we do not miss any retweet. At the time of writing of this article it costs around 350 USD and it is definitely worth buying.
4) Yes Officer, I saw the rate limit
Before starting to use the Twitter API, there are two basic requirements — First, setup a developer account and second, create an app. Twitter reviews and approves your app based on the use case description you have provided in the App. Twitter usually approved the app pretty quickly, once done you should be able to get your API and secret Keys from the App Management section of the Developer portal. Note that the keys and tokens will display only once on the developer portal, in case you lose them, you would need to regenerate them from the Developer portal. So, please maintain them in a secured password protected system.
Twitter sets some rate limits for their Standard API’s, however there are not rate limits for Premium API’s. The detailed Rate limits for apps & users can be found in this link.
From our Instant-Win campaign perspective we had to work with a rate limit of 15000 DM’s over a 24-hour window. Since the campaign managers were expecting around 30000 entries per day for the first couple of days, we had to find a solution to work around the rate limits provided by Twitter.
Through interaction with the Twitter team, the following options were suggested & implemented to extend the default rate limits:
1) Use of a Call-To-Action(CTA) button with a message — “I agree to participate in the campaign” which would entice the users respond to the Direct Message thereby resetting the API rate limit. More details about how to add CTA’s to DM’s can be found here
2) Since the customer’s Twitter account was a verified business account, the Twitter team would add the App to a profile with a higher DM Rate Limit for the duration of the promotion. This activity would have to be done by the Twitter API team through an internal process
5) Enhance Your Calm
Twitter politely requests you to calm down when you reach any of the rate limits for the API’s. With Twitter API’s rate limiting, the two common errors the API responds with are:
1) HTTP 420 — Returned when an app is being rate limited for making too many requests.
2) HTTP 429 — Returned when a request cannot be served due to the app’s rate limit having been exhausted for the resource. See Rate Limiting.
Understanding the response codes is an important part of using the Twitter API. Twitter also provides the following HTTP headers to understand where the app is at for a given rate limit as described here
Twitter also provides an API to Get the App Rate Limit status as documented here
6) How do I get my followers?
One of the KPI’s of a successful InstantWin campaign is to increase the number of Twitter followers. Hence, the campaign mechanic was designed to ensure the users follow the account to be an eligible participant of the promotion.
The Account Activity API does provide a couple of attributes which intend to show if the user who retweeted the campaign tweet is an existing follower. However, the API always seems to return a NULL value for both the fields as confirmed by the Twitter API support team.
The alternate option was to maintain all the Followers in a Database Table and set up a web hook using the Account Activity API to add any new followers to the table. We leveraged the GET followers/ids API to retrieve the existing followers. The Results are given in groups of 5,000 user IDs and multiple “pages” of results can be navigated through using the next_cursor value in subsequent requests as documented here.
We setup a webhook to the Account Activity API to get new followers into the same table.
7) Personalize a DM with an image
Twitter provides the Media Upload API for uploading personalized images to Twitter. Once the media upload is done, the API responds with a media_id which can be used as a parameter in the other API’s like the Direct Message API. There are restrictions on the size & type of media that can be uploaded.
One caveat we found is that Twitter does not persist the media once uploaded, hence we were required to upload the media each time we wanted to send a Direct Message.
We could not find any defined rate limits for the Media Upload API documentation provided by Twitter & ran into the HTTP 429 issues. We had to throttle our application requests to 400 requests per 15-minute window after a fair amount of testing.
An alternate solution could be to use the X-Rate-* headers which are returned as part of the media upload API response to throttle the requests.
The upshot is that twitter APIs take a little getting used to and has few stricter rules which may need to be worked-around along the journey. However, the potential benefits of twitter campaign far outweigh these considerations.
