Omni Custom Apps – Developer Guide

overview omni custom apps allow you to build and embed your own applications directly inside the exotel ameyo agent console (ecc) these apps run inside an iframe within the agent workspace and communicate with the platform using the omni sdk using sdk events and methods, your application can react to interaction lifecycle changes fetch agent and campaign context initiate interactions trigger crm actions access configuration data exchange structured data with ecc this enables advanced workflows such as screen pop, contextual automation, crm extensions, campaign specific tools, and real time agent assistance where the app runs the custom app is loaded inside the agent console (ecc) it runs inside an iframe it receives context through query parameters such as origin instanceid sdkbaseurl (if configured) your application must dynamically load and initialize the omni sdk before using any events or methods common use cases custom apps are typically built for crm screen pop and contextual record loading click to call or outbound automation campaign specific data capture forms real time interaction insights workflow orchestration custom disposition workflows external system integration panels sms/whatsapp trigger utilities ai assist dashboards sdk documentation (source of truth) always refer to the official documentation for sdk loading instructions initialization configuration complete list of supported events complete list of available methods payload formats and argument requirements url based integration appraoch docid\ jyrqfarow5pmd6mofxpzb omni toolbar events & methods reference docid\ jthp6inxptrgrl2it yz3 these documents define the authoritative contract for the sdk application architecture a custom app may be built using plain html + javascript react angular vue any framework capable of running in an iframe minimum requirements a single entry html file (or spa entry point) dynamic sdk loading sdk initialization event registration method invocation handling loading the omni sdk the sdk must be loaded from {base}/omniapp/sdk/ameyo sdk js where base is resolved in this order sdkbaseurl query parameter origin query parameter window\ location origin remove any trailing slash before appending the sdk path dynamic import is recommended for modern applications sdk initialization after loading the sdk module, initialize it using sdk initialize({ context "app", origin origin, instanceid "ameyoiframe" }) store the returned sdk instance and use it throughout your app lifecycle do not call any sdk methods before initialization completes working with events the sdk exposes two primary event groups interaction events registered via sdk interaction register(eventname, callback) used for interaction lifecycle tracking crm triggers screen pop logic transfer and conference handling disposition events session events registered via sdk session register(eventname, callback) used for login status updates agent availability changes campaign selection updates extension changes event payloads include structured context such as interactionid campaignid customerdetails channeldetails refer to the docid\ jthp6inxptrgrl2it yz3 documentation for the complete event list and payload definitions always handle registration promise rejections calling sdk methods methods are exposed under sdk session sdk interaction sdk configuration other documented namespaces method invocation format sdk\[api]\[methodname]\( args) examples include fetching current user details initiating an interaction logging in via sdk fetching disposition codes retrieving selected campaigns all methods return promises handle both success and error states argument order and structure must match the official documentation exactly data flow best practices use interaction payload data to drive ui updates use campaign context to determine business rules do not assume undocumented fields treat sdk contracts as strict always implement error handling for sdk load failure initialization failure event registration errors method invocation failures testing your app before deployment verify sdk loads correctly from resolved base url confirm initialization occurs once validate event callbacks trigger as expected confirm method calls return expected responses test across interaction types (voice, chat, etc ) validate behavior when agent switches campaigns validate behavior during login/logout cycles packaging & deployment your app should be hosted on a secure https endpoint accessible to the ecc environment optimized for iframe rendering lightweight and responsive if packaging as an ameyo app extension ( aaex), ensure the structure aligns with platform requirements ai assisted app development if you are using ai tools such as cursor, chatgpt, copilot, or claude to build an omni custom app, you can use the provided ai build contract and scaffold template these files help ensure correct sdk initialization, accurate event and method usage, and alignment with the official documentation they are optional accelerators designed to reduce integration errors and speed up development a reference sample app is attached below use this as a structural reference when building your integration, as it includes the essential files required by the app framework troubleshooting if the app fails to function confirm sdk url resolution confirm initialize() has been called confirm event names match documentation exactly check browser console for promise rejections verify query parameters are being passed correctly ensure cors and hosting configuration allow iframe access when to contact support reach out to exotel support if sdk fails to load despite correct configuration events are not firing as documented method calls fail with platform level errors you suspect an environment configuration issue