A Guide To Twurl and the Twitter API
If you’re a developer and a fan of Twitter, chances are that you’ve used the Twitter API once or twice. If not, it’s alright because that’s what this article is about. As someone who had very little knowlege of anything code related, getting started with the Twitter API was tough. Questions were asked, people were probably annoyed… Eventually, I familiarized myself by experimenting and playing around.
Understanding the API is fairly simple. When you send a request, Twitter returns data using JSON. To make things a bit more simple, Twitter also has an OAuth-enabled curl tailored specifically to the Twitter API. They call it twurl. Why? Because it’s like curl but for Twitter. Twurl makes it easy to authorize an account and experiment with the available Endpoints. It also gives you the ability to swap between access tokens and accounts.
Installing twurl
Mac
Windows
Now that twurl is installed on your system, you’ll want to install jq. jq allows responses to be processed in JSON form. To get a response, add “ | jq” to the end of a request.
Before you get started with the Twitter API, you will want to create and authorize an application. To do so, you will need a Developer Account. Navigate to dev.twitter.com and Apply. Once approved, create an app with the permissions that you want. Take note of the access token and access secret. You will need those keys when authorizing.
Now that you have authorized an application to an account, you can familiarize yourself with some of the docs.
It’s necessary to include -X and to specify your request method (GET, by default, or POST). -H is equally important because that is the command needed to specify the host URL. The Twitter Developer Docs should help greatly as they tell you which method is used. The nice folks over @TwitterDev also provide some tutorials to help you get started.
Use #1: Sending a Tweet
Say that I want to send out a Tweet with the text “Hello! This Tweet was sent via the Twitter API.” I would look at the Docs and find the POST statuses/update endpoint. Knowing a little bit about how twurl requests look, I simply convert the given JSON request to twurl.
Be sure to look at the available parameters. You can make your Tweet nullcast (invisible on the public timeline), you can add media or add a Card, etc.
Here is an example with in_reply_to_status_id, media_ids, and the nullcast parameters.
Request
Response
Use #2: Creatives
Note: Building Creatives through the Twitter API requires you to have an Ads Account as well as Ads API Access.
If you have Twitter Ads API Access, you are able to create Creatives through the API. Not all creatives are available for anyone to create. Some are in beta, some require whitelisting, and some aren’t even public yet.
First, let’s create a Card that is available to everyone (with Ads API access). A simple Website Card that points towards the Twitter Developers website.
Visit the POST accounts/:account_id/cards/website and view the example and parameters.
Request
Response
Take note of the provided card_uri. We will need that when adding the card to a Tweet.
Composing a Tweet with the Website Card Attached
Next, let's create a Conversation Card with two CTAs. These cards require whitelisting so if you’d like access for yourself or your company, visit the Help tab on ads.twitter.com.
First, visit the POST accounts/:account_id/cards/image_conversation endpoint and check out what you can do with additional parameters.
Request
Response
Keep note of the card_uri.
Add the Conversation Card to a Tweet
Request
Response
Now let's create a Direct Message Card. Personally, these are my favorite because they lead to any Direct Message experience that you can create. With that in mind, unless you’re using a third-party platform for a DM bot (Iris, Blue Robot, QWVR, etc), you will need to be whitelisted for the Account Activity API aswell.
If you are using a third-party platform, make sure to take note of the Welcome Message ID(s). The ID(s) will be used to direct a user to a specific experience. For this example, I will be using the Default Welcome Message ID, given through the Iris Platform, to create a Direct Message Card with one CTA.
Once you have the ID(s) you can get started. Navigate to the POST accounts/:account_id/cards/image_direct_message endpoint and view the example and parameters.
Request
Response
Take note of the card_uri.
Add the Card to a Tweet
Request
Response
Use #3: Uploading Media
Lastly, I’ll go over how to upload media to Twitter via the API. This is only necessary for when you need the media_id parameter. The best possible way to do this is by using the chunked uploading method. This works for images (GIF, PNG, JPG) and Video (MP4). For each media asset uploaded, it will go to your media library either located on the Ads Platform or on studio.twitter.com if you are whitelisted for the Twitter Media Studio product.
When using the chunked method, there are three stages. INIT, APPEND and FINALIZE.
Let's begin. I will be uploading this image of the Twitter logo on a white background. The size is 1200x627 so it’s the correct dimensions that Cards require.
Start with INIT.
total_bytes = the exact number of bytes your media asset contains. Check the media info to find the exact size.
Next, APPEND
Finally, FINALIZE
Response
Hopefully, this article gave you a bit of an insight into the Twitter API. Now that you know how twurl and the API works, go compose some Tweets or build something cool!
