How to ask Siri about your bunq account balance, using the bunq API and Siri Shortcuts
bunq offers a world-class mobile banking solution, but wouldn’t it be great if we could make the experience even better? What about the ability to ask Siri about our current balance! That’s what we’re going to achieve in this tutorial. We will harness the power of the bunq C# SDK in combination with Siri Shortcuts to make the magic happen.
What do we need, for this magic to work? ✨
The shortcuts app is a powerful tool with which you can automate things in iOS, but it isn’t that powerful! You’ll have a hard time trying to make an API wrapper, inside of shortcuts, for an advanced API like the one from bunq. That’s why we will create a small proxy API in .Net Core that runs on our server or personal machine. The proxy API does the heavy-lifting, while we create an easy to use and easy to understand Siri Shortcut.
You’ll need the following items:
- .NET Core 2.2
- Visual Studio / Visual Studio Code or another IDE with support for C#
- An iPhone with the Shortcuts app installed
- A bit of programming knowledge and understanding of HTTP
I’ll be using Visual Studio (for Mac) in this tutorial, but the experience with another IDE should be similar. All the source code will be available as a download on GitHub.
Creating the .Net Core C# proxy API 🖥
We’ll need to create our own little API that the shortcut will be able to interact with. Creating a shortcut that directly talks to the bunq API will be a bit of a headache. 🤯
Setup your API project 🔨
First off, let’s open the IDE and start a new project. We’ll pick the .NET Core API project template as it gives us a nice starting point for this project. Make sure you’ll pick the latest target framework (.NET Core 2.2) and give your project a recognisable name.
When you’ve created the project you’ll see it already has a few files. Mainly the
Startup.cs and the
ValuesController.cs in the Controllers directory. We’ll use
Startup.cs in a later stage to add a simple form of authentication to our API and to init the bunq SDK. But first, we’ll take a look at the
ValuesController.cs in order to get a better understanding of the inner workings of a .NET Core API.
This ValuesController is what’s visible for the outside world when we run our API. The
[Route(“api/[controller]”)] part tells where we can access this controller once it’s live. That is, at
<yourhost>/api/values the path is derived from the controller’s name.
ValuesController defines a few endpoints which we could call on our controller. The specific HTTP method is indicated by the HTTP verb above each endpoint.
Initialising the bunq SDK 🌈
Before we can replace the
ValuesController with our own we need to add the bunq SDK to our project. Go to Project > Add NuGet Packages.. and search for bunq. Select
Bunq.Sdk from the list and press Add Package. Once added, you should be able to see the bunq SDK in your solution explorer under your project dependencies.
In order to be able to use the bunq API, we’ll also need to create an
apiContext. For this we’ll edit the
Startup method in
Startup.cs and add the following lines at the end of the method:
This piece of code tries to restore the
apiContext from the local storage and if it fails (because there isn’t a local
apiContext yet) it will create a new
apiContext for us. The creation of the context requires three parameters:
- The environment type (Sandbox or production)
- A bunq API key
- A device description
In the code sample above we’ve used two private constant strings for the API key and the device description. In order for this to work, you’ll need the following two lines to your
Startup class definition.
Note: Placing your API key inside your source code isn’t best practice, but it will do for now.
We now should have a working connection with the bunq API once we run our code!
Creating the MonetaryAccountController 💰
Now that we have initialised the bunq SDK and registered our API as a device we can query the bunq API. So let’s create a new file (or duplicate the
ValuesController.cs) in the
Controllers directory that will handle our endpoints for retrieving account balances:
Here’s the fully finished
MonetaryAccountController.cs, we’ll walk through it step by step later in the tutorial.
This file has the same structure as the old
ValuesController.cs file, it contains two methods that will be exposed as API endpoints. The first method returns all monetary account and the second one returns only a specific monetary account, by providing its ID.
Before I go into more detail about the methods I’d like to redirect your attention to a small class that is defined at the top of this file. This
Account class will be used as a simplified object that our API will return. This way it will be easier to process the data in the shortcuts app.
Both methods are pretty the same except the second method only returns the details of a specific method. So let me walk through the steps of the first method:
- We load the
bunqContextso we can query the bunq API.
- We ask the bunq API the list of accounts.
- We create a list that will store our simplified
- We iterate through the values of the
MonetaryAccountswe received from the bunq API.
- We create a simplified
Accountobject from each
MonetaryAccountand add it to our list
- We return the list of simplified
Accountobjects in JSON format
That’s it! That’s all that we need, in order to create a simple API that returns simplified information about our monetary accounts. You can try it out by pressing the run button and use
curl or postman to call your API.
Adding some security to our API 🔐
In theory, we now have a fully working API. However, everybody with the correct network path will be able to query your API once it is live. So let’s build is some security measurements.
Since our API only returns some values and the user isn’t able to add or alter data authorization by a simple API Key is enough.
First, install the
AspNet.Security.ApiKey.Providers NuGet package. After that, add the following code to the
ConfigureServices method in
Startup.cs and add
app.UseMvc(); in the
We now have everything in place to secure our API endpoints. Just change the
Super-secret-key to a strong secret and set your own name. The only thing left for us to do is adding the
[Authorize] action filter to our methods in the
And ta-da! We’ve got a fully functioning API with authorization. You’ll see that you can’t just call our endpoints without authorization. In order to call our endpoints again, we need to add an
authorization HTTP header to our call, with the value:
But obviously, you’ve already changed it to something more secure 😉
In order to launch your API, you can run
dotnet run in the terminal from the project’s directory.
Accessing the API from the outside 🏡
Currently, our API only runs on our own machine and isn’t available from the outside. Something we will need when we want to connect with Siri from our phone. Unfortunately, not everybody has access to a dedicated server or a static IP-address. If you have those great, run it on a server!
But for those who don’t have access to a dedicated server, we can utilise a little tool called Ngrok. Ngrok allows us to set up a secure tunnel so we can reach our API from the outside.
The steps are pretty simple:
- Download and install ngrok
- Register for a free account
ngrok authtoken <token>to login to the ngrok tool
ngrok http https://localhost:5001(Our API runs on port 5001)
Note: You’ll get the auth token from the ngrok dashboard
You’ll get a ngrok.io URL at which the API is available, easy as that! The tunnel is fully secured with HTTP 🔐. We can now use the ngrok URL to connect with our Siri shortcut.
Note: If you don’t login to an ngrok account the URL will only be valid for 8 hours. The URL changes every time you restart the tool.
Creating the Siri Shortcut 📱
We have our API running and available from the outside. Finally, the fun part can begin! Let’s grab our iPhone and fire up the shortcuts app. The shortcut we’re going to make only contains 4 building blocks. Let’s walk through them:
URLblock with the URL to our API endpoint to fetch the details of a specific account. (The ID can be obtained by calling the account list endpoint)
Get Contents of URLblock, where we add the Authorization header so we have access to our data.
- We turn the data from the API into a dictionary with a
Get Dictionary from Inputblock.
Show Resultblock where we use the dictionary variable to present the data in the Siri response. (
Get Value from Key)
That’s all we need for the shortcut! You can now add your shortcut to Siri by recording a command! Settings > Add to Siri 🎙
That’s it, you’re done. You’ve successfully asked Siri about your bunq account balance! Keep on tinkering! Don’t forget, the source code is available on Github.
Final notes 📝
Thanks for taking the time to read this tutorial. I hope you found it interesting and give it a try. If you liked my entry to the API tutorial contest, please give it a clap and share it. 👏
And of course, check out the other entries! 🏆