MS Office

The following sections describe the available configuration options for deploying and running the Teams Adapter components - Service App, Web Service, and Platform App.

For more details and examples related to the functionalities provided by the Teams Adapter (e.g., configuring the Service App rules or creating custom actions for the Platform App), see the Functionalities section.

If you are using the Teams Adapter in an io.Connect Desktop project, the configuration for the Service App component must be provided as a standard io.Connect app definition file. Use the "customProperties" top-level key to provide configuration settings for the Service App component itself:

{
    "name": "ms-teams-adapter",
    "type": "window",
    "title": "Teams Adapter",
    // Auto start the Service App with the platform.
    "autoStart": true,
    // Disable running multiple instances.
    "allowMultiple": false,
    // Hide the Service App from the io.Connect launcher.
    "hidden": true,
    "details": {
        // URL pointing to the location where the Service App is deployed.
        "url": "https://example.com/teams-adapter/",
        // This will hide the Service App window from the user.
        // Set to `true` if using `"sso"` authorization type (see the `Authorization` section).
        // Set to `false` (default) if using `"login"` authorization type to allow the user to log in via the UI.
        "hidden": true,
        // Allow the app to retrieve the authentication info (SSO token)
        // if using `"sso"` authorization type.
        "allowAuthInfo": true,
        // Enable the io.Connect Channels for the Service App.
        "allowChannels": true
    },
    "customProperties": {
        // Service App configuration settings.
    }
}

For io.Connect Browser projects, the configuration for the Service App component must be provided as an app definition when initializing your Main app:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    applications: {
        local: [
            {
                name: "ms-teams-adapter",
                type: "window",
                title: "Teams Adapter",
                details: {
                    // URL pointing to the location where the Service App is deployed.
                    url: "https://example.com/teams-adapter/"
                },
                customProperties: {
                    // Service App configuration settings.
                }
            }
        ]
    }
};

const { io } = await IOBrowserPlatform(config);

The following properties can be used under the "customProperties" top-level key of the Service App app definition in order to provide settings specific for the Service App:

Authorization

The "authorization" object is used for defining the type of the authentication procedure - whether to use SSO to log the user in the Teams Adapter automatically, or to require them to log in manually for each session.

The "authorization" object has the following properties:

Example configuration for SSO authentication:

{
    "customProperties": {
        "authorization": {
            "type": "sso"
        }
    }
}

If using manual login (the "type" property of the "authorization" object is set to "login"), you must provide OAuth login information by using the "oAuth" object in order for the Teams Adapter to be able to authenticate to the Microsoft Graph API.

The "oAuth" object has the following properties:

⚠️ Note that the set of permissions for access to the Microsoft Graph API may vary depending on the Teams Adapter functionalities you want to use. For details on the required permission for each functionality, see the respective entry in the Default Implementations section.

Example configuration for manual login:

{
    "customProperties": {
        "authorization": {
            "type": "login"
        },
        "oAuth": {
            "appId": "my-app-id",
            "tenantId": "my-tenant-id",
            "scopes": [
                "Chat.Read",
                "Chat.ReadBasic"
                "Chat.ReadWrite",
                "ChatMessage.Read",
                "ChatMessage.Send",
                "User.Read",
                "User.ReadBasic.All"
            ]
        }
    }
}

Web Service Connection

To define settings for controlling the Web Service component, use the "webService" object.

The "webService" object has the following properties:

Example configuration:

{
    "customProperties": {
        "webService": {
            "enabled": true,
            "url": "https://example.com/my-web-service",
            "resource": ["/users/me/chats/getAllMessages"]
        }
    }
}

Messages

The "messages" object can be used to instruct the Service App component to retrieve rich message information for the "onMessage" rule. To do so, you must have encryption certificates in PEM format as described in the detailed deployment guide for the Service App component.

The "messages" object has the following properties:

Each object in the "encryptionCertificates" array has the following properties:

Example configuration:

{
    "customProperties": {
        "messages": {
            "requestContents": true,
            "encryptionCertificates": [
                {
                    "data": "certificate-data",
                    "encryptionCertificateId": "certificate-serial-number",
                    "privateKey": "private-key-data"
                }
            ]
        }
    }
}

Permissions

The "permissions" object has the following properties:

Example configuration:

{
    "customProperties": {
        "permissions": {
            "allowEval": true
        }
    }
}

Rules

The "rules" object allows you to specify rules that will determine the behavior of the Teams Adapter in response to various events from Teams, such as receiving a message, or when the user invokes a Platform App action from the Teams UI.

The "rules" object has the following properties:

For more details on the shape of the objects accepted in the rule arrays and on how to configure the response behavior of the Service App, see the Functionalities > Service App Rules section.

⚠️ Note that the Web Service component is optional. It's possible to use the Teams Adapter without a Web Service component, but you will lose the features that depend on receiving events from Teams, as well as the UI functionalities provided by the Platform App component.

The Web Service component itself has little configuration by design. Most of its functionality is controlled using arguments from the Service App. The configuration for the Web Service is a JSON file delivered with the ZIP file containing the Web Service component. It must be hosted with the Web Service.

⚠️ Note that the Service App also contains configuration settings for the connection to the Web Service component. For more details, see the Service App > Web Service Connection section.

The configuration file for the Web Service component contains the following properties:

The following is an example configuration for the Web Service component:

{
    "appId": "my-web-service-app-id",
    "debug": false,
    "userWhitelist": "^.*@interop[.]io$",
    "tenantIdAllowList": ["my-tenant-id"]
}

⚠️ Note that the Platform App component is optional. The Platform App and the UI actions it provides can't be used without the Web Service component.

The Platform App component is a standard Teams app written with the Microsoft Teams Toolkit. As such, its runtime configuration is a JSON file named manifest.json and located in the /appPackage directory of the ZIP delivery file.

Most of the properties in this file don't need to be modified. The only required change is to specify the URL of your Web Service component using the "validDomains" top-level array:

{
    "validDomains": [
        "teams-webservice-prod.example.com"
        "teams-webservice-dev.example.com"
    ]
}

You can use the "composeExtensions" top-level key to remove or modify the default UI actions, or to add your own custom UI actions. For more details, see the Functionalities > Usage > Platform App UI Actions section.