If you’re looking to build Microsoft Teams Apps, whether they are Tabs, Bots, Message Extensions or Webhooks, Microsoft has done a great job with their documentation. You can find some pretty rad documentation here:
https://docs.microsoft.com/en-us/microsoftteams/platform/mstdd-landing
You can even find a cool Adaptive Card Designer here: https://adaptivecards.io/designer/
We have built some seriously complex Teams Flows that require custom OAuth integration with Azure Active Directory B2C and also require connecting those accounts with Microsoft’s Teams O365 Logins so that we can personalize the user’s experience and allow a seamless integration between O365 and their SaaS Platform Account.
HOWEVER….MICROSOFT TEAMS LEAVES A LOT TO BE DESIRED….
For a product that is being used by some of the top enterprises, the developer experience in building Teams apps is very sucky.
We have run into too many issues that have delayed our deadlines, made us lost significant dollars on R&D and have only made our clients get the perception that we don’t know what we are doing.
So, it is our humble request to Microsoft Teams to really take these type of conversations seriously.
Here is our list of gripes:
You cannot change the width of the Adaptive Cards
While we understand the reason for maintaining this control (has to do with providing a good UI/UX on Mobile, Tablets and Desktops), we still feel that the designers of today are no newbies either. They have a keen sense of handling issues like these so long as the tool provides us with options.
You can read about this issue here: https://github.com/MicrosoftDocs/msteams-docs/issues/739 – Apparently, we’re not the only ones disappointed.
Call Stack Issue
We’re not certain yet whether this is due to poor example code offered by Microsoft, or if there’s a genuine bug in Teams. Apparently, using the new version of Newtonsoft.Json (13.*) has added a JSON serialization Max-Depth limit (and rightly so). This causes Bot conversations to start throwing bugs when that limit of 64 (default by Newtonsoft) is exceeded.
Downgrading to 12.0.3 solves this problem, however, we think that there is a bigger issue underneath all of this. The call-stack of dialogs and necessary states needs to be hydrated correctly when we replace the dialog. It appears that there might be a bug in this call stack not cleaning up. You can read about it here: https://github.com/microsoft/BotBuilder-Samples/issues/3328
OAuth Issues
The biggest challenge for us was understanding the OAuth connectivity with 3rd party OAuth providers like that of Azure Active Directory B2C. Most examples assume that Teams users will connect with Microsoft O365 and take it from there. But what if we had existing OIDC compliant OAuth logins in our SaaS products? How would we go about integrating w/ a 3rd party OAuth provider? How would things be configured?
The documentation around the concepts for this topic is sparse. They have a great write-up on Generic OAuth, however the naming seems suspect here, there’s a Generic OAuth2 and there’s an OAuth2 Generic Provider. 🙂 It’s the latter that gives you more control – if you wanted to know which one to use. The examples leave a LOT to be desired. To be candid, we opened a Customer Support ticket in Azure, and also reached out to the team via GitHub and it took a bunch of figuring out to finally get this functionality working.
You can read about it here: https://github.com/microsoft/botframework-sdk/issues/6342
Some Additional Thoughts
I think there’s some confusion b/w Node and C# versions and which version might be the best. It took us a while to really understand what was going on there.
We run into random delays (which we know are not API related) – there’s no activity indicators in Teams, so even something simple as a Bot typing indicator when there are delays in rendering messages would be great.
Images are limited to 1024×1024 and 1MB. We understand and appreciate this. Existing systems that allow users to upload their own images may not necessarily adhere to these standards. We had to go back into our SaaS platform and retroactively resize the images because we allowed a 2MB limit for images. These things matter…
Trying to be too many things to too many people. We all know that Microsoft has the purest intentions in allowing different products and developers with other programming languages to build on their stack.
However, Microsoft repeatedly misses their mark in curating a great experience. For e.g. there is a Bot Framework, Teams Bot, Bot skills that you suddenly become aware of. This adds to the confusion. Do I care about anything other than Teams? Not really. So why doesn’t the documentation curate my experience so I don’t even care about those other frameworks.
Likewise, we get it that Microsoft wants to allow C# and NodeJS for their Teams development. Can we please just get a curated experience based on the language we pick?
There are too many references to different languages and corresponding examples all over their documentation. It may not hurt to create micro-experiences tailored to a programming language of the user’s choice.
Twilio does a great job with this. Stripe is phenomenal in their documentation as well. We’d love to see more of that with Microsoft.
Conclusion
As a Software Development company, we love developing rich, interactive experiences for our clients and for our own products.
We have noticed that the learning curve associated with Teams is significant, and there are too many hidden gotchas all over the place.
It is hard to understand best-practices and implement a single strategy from start-to-finish. We have repeatedly had to rewrite our code after understanding more about the underlying best practices, which were not evident when we first started working with development.
So, our advice to fellow developers and other software agencies – PLAN WISELY AND BID HIGH. We’ve lost quite a bit of money on a project we undertook largely because of all the hidden land-mines that we were not aware of. Lessons learned.
Share your experiences in building Teams app here…