Skip to main content

​
Introduction

Actions are automations. They are the things that happen when an annotation is triggered. For example, when a goal is scored, you may want to automatically create a clip of that goal (either as an mp4 asset or a playable video). And maybe you want to automatically share that clip to social media? Actions are the way to achieve this. Motto supports a wide range of actions, all with the purpose of simplifying your workflow and automating repetitive tasks. Or, put differently, reducing the overhead needed to run a live sports OTT platform. Here is a non-exhaustive list of automated actions:
  • Create a clip of a goal in your live-stream;
  • Create a highlight reel of all goals and chances in a match;
  • Share to social media the clip of a scored goal;
  • Send a notification to all users that have favorited a team when a goal is scored;
  • Write a message in a chat room when kickoff starts;
  • Send a webhook callback to a third-party system when the match is over.
These actions (and more) can be configured to suit your particular needs. The next section will guide you through the process of setting this up.

​
Get Started

To benefit from Motto’s actions system, you must first think through your particular use-cases. What do you want to happen when a goal is scored? Or when a match is over? The following section helps you understand what is possible.
To get started with actions, you must first ensure that you have followed the steps in the annotations guide. This is because actions are triggered by annotations.

​
Action Types

In order to understand what is possible through Motto, you can browse the available action types. To do so, follow these steps:
Call the List Action Types endpoint.
curl --request GET \
  --url https://api.mottostreaming.com/annotations/action_types/v1 \
  --header 'Authorization: Bearer <your_token>'
This will return a list of available action types that you can choose to configure.

​
Action Configuration

Once you have determined which action types you would like to trigger when an annotation is created, you must configure your annotation type with the appropriate action configuration. To do so, follow these steps:
First, call the Get Action Type endpoint to understand exactly which fields you must provide in the action configuration.
curl --request GET \
  --url https://api.mottostreaming.com/annotations/action_types/v1/create_clip \
  --header 'Authorization: Bearer <your_token>'
Then, call the Set Action Configuration endpoint with the correct configuration. For example, if you want your “Goal” annotations to trigger a highlight clip creation, you would call the endpoint like this:
curl --request POST \
  --url https://api.mottostreaming.com/annotations/types/v1/<annotation_type_id>/action_configuration \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "configuration": {
       "create_clip": {
           "motto_jwt": "<your_token>",
           "name": "Goal",
           "relative_end_offset": 10000,
           "relative_start_offset": -10000
       }
  }
}'
A lot is happening here, so let’s break it down.
  1. The annotation_type_id should be the annotation type for which you want to configure the action. In this example, it is assumed you have already configured a “Goal” annotation type as described in this guide.
  2. There is a create_clip key in the configuration object. This is the ID of the action type that you want to trigger.
  3. There is a motto_jwt key in the configuration object. This is the Motto JWT token that is used to by our servers to authenticate the action calls, since actions are asynchronous in nature and actually may call Motto’s Studio API (or even external APIs). You can provide your own JWT token, but it is recommended to provide credentials to an account with only the necessary permissions (in this example the permission needed to create a clip).
    It is not recommended to provide tokens to the action configuration in plaintext. Instead, we recommend using action secrets.
  4. There are more input fields, like name and relative_start_offset. These are specific to the action type that you are configuring. In this example, the name field is used as part of the name the clip will be given, and the relative_start_offset and relative_end_offset fields are the start and end times of the clip relative to the annotation time.
It is important to understand that each action has its own set of input fields that it requires, so the example above is only here for reference.
Once you submit this configuration, you are done! You can verify this now by creating an annotation of the type you just configured, and see if the action triggered. Keep in mind that, depending on the kind of action(s) you have created, it may take some time for the action to complete.

​
Action Secrets (advanced)

As has become clear in the action configuration section, some actions require authentication credentials. While you may provide these in plaintext on the action configuration, this may expose those credentials to anyone who has access to view your action configurations, which may lead to accidental leaking of your credentials to unintended parties. The suggested alternative to providing credentials in plaintext is to use Motto’s action secrets system. To do so, follow these steps:
Call the Create Action Secret endpoint to store a secret value. For example, if you wanted to store a Motto API token, you could call the endpoint as follows:
curl --request POST \
  --url https://api.mottostreaming.com/annotations/action_secrets/v1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "motto_jwt",
  "project_id": "<your_project_id>",
  "description": "The JWT of a Motto account with the Editor role",
  "value": "<some_token>"
}'
Once your action secret is stored, you can reference it in your action configuration by using the $secret.<secret_id> syntax. For example, if you wanted to use the motto_jwt secret in your action configuration, you would reference it like this:
{
    "configuration": {
        "create_clip": {
            "motto_jwt": "$secret.motto_jwt",
            "name": "Goal",
            "relative_end_offset": 10000,
            "relative_start_offset": -10000
        }
    }
}

​
Action Chaining (advanced)

The Motto action system is designed for both simple and complex workflow automations. Action chaining is a concept that lets you execute multiple actions in sequence, where the result of one action can be used as input for the next action. For example, you may want one action to create a clip, and then take that clip’s asset_id (which is the “output field” of that particular action type) as input for an action that shares it to Instagram (which may require an asset_id as its input field). Fortunately, chaining actions is not difficult to configure. In fact, it is very similar to configuring a single action, but with the added step of providing the output of one action as input for the next action. For the example above, the configuration may look like this: 
{
    "configuration": {
        "create_clip": {
            "motto_jwt": "$secret.motto_jwt",
            "name": "Goal",
            "relative_end_offset": 10000,
            "relative_start_offset": -10000
        },
        "share_to_instagram": {
            "instagram_api_token": "$secret.instagram_token",
            "social_media_post": "Have a look at this amazing goal!",
            "video_asset_id": "$create_clip.asset_id"
        }
    }
}
The $create_clip.asset_id is a reference to the output field of the create_clip action. This is how you chain actions together.

​
Next Steps

If you are interested in using annotations to enrich your OTT platform experience, you may want to learn more about frontend plugins.