URL Schemes in Twitterrific

What is the URL scheme for Twitterrific 5?

URL schemes can be used by other applications to communicate with Twitterrific. The protocol for the URL is the application's name and version:

twitterrific5://

NOTE: twitterrific:// is provided for backward compatibility, but not all of the functions listed below will be available in older versions.

Choosing the Account

When communicating with the app, you can optionally specify an account using the URL host. For example, to use the CHOCKLOCK account you'd specify:

  • twitterrific5://account/CHOCKLOCK/

You can get the current account by specifying "current" or a blank string for the host. For example:

  • twitterrific5://current/
  • twitterrific5:///

In Twitterrific on iOS the current account is the last one used. On macOS, the frontmost timeline is considered the current account; if there is no timeline one will be opened using the primary account.

Opening the App

If you just want to open the application, you can use:

  • twitterrific5://
  • twitterrific5://<account>/

The second example will also open the specified account.

Selecting a Timeline

You can select one of the timelines using the following URL resources:

  • twitterrific5://<account>/tweets
  • twitterrific5://<account>/mentions
  • twitterrific5://<account>/messages
  • twitterrific5://<account>/favorites

Opening Searches and Lists

When opening a search or list timeline, you'll also need to specify a query or name:

  • twitterrific5://<account>/search?q=query%20with%20percent%20encoding
  • twitterrific5://<account>/list?name=name%20with%20percent%20encoding

All query parameters should be percent encoded per RFC 2986.

An invalid or blank list name will present the list selection interface.

Viewing Tweets and Profiles

Tweets and user profiles can be opened using the following syntax:

  • twitterrific5://<account>/tweet?id=1234
  • twitterrific5://<account>/profile?screen_name=Iconfactory

Posting a Tweet

To open the compose view with a pre-populated message use this URL:

  • twitterrific5://<account>/post?message=message%20with%20percent%20encoding

You can also supply a tweet ID to generate a reply:

  • twitterrific5://<account>/post?message=message&reply_to_id=1234

Opening Message Threads

To open a message thread with a user and send them a message, you'll need to supply their user ID as a parameter:

  • twitterrific5://<account>/send?recipient_id=643443

To get a user ID, you can use Twitterrific's user profile. It shows the user ID formatted as #643,443 – remove the hash and commas and use the numbers only.

Creating Muffle Rules

You can add a muffle rule to the selected account using any percent-encoded text:

  • twitterrific5://account/gnitset/muffle?add=rule%20with%20percent%20encoding
  • twitterrific5://account/gnitset/muffle?add=%23GameOfThrones
  • twitterrific5://account/gnitset/muffle?add=%40HottPockets69

The last two examples show how this feature can muffle hash tags (%23 is '#') or user accounts (%40 is '@').

Sample Code

Now that you've seen all the available functions and parameters, you may need some guidance on how to apply them in your preferred coding environment. The sample code below covers the most common uses.

To post a tweet from Twitterrific 5 on iOS, you'd use the following Swift code:

let scheme = "twitterrific5:"
let account = "account/CHOCKLOCK"
let function = "post"
let parameters = "message=Poopin' 💩"
if let query = parameters.addingPercentEncoding(withAllowedCharacters: CharacterSet.urlQueryAllowed) {
    let urlString = scheme + "//" + account + "/" + function + "?" + query
    if let url = URL(string: urlString) {
        UIApplication.shared.open(url)
    }
}

On macOS, you'd use NSWorkspace.shared.open(url) instead.

Note the use of the String method addingPercentEncoding(withAllowedCharacters:) to ensure that the URL contains valid characters for Unicode codepoints (including Emoji characters.)

You may also want to use some of the scripting capabilities available on macOS. The open command in the Terminal can be used to send URLs to Twitterrific:

$ open twitterrific5:///

This command can also be used in a shell script. If you're using Apple Script, the same shell command is helpful with a little extra syntax:

do shell script "open twitterrific5:///"

We also provide a sample project called Twirl that shows you how to construct the URLs on native apps for iOS and macOS. The code is written in Objective-C and can easily be adapted for your own needs: Download Twirl