Introduction

This guide walks you through configuring the jtel ACD Client Tab as a custom application within Microsoft Teams, providing seamless integration with the jtel Carrier Portal. By adding this app to your Teams environment, users can access the jtel ACD Client directly within Teams.

The setup process involves creating a Teams app package, uploading it to your Teams admin portal, and configuring it for global use within your organization. This document provides step-by-step instructions on the prerequisites, installation, and setup, along with guidance for updating the app as needed.

Guide Overview

Prerequisites: Setting up the required files for the Teams app.
App Creation: Configuring and zipping the necessary files for upload.
Installation and Setup: Uploading the app to Teams and configuring it within your organization's policies.
Updating the App: Procedures to update the app version and troubleshoot if necessary.

Prerequisites

To begin, create a Teams application by preparing three files:

Icon-color.png and Icon-outline.png - the application's icons.
manifest.json - the application's configuration file.

Configuring manifest.json

The manifest.json file defines key application properties and configurations, such as app identifiers, permissions, and URLs.

manifest.json

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "id": "$application_id",
  "version": "1.0.0",
  "packageName": "de.jtel.acd.teams",
  "developer": {
    "name": "jtel GmbH",
    "websiteUrl": "https://jtel.de/",
    "privacyUrl": "https://jtel.de/privacy-statement-eu/",
    "termsOfUseUrl": "https://jtel.de/en/legal",
    "mpnId": ""
  },
  "name": {
    "short": "jtel ACD",
    "full": "jtel ACD Client Tab"
  },
  "description": {
    "short": "jtel ACD Teams Client",
    "full": "The jtel ACD Client for Microsoft Teams provides seamless integration with jtel's Carrier Portal, enabling users to manage carrier operations directly within Teams. Access dashboards, monitor performance metrics, and collaborate with your team efficiently."
  },
  "icons": {
    "outline": "Icon-outline.png",
    "color": "Icon-color.png"
  },
  "accentColor": "#333333",
  "configurableTabs": [],
  "staticTabs": [
    {
      "entityId": "jtelACD",
      "name": "jtel ACD",
      "contentUrl": "$acd_portal_url",
      "websiteUrl": "$acd_portal_url",
      "scopes": [ "team", "personal" ]
    }
  ],
  "bots": [],
  "connectors": [],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "$acd_domain",
    "jtel.de"
  ],
  "webApplicationInfo": {
    "id": "$app_registration_id",
    "resource": "https://$acd_domain"
  }
}

Replace the following placeholders:

$application_id: The unique ID for your application. Generate one using a Free Online GUID Generator.
$acd_portal_url: The URL for the jtel Carrier Portal (e.g., https://myacdsystem.mydomain.de/CarrierPortal/login/myResellersUID/myClientsUID).
$acd_domain: Your portal's domain, such as myacdsystem.mydomain.de.
$app_registration_id: The "Application (client) ID" from Microsoft Azure’s App registrations.

Note: Teams only accepts URLs with https.

Note: Include webApplicationInfo only if using Microsoft Entra ID Login.

Once configured, compress the three files into a .zip file for upload.

Example in the attachment:

jtelACDTeamsTab.zip

Teams App Upload and Configuration

To create Teams Apps for your organization, you must be a Global Admin: Login to Microsoft 365 admin center with your admin credential and make sure of the role.

Login to Dashboard - Microsoft Teams admin center
Go to Teams apps → Manage apps and click on Upload new app.
Follow the steps to upload the zip file created in the previous steps.
By successful upload, you should see the following popup:
You should be able to see the new app in All apps table by typing the filter jtel ACD
Go to Teams apps → Setup policies and click on Global (Org-wide default)
Under Installed apps click on Add apps and search for the added application by the name “jtel ACD“. Next click on Add.
Under Pinned apps, click on Add apps and add the new application.
Finally click on save button and you should see the following popup:
Restart the Teams application and go to Apps and search for jtel ACD.
Select the new application and click on Add button. The portal will be opened then.

Tip: The teams application doesn't get the changes immediately. If you don't see the new application in teams application, then verify with the teams web application.

Updating an Existing App

Update the app folder (manifest.json and icons if necessary).
In manifest.json, the id should be the same and the version should be incremented (e.g., from 1.0.0 to 1.0.1 for example).
Zip the folder.
Login to Dashboard - Microsoft Teams admin center.
Go to Teams apps → Manage apps and search for the jtel app.
Open the app and click on New version Upload file on the top of the screen.
Upload the new zip.

If after uploading the zip an error message appears on top of the screen. you can delete the app and reinstall it from scratch.

With these steps, your organization can seamlessly integrate and manage the jtel ACD Client within Microsoft Teams.

Troubleshooting: Redirect Issue with Microsoft Entra ID Login

If the jtel ACD application repeatedly redirects or does not complete the login process inside Microsoft Teams, check the access-token version configured for the Microsoft Entra application.

This setting is configured in the Microsoft Entra App Registration manifest, not in the Teams application package manifest.json.

Open the Microsoft Entra admin center.
Go to Entra ID → App registrations.
Select the application used by the jtel ACD Teams integration.
Under Manage, select Manifest.
Locate requestedAccessTokenVersion inside the api object.

Change the value from null to 2:

"api": {
  "requestedAccessTokenVersion": 2
}

Save the manifest and restart or reload the Microsoft Teams application.

Setting requestedAccessTokenVersion to 2 has resolved a reported redirect issue when using Microsoft Entra ID authentication. A value of null defaults to access-token version 1.

Sanitized Microsoft Entra Application Manifest Template

All application IDs, object IDs, resource IDs, permission IDs, scope IDs, domains, URLs, credential information, and customer-identifying values have been replaced.
Values enclosed in <...> are documentation placeholders. This template cannot be imported without replacing them with valid values.

{
  "id": "<APPLICATION_OBJECT_ID>",
  "deletedDateTime": null,
  "appId": "<APPLICATION_CLIENT_ID>",
  "applicationTemplateId": null,
  "disabledByMicrosoftStatus": null,
  "createdByAppId": null,
  "createdDateTime": null,
  "displayName": "<CUSTOMER_NAME> JTEL",
  "description": null,
  "groupMembershipClaims": null,
  "identifierUris": [
    "https://<JTEL_ACD_HOSTNAME>"
  ],
  "isDeviceOnlyAuthSupported": null,
  "isDisabled": null,
  "isFallbackPublicClient": null,
  "nativeAuthenticationApisEnabled": null,
  "notes": null,
  "publisherDomain": "<TENANT_NAME>.onmicrosoft.com",
  "serviceManagementReference": null,
  "signInAudience": "AzureADMyOrg",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "samlMetadataUrl": null,
  "defaultRedirectUri": null,
  "certification": null,
  "optionalClaims": null,
  "requestSignatureVerification": null,
  "addIns": [],
  "api": {
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "requestedAccessTokenVersion": 2,
    "oauth2PermissionScopes": [
      {
        "adminConsentDescription": "Allows Teams to call the app's web APIs as the current user.",
        "adminConsentDisplayName": "Teams can access the user profile",
        "id": "<ACCESS_AS_USER_SCOPE_ID>",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "Enable Teams to call this app's APIs with the same rights that you have.",
        "userConsentDisplayName": "Teams can access your user profile",
        "value": "access_as_user"
      }
    ],
    "preAuthorizedApplications": [
      {
        "appId": "<MICROSOFT_TEAMS_WEB_CLIENT_ID>",
        "delegatedPermissionIds": [
          "<ACCESS_AS_USER_SCOPE_ID>"
        ]
      },
      {
        "appId": "<MICROSOFT_TEAMS_DESKTOP_MOBILE_CLIENT_ID>",
        "delegatedPermissionIds": [
          "<ACCESS_AS_USER_SCOPE_ID>"
        ]
      }
    ]
  },
  "appRoles": [],
  "info": {
    "logoUrl": null,
    "marketingUrl": null,
    "privacyStatementUrl": null,
    "supportUrl": null,
    "termsOfServiceUrl": null
  },
  "keyCredentials": [],
  "parentalControlSettings": {
    "countriesBlockedForMinors": [],
    "legalAgeGroupRule": "Allow"
  },
  "passwordCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "requiredResourceAccess": [
    {
      "resourceAppId": "<APPLICATION_CLIENT_ID>",
      "resourceAccess": [
        {
          "id": "<ACCESS_AS_USER_SCOPE_ID>",
          "type": "Scope"
        }
      ]
    },
    {
      "resourceAppId": "<MICROSOFT_GRAPH_RESOURCE_APP_ID>",
      "resourceAccess": [
        {
          "id": "<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_1>",
          "type": "Scope"
        },
        {
          "id": "<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_2>",
          "type": "Scope"
        },
        {
          "id": "<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_3>",
          "type": "Scope"
        },
        {
          "id": "<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_4>",
          "type": "Scope"
        }
      ]
    }
  ],
  "verifiedPublisher": {
    "displayName": null,
    "verifiedPublisherId": null,
    "addedDateTime": null
  },
  "web": {
    "homePageUrl": null,
    "logoutUrl": null,
    "redirectUris": [
      "https://<JTEL_ACD_HOSTNAME>/CarrierPortal/ssologin",
      "https://<JTEL_ACD_HOSTNAME>/CarrierPortal/azurelogin"
    ],
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUriSettings": [
      {
        "uri": "https://<JTEL_ACD_HOSTNAME>/CarrierPortal/ssologin",
        "index": null
      },
      {
        "uri": "https://<JTEL_ACD_HOSTNAME>/CarrierPortal/azurelogin",
        "index": null
      }
    ]
  },
  "servicePrincipalLockConfiguration": {
    "isEnabled": true,
    "allProperties": true,
    "credentialsWithUsageVerify": true,
    "credentialsWithUsageSign": true,
    "identifierUris": false,
    "tokenEncryptionKeyId": true
  },
  "spa": {
    "redirectUris": []
  }
}

Placeholder reference

Placeholder	Description
`<APPLICATION_OBJECT_ID>`	Object ID of the Microsoft Entra application registration
`<APPLICATION_CLIENT_ID>`	Application ID, also called the client ID
`<ACCESS_AS_USER_SCOPE_ID>`	ID generated for the application's `access_as_user` scope
`<CUSTOMER_NAME>`	Customer or application display name
`<TENANT_NAME>`	Microsoft Entra tenant name
`<JTEL_ACD_HOSTNAME>`	jtel ACD hostname without `https://`
`<MICROSOFT_TEAMS_WEB_CLIENT_ID>`	Microsoft Teams web client application ID
`<MICROSOFT_TEAMS_DESKTOP_MOBILE_CLIENT_ID>`	Microsoft Teams desktop and mobile client application ID
`<MICROSOFT_GRAPH_RESOURCE_APP_ID>`	Microsoft Graph resource application ID
`<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_1>`	First configured Microsoft Graph delegated permission ID
`<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_2>`	Second configured Microsoft Graph delegated permission ID
`<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_3>`	Third configured Microsoft Graph delegated permission ID
`<MICROSOFT_GRAPH_PERMISSION_SCOPE_ID_4>`	Fourth configured Microsoft Graph delegated permission ID

Redirect troubleshooting setting

For Microsoft Teams redirect or authentication-loop problems, verify that the following property is set inside the api object:

"requestedAccessTokenVersion": 2

This property belongs to the Microsoft Entra application registration manifest. It must not be added to the Microsoft Teams application-package manifest.

Page tree

Teams - Configure Jtel Portal in Microsoft Teams