Omni Custom Apps – Developer Guide

omni custom apps let you extend the contact center by embedding custom functionality directly within the agent workspace these apps run inside an iframe and connect to the platform using the omni sdk, which gives you access to real time events like calls, messages, and agent actions in practice, this means you can build things like crm integrations with screen pop, messaging triggers, call workflows, or lightweight agent assist tools—all directly inside the agent interface getting started (takes a few minutes) start by installing the cli globally npm i g create exotel omni app or npx create exotel omni app\@latest then generate your app create exotel omni app you’ll be asked whether you want a blank app or a template if you’re exploring, templates are faster—they give you working ui and patterns you can modify instead of starting from zero once the project is created npm install npm run dev that’s enough to get a running app locally with the sdk already wired up when you’re ready to deploy npm run ship this produces an omni upload aaex file, which you upload via admin → app manager what’s actually happening under the hood the generated app already handles the hard parts loading and initializing the omni sdk setting up event subscriptions wiring the app into the iframe environment packaging the app in the correct aaex format you’re not building integration plumbing—you’re building the actual use case the important implication don’t touch the sdk setup unless you know exactly why how you should build (this is where most teams go wrong) the fastest way to build these apps isn’t manually—it’s with ai every generated project includes a developer md file this isn’t documentation fluff—it’s a contract that tells ai tools exactly how to work within the system the intended workflow is simple add developer md in any ai agent console and say 'let's begin' describe what you want to build the agent will ask a few clarifying questions implement the feature directly in your codebase stay within the allowed sdk and ui patterns if you follow this, you can go from idea to a working app in minutes if you ignore it, you’ll end up manually wiring things the scaffold already solved ui expectations (keep this simple) use the signal design system (@exotel npm dev/signal design system) as your default it’s already included—you don’t need to install anything extra running npm install pulls it in automatically these components are built to match the agent interface and behave correctly inside an iframe, which is where most custom uis break if something truly isn’t available, you can fall back to mui—but that should be rare the practical rule start with signal, only deviate if you hit a real limitation project layout (what you actually need to care about) you don’t need to understand the entire repo focus on this app/components/usecases/ → where your feature logic lives app/omni/ → sdk integration (leave this alone) registeromnisdk generated ts → where events are wired manifest json → controls name, version, and deployment path everything else is supporting structure also keep sdk logic out of your ui components use the existing bridge layer mixing the two will make your app harder to maintain very quickly a couple of non negotiables there are two files you should not modify loadomnisdk ts omniprovider tsx they’re already aligned with the platform requirements changing them is the fastest way to introduce hard to debug issues same goes for events only use documented sdk events and methods don’t invent payloads always handle errors properly deployment details that trip people up the packaging step ( npm run ship ) gives you a ready to upload aaex that part is straightforward where things usually break is hosting your app is served from a path like /si/{name}/{version}/ those values come from manifest json if they don’t match your hosting setup, you’ll get missing js errors (usually 404s on static files) also make sure you’re uploading the full dist/ output, including the static/ folder troubleshooting (quick reality checks) if something breaks, it’s usually one of these js files not loading → manifest mismatch theme looks off → iframe or root theme issue events not firing → wrong event name or silent error build suddenly unstable → you ran npm audit fix force that last one is worth repeating don’t do it it tends to upgrade dependencies beyond what the template supports why this setup exists without this scaffold, teams consistently run into the same problems sdk initialization issues incorrect event handling broken iframe theming invalid packaging ui that doesn’t adapt to the agent layout this setup removes those variables so you can focus on what actually matters building the workflow and if you lean into the ai workflow properly, you’re not just saving effort—you’re compressing build time from days to minutes