This is the second part of the ODC with Bots for Teams series. In this tutorial, we will create a messaging endpoint in an OutSystems Developer Cloud application and set up a basic Azure Bot resource in your Azure tenant, along with a Microsoft Entra application registration.

Make sure you have read the Introduction to understand the different parts of this setup.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.1 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.1.

Messaging Endpoint Application

A messaging endpoint receives various types of messages from communication channels, including user messages. In an OutSystems Developer Cloud, this is an exposed REST API endpoint that accepts POST requests and is later configured in an Azure Bot resource.

• Open the ODC with Bots for Teams Demo application and switch to the Logic tab.

• In Integrations - REST, select MessagingEndpoint.

The exposed REST API is configured with authentication set to None, and documentation is turned off.

• Click on the Messages endpoint

The Message endpoint is set up to accept POST requests and has one input parameter, Request, which is received in the Body as type Text.

• Copy the URL of the Messages endpoint. If you have not changed the demo app name it should be /ODCwithBotsforTeamsDemo/rest/MessagingEndpoint/Messages. We need that URL path later on, when we configure the Azure Bot resource.

For now, we will leave the Demo app and set up the rest in the Azure Portal.

Register Entra Application

A bot resource requires an Entra application registration, which we later use to get an access token to communicate with the Bot Connector API and respond to messages.

In Azure Portal go to App Registrations and click on New registration.

• Name - Microsoft Teams Conversational Bot with ODC

• Supported account types - Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)

• Click Register

From the Overview page, copy the values of:

• Application (client) ID

We will need these values later.

Add a Client Secret

Under the Manage menu select Certificates & secrets

Select the Client secrets tab and click on New client secret

• Description - ODC Conversational Bot sample

• Expires - Recommended: 180 days (6 months)

• Click Add

Immediately after adding the new client secret, copy the Value and save it for later, as it will only be displayed once. We won't use the Client Secret in this article, but it will be needed in future articles.

Add a Redirect URI

The final configuration step is to add a Redirect URI to the application registration.

Under the Manage menu select Authentication.

In the Platform configurations section click Add a platform

• Select Web

• Redirect URIs - https://token.botframework.com/.auth/web/redirect

• Click Configure

Create an Azure Bot

With our basic application registration complete, we can now create an Azure Bot resource that will connect one or more channels (like Microsoft Teams) with our ODC messaging endpoint.

In Azure Marketplace search for Azure Bot and click Create - Azure Bot.

• Bot handle - BotId-<Application ID from Entra App Registration>

• Subscription - Select your subscription model

• Resource group - Choose a resource group where you want to place the bot resource

• Data residency - Global

• Pricing tier - Change plan to Free

• Type of App - Multi Tenant (corresponds to our Entra App Registration)

• Creation type - Use existing app registration

• App ID - Paste the Application ID from the Entra App Registration Overview page

• App tenant ID - Paste the Tenant ID from the Entra App Registration Overview page

• Click Review + Create, review the information the click Create

Wait until the deployment is complete, then click on Go to resource to continue.

Set Bot Profile

In the deployed Azure Bot resource, first go to the Settings - Bot profile menu and give your bot a meaningful display name and description. You can also upload a custom icon here.

Configure Messaging Endpoint

Next switch to the Settings - Configuration menu. The only settings we have to configure here is to provide the FQDN to our Messaging endpoint.

The messaging endpoint FQDN is the combination of your ODC stage base URL and the path you copied earlier from the Messaged endpoint of the demo application.

• Messaging endpoint - https://<ODC stage>.outsystems.app/ODCwithBotsforTeamsDemo/rest/MessagingEndpoint/Messages

• Click Apply to save the changes.

Receive a Message from Web Chat

Switch to ODC Studio and double-click the Messages endpoint in Logic - Integrations - REST - MessagingEndpoint.

Right-click on the Start node and select Add Breakpoint from the menu to add a breakpoint.

In the Debugger tab, click Start debugging.

Leave the debugger and go back to your Azure Bot resource. Select the Settings - Test in Web Chat menu. You should immediately see ODC Studio flashing.

Check the Request input parameter, which contains a JSON document that should look like this:

{
  "type": "conversationUpdate",
  "id": "KJvkAp8O6y1",
  "timestamp": "2025-01-20T05:49:46.1194744Z",
  "serviceUrl": "https://webchat.botframework.com/",
  "channelId": "webchat",
  "from": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
  },
  "conversation": {
    "id": "xxxxxxxxxxxxxxx-eu"
  },
  "recipient": {
    "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "My Demo OutSystems Bot"
  },
  "membersAdded": [
    {
      "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "name": "My Demo OutSystems Bot"
    },
    {
      "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
    }
  ]
}

This first message indicates that both a bot and a user joined a conversation.

Resume the debugger to continue.

Next type a message in the Web Chat console and inspect the message again in the debugger.

You should receive a message like this

{
  "type": "message",
  "id": "175nbLQPt2A7LhdRnSZeYM-eu|0000000",
  "timestamp": "2025-01-20T05:55:16.1409929Z",
  "localTimestamp": "2025-01-20T06:55:18.613+01:00",
  "localTimezone": "Europe/Berlin",
  "serviceUrl": "https://webchat.botframework.com/",
  "channelId": "webchat",
  "from": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "name": ""
  },
  "conversation": {
    "id": "xxxxxxxxxxxxxxx-eu"
  },
  "recipient": {
    "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "My Demo OutSystems Bot"
  },
  "textFormat": "plain",
  "locale": "de",
  "text": "Hello",
  "attachments": [],
  "entities": [
    {
      "type": "ClientCapabilities",
      "requiresBotState": true,
      "supportsListening": true,
      "supportsTts": true
    }
  ],
  "channelData": {
    "clientActivityID": "xxxxxxxxxxxx"
  }
}

In this case I, identified by the from object, sent a text “Hello” to the bot identified by the recipient object.

The Test in Web Chat feature uses the Web Chat channel, which is activated by default. Later, you can disable these pre-activated channels once you are satisfied with your bot. However, for development purposes, you should keep it activated as it offers an easy way to test your implementation.

Summary

Congratulations! You have just completed the initial setup to receive messages from an Azure Bot resource. In this tutorial, we set up a new Azure Bot resource in your Azure Active Directory tenant. This resource sends messages received by a channel to a REST API endpoint in an OutSystems Developer Cloud application. In the next article, we will cover how to respond to incoming messages using the Bot Connector API.