Integrate existing third-party APIs using Teams Toolkit v4

Important

We've introduced the Teams Toolkit v5 extension within Visual Studio Code. This version comes to you with many new app development features. We recommend that you use Teams Toolkit v5 for building your Teams app.

Teams Toolkit v4 extension will soon be deprecated.

Teams Toolkit allows you to access and use existing APIs for building Teams apps. Your organization or a third-party might have developed these APIs. When you use Teams Toolkit to connect to an existing API, Teams Toolkit performs the following functions:

• Generate sample code in the ./bot or ./api folder.
• Add a reference to the @microsoft/teamsfx package to package.json.
• Add app settings for your API in .env.teamsfx.local that configures local debugging.

Teams Toolkit allows you bootstrap sample code to access the APIs, if you don't have language appropriate SDKs to access these APIs.

Configure API connection

You can add an existing third-party API to your Teams app using:

• Teams Toolkit
• TeamsFx CLI commands

Add API connection using Teams Toolkit

Add a connection to an existing third-party API using the following steps:

1. Open your Teams app project in Visual Studio Code.

2. Select Teams Toolkit from the Visual Studio Code activity bar.

3. Select Add features in the DEVELOPMENT section.

   

   The Add Feature dropdown list appears.

4. Select API Connection.

   

5. Enter endpoint for the API, and then press Enter.

   Ensure that the endpoint is a valid http(s) URL. Teams Toolkit adds the endpoint to the project's local app settings, and it's the base URL for API requests.

   

6. Select the component that needs to connect to the API, and then select OK.

   

7. Enter an alias for the API, and then press Enter.

   The alias generates an app setting name for the API. Teams Toolkit adds the alias to the project's local app setting.

   

8. Select the required authentication for the API request from the API authentication type.

   

   Teams Toolkit generates appropriate sample code and adds corresponding local application settings based on authentication that you select. To configure authentication:

Basic

For implementing basic authentication using username and password:

• Select Basic.
• Enter the username for basic Auth.

Teams Toolkit generates the sample code to call your API at bot\myAPI.js.

Certification

• Select Certification to authenticate requests using certificates.

Teams Toolkit generates the sample code to call your API at bot\myAPI.js.

Azure Active Directory (Azure AD)

• Select Azure Active Directory (Azure AD) to authenticate requests using Azure AD access tokens.

Teams Toolkit generates the sample code to call your API at bot\myAPI.js.

API Key

• Select API Key to implement authentication using an API key.
• Select the required API key position in request.
• Enter an API key name.

Teams Toolkit generates the sample code to call your API at bot\myAPI.js.

Custom Auth Implementation

• Select Custom Auth Implementation to customize authentication according to your app requirement.

Teams Toolkit generates the sample code to call your API at bot\myAPI.js.

You've successfully added a connection in your Teams app to an existing API.

Add API connection using TeamsFx CLI

The base command of this feature is teamsfx add api-connection [authentication type]. The following table provides a list of different authentication types and their corresponding sample commands:

Tip

You can use teamsfx add api-connection [authentication type] -h to get help document.

Authentication type	Sample command
Basic	teamsfx add api-connection basic--endpoint https://example.com --component bot--alias example--user-name example user--interactive false
API Key	teamsfx add api-connection apikey--endpoint https://example.com --component bot--alias example--key-location header--key-name example-key-name--interactive false
Azure AD	teamsfx add api-connection aad--endpoint https://example.com --component bot--alias example--app-type custom--tenant-id your_tenant_id--app-id your_app_id--interactive false
Certificate	teamsfx add api-connection cert--endpoint https://example.com --component bot--alias example--interactive false
Custom	teamsfx add api-connection custom--endpoint https://example.com --component bot--alias example--interactive false

---

Directory structure updates to your project

Teams Toolkit modifies bot or api folder based on your selection:

1. Generate {your_api_alias}.js\ts file. The file initializes an API client for your API and exports the API client.

2. Add @microsoft\teamsfx package to package.json. The package provides support for the common API authentication methods.

3. Add environment variables to .env.teamsfx.local. You must configure environment variables for the selected authentication type. The generated code reads values from the environment variables.

See also

• Teams Toolkit Overview
• Publish Teams apps using Teams Toolkit