ECC Custom Apps – Developer Guide

overview ecc custom apps allow you to build and embed your own applications directly inside the exotel ameyo ecc 4 x agent workspace these apps run inside an iframe within the agent workbench and communicate with the platform using the aaf sdk ( aaf sdk js — ameyo application framework) using sdk events and methods, your application can react to call and chat lifecycle changes fetch agent, session, and campaign context trigger host ui actions (toasts, forms, popups) make ameyo rest calls through the parent shell access crm data and interaction context exchange structured data with ecc in real time this enables advanced workflows such as screen pop, contextual crm panels, campaign specific data capture, call workflow orchestration, and real time agent assistance where the app runs the custom app is loaded inside the ecc 4 x agent workspace it runs inside an iframe within an assigned workbench slot it receives context through query parameters such as origin , instanceid , and sdkbaseurl (if configured) your application must dynamically load and initialize the aaf sdk before using any events or methods getting started install the cli and generate your app npx create exotel gwt app\@latest you will be prompted for an app folder name and a starting template (blank, call session monitor, or global events logger) then cd your app folder npm install npm run dev when ready to deploy npm run ship this produces gwt upload aaex , which you upload via admin → app manager and assign to a workbench slot 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 and call scripting custom disposition workflows external system integration panels ai assist dashboards application architecture a custom app may be built using plain html + javascript, react, angular, vue, or any framework capable of running in an iframe minimum requirements a single entry html file (or spa entry point) dynamic aaf sdk loading sdk initialization event registration method invocation handling the generated scaffold handles sdk loading, typed event helpers, the signal design system setup, and the correct aaex packaging layout out of the box you focus on the use case, not the plumbing loading the aaf sdk the sdk ( aaf sdk js ) is provided by the ecc host the scaffold resolves the correct url 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 the sdk module loads, initialize it using ameyoclient initialize({ instanceid "ameyoiframe" }) store the returned client instance and use it throughout your app lifecycle do not register any events or call any methods before initialization completes working with events the sdk exposes two primary event groups global events — registered via client globalevent(eventname, callback) used for call lifecycle tracking ( callconnected , callhungup , etc ) agent session and availability changes crm triggers and screen pop logic context events — registered via client contextevent(eventname, callback) used for slot local events such as tab changes and ticket saves events scoped to the workbench slot rather than the whole session refer to the sdk reference documentation in your generated project for the complete event list, payload definitions, and valid slot contexts always handle registration promise rejections error code 121 means the event name is not recognized on this ecc build error code 122 means the event is not allowed in the current slot type calling sdk methods methods are available under namespaces on the client // fetch data about the logged in agent client globaldata get("loggedinuser") // trigger a host ui action client interface trigger({ action "showtoast", data { } }) // make a rest call through the parent shell client httprequest({ method "get", url " ", }) all methods return promises always handle both success and error states argument structure must match the sdk documentation exactly — refer to the sdk reference in your generated project data flow best practices use event payload data to drive ui updates use campaign and session context to determine business logic do not assume undocumented fields will be present treat sdk contracts as strict — only use documented event names and method signatures always implement error handling for sdk load failure, initialization failure, event registration errors, and method invocation failures use only event names from the supported events list in your scaffold — do not invent or guess event names ui guidelines use the signal design system ( @exotel npm dev/signal design system ), included in every generated project it provides components built to match the agent interface and behave correctly inside an iframe light theme only — agent workbench slots expect a light, readable ui do not add a dark mode toggle narrow and wide layouts — design for compact workbench slots using drawers, dialogs, and progressive disclosure rather than dense single page layouts testing your app before deployment, verify sdk loads correctly from the resolved base url initialization occurs once and completes before any event registration event callbacks trigger as expected method calls return expected responses behavior is correct across call types (inbound, outbound, manual) behavior is correct when the agent switches campaigns or logs out and back in always test inside the live ecc agent workspace — local development gives you the shell, but ameyoclient is only available inside the real ecc environment packaging and deployment npm run ship produces gwt upload aaex — a ready to upload archive containing index html , static/ , manifest json , and app logos upload via admin → app manager , then assign to a workbench slot common deployment pitfalls manifest json name and version must match the url path ecc serves (e g /si/{name}/{version}/ ) a mismatch causes 404 errors on js bundles or static assets if the sdk fails to load, confirm origin / instanceid query parameters are correct, or set ?sdkbaseurl= to your ecc base url ai assisted app development if you are using ai tools such as cursor, copilot, or claude to build an ecc custom app, every generated project includes a developer md file this is a structured contract that tells ai tools how to work correctly inside this system — which helpers to use, which files to leave alone, and how to implement features without breaking sdk initialization or packaging open developer md , copy the "copy/paste into an ai agent" block into your agent chat, and say "let's begin " the agent will ask a few short questions and then implement in the repo a reference sample app is included in the scaffold use it as a structural reference for the essential files required by the app framework troubleshooting symptom likely cause ameyoclient not available app not opened inside ecc agent workspace, or parent didn't load aaf sdk js js bundle 404 / 403 manifest json name/version mismatch; wrong /si/ path event registration fails (121) event name not recognized on this ecc build — use only supported event names from your scaffold event registration fails (122) event not allowed in this slot type (workbench vs modal vs navbar) no aaf sdk js in network fix bundle 404 first; then check sdkbaseurl / origin parameters theme looks wrong confirm light theme is applied; check parent iframe color scheme build fails on imports direct @mui/material import — use @exotel npm dev/signal design system instead when to contact support reach out to exotel support if the sdk fails to load despite correct configuration events are not firing as documented method calls fail with platform level errors you suspect an environment or ecc configuration issue