Documentation

Connections

What are connections?

Connections allow you to power entire integrations between your service and another with one single connection. A user connects once using the connect button, and you can power multiple triggers and actions.

Connections vs Applets

Applets are 1:1. There's one trigger that happens on your service that maps to certain actions on another service. Also, Applets need to be configured on IFTTT.

Connections, on the other hand, are there to achieve multiple functions with a single integration. Connections allow you to set up triggers and actions for your users via the Connect API without the user having to enable anything on IFTTT. Just connect, authenticate, and you're ready to go.

Creating connections

Connection creation tool

The connection creation tool is designed for you to be able to build powerful integrations with any service on IFTTT. Connections created on the platform should be used in tandem with the Connect API, the iOS SDK, and the Android SDK.

How to use the tool

  1. Start by selecting the service you are looking to connect with
  2. Enter a title for the connection (e.g. "Control your Hue lights when you stream on Twitch")
  3. Once the connection is created, edit the connection to add the trigger and/or action you're going to use, set their configuration, and click "Update"**
  4. You'll now have access to Connect API endpoints for the selected trigger and/or action
  5. Leverage the iOS and Android SDKs to programmatically subscribe to triggers and run actions for your users

Tips on configuration

Similar to Applet configuration, connection trigger and action fields can either be set by you as the developer or shown to the user to set themselves. How a connection is configured is dependent on the experience you're looking to create. See below for an example of how to use different configuration settings for different experiences.

Example: Control the color of your Hue lightbulbs

Service: Philips Hue Action: Change color

Use cases:

Change a user's Hue lights to blue An experience you're looking to create that only sets a user's Hue lights to blue.

Field name Visibility Value
Which lights? Customizable by the user Set by the user
Color value or name Set by you blue

Change a user's Hue lights to their favorite color An experience you're looking to create that sets a user's Hue lights to their favorite single color.

Field name Visibility Value
Which lights? Customizable by the user Set by the user
Color value or name Customizable by the user blue (default)

Change a user's Hue lights dynamically from your mobile app An experience you're powering where a user can change the color of their Hue lights directly from your mobile app.

Field name Visibility Value
Which lights? Customizable by the user Set by the user
Color value or name Set by you blue (default)

To change the color of the lights dynamically, be sure to include the following in the body of your action run request. This will overide the default value (blue).

{
  "fields": {
    "color": "purple",
  }
}

Testing and publishing your connections

  • To see the Connect API logs for a given connection, click the "API logs" tab and reference set of status codes.

  • Connections can be tested fully with the iOS and Android SDKs.

  • Publishing connections is only available for approved paid organizations. To learn more, contact sales.

Getting started with connections

Hello World!

This is the first part in a series that guides the reader through the process of creating and using IFTTT Connect. It’s intended for developers who want to learn how to use IFTTT Connect and Connect API. This first part will guide you through the process of creating and using a very simple connection, a Hello World for IFTTT Connect if you will. More complex topics will be covered in later parts.

Prerequisites

This guide assumes that you already have:

  • Your service on platform.ifttt.com that supports OAuth2 authentication.
  • An account on ifttt.com that is connected to your service and to Google Drive.

Use case

We’ll use an image processing service as a running example. Let’s call it Image Processor. A connection will allow the service to get access to users’ Google Drive to do the following:

  1. Watch a Google Drive folder for a new photo
  2. Download a new photo when it’s added to the folder
  3. Make a thumbnail for the photo
  4. Upload the thumbnail back to Google Drive

In this part we’ll cover the uploading step (4) as this is the most simple one but at the same time allows you to get familiar with IFTTT Connect and Connect API.

Create connection

A connection connects your service to one of many others available on IFTTT. Once a user enables your connection you can utilize it to perform various tasks available through the connected service on the user's behalf. In our example a connection will connect Image Processor to Google Drive. This will allow you to download and upload files from/to user’s Google Drive.

To create a connection:

  1. Go to your service connections
  2. Click New Connection
  3. Choose Google Drive as a service to connect to
  4. Name it Thumbnail Creator and click Save

Create a new connection

This will create a private connection that is visible only to the members of your organization on IFTTT.

Private connection

Preconfigure connection

In this state the connection cannot enable any useful functionality. We need to preconfigure it first:

  1. Click Edit
  2. Click Add Action under Google Drive
  3. Select Upload file from URL for an action
  4. For File URL field Set Visibility to Set by you and Value to TODO (this is just a placeholder, we’ll override this value later)
  5. Do the same for File name field
  6. For Drive folder path field set Visibility to Customizable by the user and leave the Default value blank
  7. Scroll down to Value propositions and use Thumbnail it! as a Value Prop 1
  8. Click Update

Edit connection

This preconfigures the connection with one action available through Google Drive and sets some default parameters for that action.

Enable connection

To test this connection you’ll need to enable it for your account on IFTTT. Follow the Enable on IFTTT link to the right of the connection card. This link will take you to this connection’s page on ifttt.com. This is what this connection will look like to a normal user on ifttt.com after you publish it. Once there:

  1. Click Connect
  2. Set Drive folder path to Thumbnails
  3. Click Save

Enable connection

This action enables and configures this connection for the current user. Now you can use it and upload a file to the user’s Google Drive. Make sure the Thumbnails folder exists in your Google Drive. IFTTT will not create one if it’s missing.

Run action

To upload a file to the user’s Google Drive run the following command line of your computer

curl -i -X "POST" "https://connect.ifttt.com/v2/connections/{connection_id}/actions/google_drive.upload_file_from_url_google_drive/run?user_id={user_id}" \
    -H 'IFTTT-Service-Key: {service_key}' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{"fields": {"url": "https://upload.wikimedia.org/wikipedia/commons/2/21/Hello_World_Brian_Kernighan_1978.jpg", "filename": "Hello World.jpg"}}'

Where:

  • connection_id - the id of your connection (see https://platform.ifttt.com/mkt/connections/private)
  • user_id - the id of the user in your service (see https://platform.ifttt.com/docs/api_reference#user-information)
  • service_key - the secret key assigned to your service (see https://platform.ifttt.com/mkt/api)

This will use the connection we’ve just enabled and upload a file to the Thumbnails folder in the user's Google Drive.

That's it for the first part. In the second part we'll learn how to listen to a new file event.

Thumbnail Creator

In the first part we've learned how to upload a file to a user’s Google Drive. In this part, we will build a backend that will power the rest of the functionality for our connection:

  1. Receive a New Photo in Google Drive Folder notification
  2. Download the new photo
  3. Make a thumbnail for the photo
  4. Upload the thumbnail to Google Drive

Tools

You will need the following tools to complete this guide:

Normally a service is reachable from the Internet. However, we are going to run the service in this guide locally and ngrok will make it easy to call our service from the Internet.

Add trigger to connection

First we need to add a trigger to our connection:

  1. Go to Connections and click the Thumbnail Creator connection we've created earlier
  2. Click Edit
  3. Click Add Trigger under Google Drive
  4. Select New photo in your folder for a trigger
  5. For Drive folder path field set Visibility to Customizable by the user and leave the Default value blank
  6. Click Update
  7. Click OK in a pop-up warning you about destroying enabled connections. This will destroy enabled connections: the ones that are visible to users at ifttt.com. It will not destroy the connection we are working on on platform.ifttt.com.

Add trigger to connection

Enable connection with trigger

Since the action of adding a trigger disabled the connection for all users we need to enable it again:

  1. Create Photos and Thumbnails folders in the root of your Google Drive
  2. Go to Connections and follow the Enable on IFTTT link to the right of the connection card
  3. Click Connect
  4. Use Photos for New photo in your folder trigger
  5. Use Thumbnails for Upload file from URL trigger
  6. Click Save

Enable connection with trigger

Create Flask app

Now that the connection is configured and enabled IFTTT will send you a webhook for every new photo added to the Photos folder in user’s Google Drive. To receive the webhooks and do the photo processing we will write a simple service using Python and Flask.

Create a new Python project:

mkdir thumbnail-creator
cd thumbnail-creator
pipenv install --python 3.7 flask==1.1.1 requests==2.22.0 pillow==6.1.0 

This will create a Pipfile that looks like this:

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
flask = "==1.1.1"
requests = "==2.22.0"
pillow = "==6.1.0"

[requires]
python_version = "3.7"

Create app.py file in your text editor with a dummy webhook request handler:

from flask import Flask

app = Flask(__name__)

@app.route("/ifttt/v1/webhooks/trigger_subscription/fired", methods=["POST"])
def handle_trigger_subscription_fired():
    return ""

This handler will be executed every time IFTTT sends you a webhook request.

Start the app:

export FLASK_ENV=development
pipenv run flask run

This will run your minimal flask app in a development mode allowing you to make changes to the code without restarting the app. The command output should look like this:

 * Environment: development
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 330-315-293

Leave the app running until the end of this guide.

Let’s test it by running the following command in a separate terminal window:

curl -i -X POST "localhost:5000/ifttt/v1/webhooks/trigger_subscription/fired"

You should see this:

HTTP/1.0 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 0
Server: Werkzeug/0.16.0 Python/3.7.4
Date: Tue, 01 Oct 2019 17:53:15 GMT

Parse webhook

Now we are ready to parse incoming webhook requests. Add the following to app.py:

from flask import request

...

request_json = request.get_json()

user_id = request_json["data"]["user_id"]
connection_id = request_json["data"]["connection_id"]
photo_filename = request_json["event_data"]["ingredients"]["Filename"]
photo_url = request_json["event_data"]["ingredients"]["PhotoUrl"]

You can test this code by sending a webhook request to yourself:

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{ "data": { "user_id": "test_user", "connection_id": "mdX8HMW9", "trigger_id": "google_drive.any_new_photo" }, "event_data": { "ingredients": { "Filename": "foo.jpg", "PhotoUrl": "https://upload.wikimedia.org/wikipedia/commons/2/21/Hello_World_Brian_Kernighan_1978.jpg" } } }' \
    "localhost:5000/ifttt/v1/webhooks/trigger_subscription/fired"

You should get back an HTTP 200 response.

Download photo

Next step is to download the photo using the url from the webhook event:

photo_bytes = requests.get(photo_url).content

Add this to your handler and run the same curl command again. You should receive a successful response.

Make thumbnail

We will use Pillow to make a thumbnail:

from PIL import Image
from io import BytesIO
import uuid

...

image = Image.open(BytesIO(photo_bytes))
image.thumbnail((128, 128))
thumbnail_filename = f"{uuid.uuid4()}.png"
image.save(f"{app.root_path}/static/thumbnails/{thumbnail_filename}")

This will make a thumbnail of the photo and save it in the ./static/thumbnails directory. The static directory has a special purpose in Flask. Everything that you put in there will be served automatically without the need for a handler. Let’s create that directory now:

mkdir -p static/thumbnails

Run another test request. After it succeeds you should see a new png file in ./static/thumbnails. Open the file up and verify it’s a thumbnail. You can check that it’s downloadable by using this URL in your browser: http://localhost:5000/static/thumbnails/{filename} (replace {filename} with the name of the created thumbnail file).

Receive real webhook

Before we go to the last step let’s ensure our code works with a real webhook event, not just a test one. Since your computer is unlikely to be reachable from the Internet we will use ngrok to work around that.

  1. Run ngrok http 5000. Look for a line that looks like this Forwarding https://123de333.ngrok.io -> http://localhost:5000. This is the URL that ngrok generated for you. In this case the URL is https://123de333.ngrok.io. As long as ngrok is running anyone from the Internet can access your computer using this URL. Note that a new URL is generated when you restart ngrok. Leave it running until the end of this guide.
  2. Go to your service API page. Set the URL to the one ngrok generated. Save the changes.
  3. Go to your Google Drive and add a photo to the Photos folder you created earlier.
  4. Check that a new thumbnail is created in ./static/thumbnails.

Thumbnail it!

The last step is to run a Google Drive action that requests a file to be downloaded from your service to user’s Google Drive. Add the following code to your handler:

from pathlib import Path

...

action_run_url = f"https://connect.ifttt.com/v2/connections/{connection_id}/actions/google_drive.upload_file_from_url_google_drive/run?user_id={user_id}"
headers = {
    "Content-Type": "application/json",
    f"IFTTT-Service-Key": "<your-service-key>"
}
# Here we are overriding the field values specified during connection creation with the actual url and filename.
action_run_body = {
    "fields": {
        "url": f"<ngrok-url>/static/thumbnails/{thumbnail_filename}",
        "filename": str(Path(photo_filename).with_suffix(".png"))
    }
}

r = requests.post(action_run_url, headers=headers, json=action_run_body)
r.raise_for_status()

Replace <your-service-key> with your secret service key.

Replace <ngrok-url> with the url ngrok generated for you.

Go to your Google Drive and add another photo to the Photos folder.

Check that a new thumbnail is added to the Thumbnails folder (this can take a few seconds).

This is it! You have just built a connection and backend for it that does something useful! Don’t forget to stop ngrok and the app.

Source code

Full source code can be found here https://github.com/IFTTT/getting-started-with-connect