Skip to content
Yetto Docs

Creating switches

Switches are the foundation of information flow and activity in Yetto. You can create switches in your inboxes to add custom automations, such as applying labels and sending data to your webhooks.

The anatomy of a switch

Yetto's switches are written in JSON have a couple of standard keys. Let's look at one and break it down as an example.

{
    "events": {
        "message.created": {
            "actions": [
                {
                    "add": [
                        "bug.urgent"
                    ],
                    "uses": "apply_labels"
                }
            ],
            "conditions": {
                "if": "{% data.yetto.message.visibility == 'internal' and data.yetto.message.text_content contains \"@label add urgent\" %}"
            }
        }
    },
    "version": "2023-03-06"
}

Events

The events object is required. This tells Yetto what events to act on and what to do when the event occurs. Each switch can contain multiple events to watch for. In this example, we're going to act on the message.created event.

A list of available events that Yetto listens for can be found in our switch reference document.

Actions

The actions array is where you'll tell Yetto what you want to do when the specific event triggers the switch. This is a required object and will always include a uses string.

The apply_labels and http_request actions are the first ones available for public use. Each action behaves a little differently and may required other object properties to work. The actions and their requirements are described in the table below.

Apply labels

The apply_labels action adds and removes labels from a conversation. It requires either an add object or a remove object, or both. These must be arrays of strings with the names of the labels you want to add or remove. The remove array can include "*", which will remove all labels from a conversation.

In the example above, we're using the apply_labels action to add the bug.urgent label when an event triggers the switch.

Http request

The http_request action requires a to: url object and a with: method object. The url is the target of the http request and the method is the http method to use when sending the data. As an example:

{
    "version": "2023-03-06",
    "events": {
      "message.created": {
        "actions": [
          {
            "name": "Send to server",
            "uses": "http_request",
            "to": {
              "url": "https://norse.org"
            },
            "with": {
              "method": "GET",
              "headers": [
                {
                    "RECEIVER-HEADER": "expected_value",
                }
              ]
            },
          }
        ]
      }
    }
}

The name property is optional, as is headers. We send Yetto specific headers with the request, but you can send additional headers if you want to use them for your own validation.

Additionally, you can specify what data you want to receive by including a with: body object. If you don't include that, we'll send the relevant payload for the event (the message payload for a message.created event, for example). However, if you include a with: body object, we will send that instead of the default payload. For example:

{
    "version": "2023-03-06",
    "events": {
      "message.created": {
        "actions": [
          {
            "name": "Send to server",
            "uses": "http_request",
            "to": {
              "url": "https://norse.org"
            },
            "with": {
              "method": "GET"
              "body": {
                "some": "thing"
                "message_id": "{{ data.yetto.message.id }}"
                }
            }
          }
        ]
      }
    }
  }

The above switch will send the body defined in the JSON object rather than the message payload that Yetto would normally send for a message.created event.

Conditions

Here we can tailor the switch action to be more specific. Yetto allows if and unless objects as conditions, both of which use Liquid as their templating language. You have access to the full object that triggered the switch event when writing these, namespaced as data.yetto.*. Let's look at our example again.

"conditions": {
    "if": "{% data.yetto.message.visibility == 'internal' and data.yetto.message.text_content contains \"@label add urgent\" %}"
}

Here we use want only internal messages containing specific text. Note that the text content is escaped using \s in Liquid.

All of the available object properties will be enumerated in our reference docs.

Version

This is a required field and should typically be set to the newest switch version. As of writing this, the latest switch version is 2023-03-06. Using a different version could create unexpected behaviors.

Make your own

To create your custom switch:

  1. Go to the "Switches" section of your inbox settings.
  2. Click "Add new switch".
  3. Enter a unique name for your switch in the "Name" field. This should be descriptive enough for you to know what it's doing at a glance. "VIP automations" or "Urgent labels" are good examples.
  4. Write the switch as valid JSON in the text field. You can start by copying and pasting an existing switch and then modifying the events and actions to suit your needs.
  5. Click "Create switch".

Your switch is now installed on your inbox and ready to use.

See some examples

Yetto uses switches under the hood to send data between plugs. Once you have a plug installed on your inbox, you can view the switches it uses to operate. Go to the "Switches" section of your inbox settings and click "View" on any of the switches listed there. That will give you an idea of how we use them internally to automate activity within Yetto.