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.
💡
By the end of this article, you will be able to receive messages only. Later articles cover how to respond to messages, add authentication and more.
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.
💡
Channels send various types of messages, as explained in the
Introduction article. The schema for each message can vary and be quite dynamic. That's why we accept the request as plain text and handle deserialization into structures later.
- 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.
From the Overview page, copy the values of:
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
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
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
💡
If you choose a specific data residency, ensure it matches the Redirect URI you configured earlier.
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.
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.
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.
💡
The demo application has no screens, but ODC will still open a Microsoft Edge or Google Chrome browser. Ignore the browser window and any error message you see.
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.
