I’ve been playing around with flavour-of-the-month Twitter-replacement Mastodon of late. Its email-like federated approach (not all controlled by a single company) gels well with our company beliefs around a diverse and open ecosystem for online life. If you’re looking for an instance (Mastodon-parlance for a service provider) we heartily recommend mastodon.me.uk. I’m on there as @amcewen@mastodon.me.uk (new followers, from whichever instance, always welcome :-)

Given the amount of work we do with Twitter, we’ve naturally been looking at how to interact programmatically with the Mastodon network.

One of the first things to do is to be able to send status updates to a particular account. This is reasonably easy to do, but required a fair bit of poking around online and so I figured (and was asked) it was worth collecting it into one place for anyone else to use.

This is all for Ruby, as that’s my experimenting-with-things scripting language of choice.

Mostly this is culled from the mastodon-api gem docs, Testing the API with cURL and API overview.

First off, you’ll need to install the mastodon-api gem.

Create a Client App

You’ll need to change the ‘mastodon.me.uk’ in the following code to point to whichever Mastodon instance you’re using. Similarly the ‘Name of your app’ should be a useful name for the app you’re building (as it’ll show up when you look at the ‘Authorized apps’ section of your Mastodon account preferences.

The final, important, piece to pay attention to is the access scope. This is the ‘read write’ parameter passed into client.create. That governs the permissions that your app will have to access the user’s account. Here we’re asking for permission to read data from the user and to post status messages and upload media; but not asking for permission to (un)follow or (un)block users (we’d need to add ‘follow’ to the parameter for that).

As this is something you’ll generally just do once to get an access token (for simple posting-to-one-account bots at least), I just ran through these steps in irb, a ruby shell.

  require 'mastodon'
  
  client = Mastodon::REST::Client.new(base_url: 'https://mastodon.me.uk')
  app = client.create('Name of your app', 'http://mywebsite.com/callback', 'read write')

Now the app object will contain two important bits of information: the client_id and client_secret.

Authorize the App

Next you need to give your newly created app access to the account to which you want it to post updates.

It’s possible to do this from within ruby, but I found it easier to drop into a terminal and use curl.

Again, you’ll need to replace all the ALL_CAPS sections, and possibly also the scope and server details (if you don’t want (just) read and write permissions or if you’re connecting to a Mastodon instance other than ‘mastodon.me.uk’).

This also includes your password in the clear, so you should be careful with that - a space at the start of the line (in bash at least) will keep that line from getting put into your terminal history).

  curl -X POST -d "client_id=CLIENT_ID_FROM_PREVIOUS_STEP&client_secret=CLIENT_SECRET_FROM_PREVIOUS_STEP&grant_type=password&username=USER_EMAIL_ADDRESS&password=USER_PASSWORD&scope=read write" -Ss https://mastodon.me.uk/oauth/token`

If all goes well, you’ll get a chunk of JSON text back from that. Looking something like this:

  {"access_token":"LONG_STRING_OF_LETTERS_AND_NUMBERS","token_type":"bearer","scope":"read write","created_at":1491919210}`

This is the all-important access token. Now we’re authorized and can post status updates as that user!

Post Updates

Posting an update just requires you to create a client using your new bearer access token, and then calling client.create_status. In this example we’ll use the text “If you can see this, I’ll be happy”, as per my first test.

  require 'mastodon'

  client = Mastodon::REST::Client.new(base_url: 'https://mastodon.me.uk', bearer_token: 'ACCESS_TOKEN_YOU_GOT_FROM_THE_CURL_RESPONSE')
  client.create_status("If you can see this, I'll be happy.")

Hope that’s useful.