Integrate existing third-party APIs using Teams Toolkit v4


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:

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.

    api add features

    The Add Feature dropdown list appears.

  4. Select API Connection.

    api select features

  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.

    api endpoint

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

    api invoke

  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.

    api alias

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

    api auth

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

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.

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:


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 --component bot--alias example--user-name example user--interactive false
API Key teamsfx add api-connection apikey--endpoint --component bot--alias example--key-location header--key-name example-key-name--interactive false
Azure AD teamsfx add api-connection aad--endpoint --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 --component bot--alias example--interactive false
Custom teamsfx add api-connection custom--endpoint --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