Introduction

What are UI Extensions?

UI Extensions are integrations that can be installed into Twist and add additional UI functionality.

We have three types of UI Extensions:

• Composer Extensions - These are extensions triggered from the composer's Quick Actions button.
• Context Menu Extensions - These are extensions triggered from the context menu of a thread/comment/message.
• Settings Extensions - These are extensions that are accessed via the in-app settings from within Twist itself

Extension Lifecycle

UI Extensions work via a turn-based model. The user asks for a UI, and the integration provides it. Once the user interacts with the extension, the client sends another request to the integration. The integration decides how to handle the interaction. It responds either with another UI or a request to execute a specific action on the client-side. This interaction cycle continues until the integration is terminated or reaches an exit condition where there's no more to show the user.

Below, you can see an example flow of our Giphy composer extension from beginning to end. If you'd like to see the complete payloads, you can use the Giphy extension in Twist and inspect the traffic occurring when interacting with the extension.

Adaptive Cards

Your integration returns UIs based on Adaptive Cards which Twist then renders for the user. Part of the response from the extension will be to include a card object (when applicable), the basic schema for which can be found here.

Versioning

Details about the versioning (Data Exchange Format/Doist Card).

Handling User Requests

Client and User Information

Each request to your extension will contain information about the client that sent the data (eg, mobile/desktop), as well as a small amount of information about the user making the request.

This is called the Data Exchange Format, and details what you can expect from the client, and what the client expects to be sent back.

• Context (context) - Information about the environment and the user that's using the integration, including which thread / channel / message it contributing, etc.
• Action (action) - We need to be able to identify the type of action the user has executed on the client so that the backend can act accordingly and send it sufficient data to act on it
• Extension Type (extensionType) - This will identify which type of extension it is, currently either composer or context-menu.
• Maximum Doist Card Version (maximumDoistCardVersion) - This will identify the maximum Doist Card version that the requesting host client can support. This can allow your extension to send back differing UI elements based on what is supported by the client.

Extension Type

We will send an extension type depending on where the user has invoked the integration.

Composer

The user can access these integrations from the composer window of the host client.

Context Menu

The user can access these integrations from the context menu of a conversation message, a thread, or a thread comment. These extensions will provide the following additional data which will reside in action.params (see actions).

Properties

Settings

If the extension type is settings this means it has been triggered from within Twist's in-app settings. Here you can have any settings the user can change for your extension.

Maximum Doist Card Version

This is the maximum version of Doist Card that the requesting host can support. The host will send this so that the extensions can return cards that the host can display. An example of why this is needed is if a user hasn't been able to update to the latest version of Twist that supports the latest version of Doist Card, the extension can send back a card that will be supported by that version of host application. Should the extension not support a lower version of Doist Card, then the extension can set the minimum cardist version when they create their integration at https://twist.com/app_console.

Context

We send context information with every request to the integration backend. It contains:

• Theme (theme)
• User (user)
• Twist (twist)
• Platform (platform)

Theme

This will be the theme of the calling application, either light or dark.

User

It contains the current user that invoked the integration.

A subset of Twist's user fields:

• short_name
• timezone
• id
• lang
• first_name
• name
• email

Platform

This will be the platform that the client is making the request from and can be used by the integrations to tailor their UI to the platform requesting. This is an optional field and can be either desktop or mobile.

Twist

Twist specific context items. These are small amounts of information about where in Twist the request was made.

Workspace

It contains the workspace where the user is currently browsing content.

A subset of Twist's workspace fields:

• id
• name

Channel

It contains the current channel in which the user is browsing content. Is not present in the data if the user is not currently browsing a channel

A subset of Twist's channel fields:

• id
• name
• description

Thread

It contains the current thread in which the user is browsing content. Is not present in the data if the user is not currently browsing a thread

A subset of Twist's thread fields:

• id
• title

Conversation

It contains the current conversation in which the user is browsing content. Is not present in the data if the user is not currently browsing a conversation

A subset of Twist's conversation fields:

• id
• title

Action

We use the action to signal to the server what kind of interaction does the user expects. We support the following list of interactions:

• Initial (initial)
• Submit (submit)

Initial

Initial Action examples

{
  "actionType": "initial"
}

{
  "actionType": "initial",
  "params": {
    "source": "message",
    "url": "https://twist.com/a/1234/msg/5678/m/46880670",
    "id": 46880670,
    "content": "Can you do this very specific thing",
    "postedDate": "2021-04-08T13:39:00Z"
  }
}

The initial action type tells the server that the user has just opened the integration and expects to see the first screen in the workflow.

If there is additional data being sent as part of the initial request (for example, with the context menu extensions), this will live in the params field

Submit

Submit Action Example

{
  "actionType": "submit",
  "actionId": "Action.Search",
  "inputs": {
    "myTextInput": "Example text fields response",
    "myNumberInput": "456"
  },
  "data": {
    "submitButtonName": "mainSubmitButton",
    "securityHash": "dajsiodjioasd45457"
  }
}

Whenever a user presses a button, for example, Twist will send all the fields the user has filled out / checked, or otherwise interacted with, back to the server, using the Action.Submit action.

Whenever a user executes an action via the Action.Submit action on the form; the following will be sent to your integration:

• All Input.* fields in the form of {"inputId": "inputValue}
• All data properties of the Submit element

An actionId should be supplied with the request as the submit action on its own may not be very clear as to the action's intended consequence.

Security

In order for your UI Extension to remain secure, when a request is made we will include an additional header in the request. This will allow your extension to confirm that the request was made from Twist.

The header x-twist-hmac-sha256 will be included. It is a SHA256 HMAC generated using the integration's verification token as the encryption key and the whole request payload as the message to be encrypted. The resulting HMAC would be encoded in a base64 string.

Full Client Request Example

The full request that the client makes to the server can look as follows.

Composer Extension

{
  "context": {
    "platform": "mobile",
    "theme": "dark",
    "user": {
      "short_name": "Anne F",
      "timezone": "Europe/Budapest",
      "id": 4564,
      "lang": "English",
      "first_name": "Anne",
      "name": "Anne Farkas",
      "email": "anne.farkas@outlook.com"
    },
    "twist": {
      "workspace": {
        "id": 4,
        "name": "My Cool Workspace."
      },
      "channel": {
        "id": 44,
        "name": "My Cool Channel",
        "description": "This is where all the cool threads go"
      },
      "thread": {
        "id": 44,
        "title": "Cool People Problems."
      },
      "conversation": {
        "id": 44,
        "title": "BFFs."
      }
    }
  },
  "action": {
    "actionType": "submit",
    "inputs": {
      "myTextInput": "Example text fields response",
      "myNumberInput": "456"
    },
    "data": {
      "submitButtonName": "mainSubmitButton",
      "securityHash": "dajsiodjioasd45457"
    }
  },
  "extensionType": "composer",
  "maximumDoistCardVersion": 0.5
}

Context Menu Extension

{
  "context": {
    "platform": "desktop",
    "theme": "dark",
    "user": {
      "short_name": "Anne F",
      "timezone": "Europe/Budapest",
      "id": 4564,
      "lang": "English",
      "first_name": "Anne",
      "name": "Anne Farkas",
      "email": "anne.farkas@outlook.com"
    },
    "twist": {
      "workspace": {
        "id": 4,
        "name": "My Cool Workspace."
      },
      "channel": {
        "id": 44,
        "name": "My Cool Channel",
        "description": "This is where all the cool threads go"
      },
      "thread": {
        "id": 44,
        "title": "Cool People Problems."
      },
      "conversation": {
        "id": 44,
        "title": "BFFs."
      }
    }
  },
  "action": {
    "actionType": "initial",
    "inputs": {},
    "data": {},
    "params": {
      "source": "message",
      "url": "https://twist.com/a/1234/msg/5678/m/46880670",
      "id": 46880670,
      "content": "Can you do this very **specific** thing",
      "contentPlain": "Can you do this very specific thing",
      "postedDate": "2021-04-08T13:39:00Z"
    }
  },
  "extensionType": "context-menu",
  "maximumDoistCardVersion": 0.5
}

Returning UIs and Action Bridges

When the server responds to the client requests, it needs to send several vital pieces of information:

• UI (card) - The card is what contains the UI JSON that Twist will render for the user.
• Client-side Actions (bridges) - UI Extensions also need to have a way to instruct the clients to do specific actions on their behalf, such as inject text into the composer. This field is an array of bridges and bridges will be executed in the order in which they appear in the array.

Note that both properties can present at the same time, but at least one must always be filled out.

UI

In most cases, we will display a UI rendered as a Doist Card, which is essentially an adaptive card with some Doist-specific tweaks. We house the entirety of the card within the card property.

Client-side Actions

Example of multiple bridges

{
  "bridges": [
    {
      "bridgeActionType": "composer.append",
      "text": "My Text to Append"
    },
    {
      "bridgeActionType": "finished"
    }
  ]
}

In some cases, we also need to ask the client to execute one of the actions within the app itself, which is where interactions contribute to the interactivity within Twist itself.

Currently, we support the following bridge action types (bridgeActionType):

• Append Text to Composer (composer.append)
• Extension has finished (finished)
• Display Notification (display.notification)

An integration can send multiple bridges as part of the response and the client will execute each bridge in order. See the example on the right of an integration that wants to add to the composer, then close the extension.

Append Text to Composer

Composer Append Bridge

{
  "bridgeActionType": "composer.append",
  "text": "My Text to Append"
}

When triggered, the client will append a specified text into the Twist text composer. The supported properties are:

• Text (text) text to append at the end of the current message

Extension has finished

Finished Bridge

{
  "bridgeActionType": "finished"
}

When this bridge is sent back, it's a way for the extension to tell the host that they have finished now and any UI can be closed.

Display Notification

Display Notification Bridge

{
  "bridgeActionType": "display.notification",
  "notification": {
    "text": "Your task has been added to your inbox",
    "type": "success",
    "action": "https://todoist.com/showTask?id=123456789",
    "actionText": "Open task"
  }
}

You can display a lightweight notification as an alternative to a full card, which may be too heavy in some scenarios.

Properties

Note: For the notification to display an action, both actionUrl and actionText must be provided.

Full Server Response Example

Server Response Example

{
  "card": {
    "type": "AdaptiveCard",
    "body": [
      {
        "type": "Input.Text",
        "id": "TextInput.Search",
        "value": "hello",
        "placeholder": "Search here...",
        "inlineAction": {
          "type": "Action.Submit",
          "id": "Action.Search",
          "title": "Search GIFs"
        }
      },
      {
        "type": "ImageSet",
        "imageSize": "Large",
        "images": [
          {
            "type": "Image",
            "url": "https://media1.giphy.com/media/XYot661SFS62c/giphy.gif?cid=550add23837d0fdf40feddd3a4df0de03a98b54019e5cffc&rid=giphy.gif",
            "altText": "robin williams hello GIF"
          },
          {
            "type": "Image",
            "url": "https://media1.giphy.com/media/icUEIrjnUuFCWDxFpU/giphy.gif?cid=550add23837d0fdf40feddd3a4df0de03a98b54019e5cffc&rid=giphy.gif",
            "altText": "Napoleon Dynamite Hello GIF by 20th Century Fox Home Entertainment"
          },
          {
            "type": "Image",
            "url": "https://media3.giphy.com/media/BVStb13YiR5Qs/giphy.gif?cid=550add23837d0fdf40feddd3a4df0de03a98b54019e5cffc&rid=giphy.gif",
            "altText": "Lionel Richie Hello GIF"
          }
        ]
      }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2",
    "doistCardVersion": 0.5

  "bridge": {
    "bridgeActionType": "composer.append",
    "text": "My Text to Append"
  }
}

Adding a UI Extension

Extensions are added to integrations in the app console. An integration can have multiple UI extensions added to it; these can be extensions for both the Quick Actions and the context menu, multiple of each are allowed. The exception to this are settings extensions though as an integration can only have one settings extension.

To add an extension, you need to create a general integration (and not channel/thread) first. Then from the integration details page, click on "UI Extensions".

Quick Actions and Context Menu

For an extension to appear in the Quick Actions or context menu, click the "Add a new UI extension" button. Then, enter the details of your extension.

Once you create an extension, you can then add an icon to it. This icon will be the image that appears in the Quick Actions/Context menu list and not the integration's image (as you can have multiple extensions, you may want different icons for each).

Properties

Settings Extensions

Use the "Add a settings extension" button to add a settings extension if you need one. An integration can only have one of these.

Properties

Doist Cards

Context

We use Doist Cards for UI Extensions. Doist Cards are based on Adaptive Cards.

We have also created our own schema based on the Adaptive Cards schema. We call this schema Doist Cards. The Doist Cards schema is a subset of the Adaptive Cards schema, that provides the elements currently supported in the Twist clients. We aim for all current versions of 1st party clients to support the latest version of the Doist Cards schema.

Doist Cards Versions

How to Use

This spec below loosely follows the official Schema Explorer. It lists all the elements supported in Doist Cards SDKs (mobile and web). The Version column is the Doist Cards Version, not one of Adaptive Cards.

Cards

Element

All Card Elements, Containers, and Inputs extend Element and support the below properties.

Card Elements

TextBlock

Image

RichTextBlock

Inline

Inline can be of type String or TextRun.

TextRun

Containers

ActionSet

Container

ColumnSet

Column

Actions

Action.Submit

Action.OpenUrl

Inputs

Input.Text

Input.Date

Input.Time

Input.ChoiceSet

Input.Toggle

Choice

Describes a choice for use in a ChoiceSet.

Types

BackgroundImage

Enums

Spacing

Please note: The values sent for this are case insensitive

HorizontalAlignment

Please note: The values sent for this are case insensitive

VerticalContentAlignment

Please note: The values sent for this are case insensitive

FontWeight

Please note: The values sent for this are case insensitive

FontSize

Please note: The values sent for this are case insensitive

Color

Please note: The values sent for this are case insensitive

ImageFillMode

Please note: The values sent for this are case insensitive

Style

Please note: The values sent for this are case insensitive

InputStyle

Please note: The values sent for this are case insensitive

ImageSize

Please note: The values sent for this are case insensitive

Notes

1

This is Doist Cards only and not part of the adaptive card spec