Generic Toolbar Integration

overview the generic web toolbar is a dedicated, web based telephony solution designed to achieve seamless computer telephony integration (cti) with a third party, web based customer relationship management (crm) application the toolbar acts as the agent's telephony palette, operating within an iframe embedded directly inside the third party crm's web page its purpose is to provide agents with essential telephony functions and display their real time call and presence status without requiring them to switch between applications note this is a licensable feature and requires enablement and full deployment by professional services and support key benefits embedded telephony inside crm for fewer context switches, faster handle time, and consistent agent experience across inbound, outbound, preview, and callbacks rich two‑way interoperability crm can trigger dial/dispose, while the toolbar emits events for screen pops, status, transfer/conference, and lifecycle updates for synchronized ui and workflows flexible authentication and extensibility password or crm‑backed sso, auto‑extension selection, custom showcrm handlers, and optional nodeflow customizations for callback and wrap‑up behaviors how it works the integration uses a two way communication model via javascript apis to link ameyo's core contact center functionalities with the third party crm application integration approach the third party crm is responsible for embedding the ameyo toolbar into an iframe within its user interface this process involves glue code incorporating a specific javascript integration file as "glue code" in the headers of the crm pages container defining a specific div element with the id ameyolframediv where the toolbar window will load prerequisites crm pages must support an iframe and include a container with id ameyoiframediv on each page where the toolbar appears, along with the ameyo integration script in headers matching users must exist in crm and ameyo, with ameyo agents provisioned prior to sso or password login attempts to ensure successful authentication and campaign access agent browsers must reach the ameyo host and ameyowebaccess endpoints, and the crm must expose a post /login logout endpoint for sso if crm‑backed authentication is required core communication flows and functions plan and prepare confirm license entitlement, engage professional services, and identify crm pages where the toolbar must appear to finalize scope and timelines verify the crm supports iframes on those pages, and ensure agent browsers can reach the ameyo host and ameyowebaccess endpoints over the required protocol and port provision matching users in ameyo and crm; userid must match if crm sso is required, and ameyo users must exist before attempting login from the toolbar add the integration script include the ameyo integration script on every crm page that will host the toolbar \<protocol> //\<domain of ameyo application> \<port number>/ameyowebaccess/toolbar/js/ameyo integration v\<file version> js as a script tag in the page head to enable two‑way messaging create the iframe container and inject the toolbar add a div with id ameyoiframediv to each crm page and inject an iframe whose src points to \<protocol> //\<domain of ameyo application> \<port number>/ameyowebaccess/toolbar crm htm?origin=\<crmorigin>, where crmorigin is computed from window\ location to scope cross‑window communication example snippet text\<script> var crmorigin; var ameyobaseurl = "\<protocol> //\<domain of ameyo application> \<port number>/"; function initialise(){ crmorigin = window\ location href; var iframediv = document getelementbyid("ameyoiframediv"); var iframeurl = ameyobaseurl + "ameyowebaccess/toolbar crm htm?origin=" + crmorigin; var iframehtml = '\<iframe height="400px" width="200px" id="ameyoiframe" src="' + iframeurl + '">\</iframe>'; iframediv innerhtml = iframehtml; } \</script> initialize handlers and load lifecycle use onloadhandler to verify the page and iframe are ready, and listen for loginstatushandler on each page open or refresh to reflect current session state in the crm shell if overriding screen pop, register your crm function with ameyo integration registercustomfunction("showcrm", { showcrm fn }) to take control of navigation and complete the pop using ameyo integration api setrecordinfoforshowcrm(requestid, …) after crm context has loaded choose and wire authentication for password login, call ameyo integration dologin(username, password, 'auth type password'); for crm sso, call ameyo integration dologin(username, password, 'auth type crm http') to trigger the crm authentication flow implement a post /login logout endpoint in the crm that accepts requestxml and returns \<status>, \<message>, and \<crmsessionid> on successful command=login, and that terminates the crm session when ameyo later calls command=logout sample json for sso login request and response structure with method = post & content type application/json {"password" "agent","userid" "agent","command" "login"} login request and response structure with method = post & content type application/x www form urlencoded request={"password" "admin","userid" "admin4","command" "login"} sso api response should be in below format with method = post & content type application/json {"status" "success","crmsessionid" "crm sess norah 123 434343","message" "message"} logout request and response structure response includes command=logout with crmsessionid, and status indicates success or failure for crm session termination method = post request { "command" "logout", "crmsessionid" "crm 1234 hjsdch" } response { "status" "success/failed", "message" "" } handle login state and force login react to loginhandler to display success, prompt for force login on session clash, or surface explicit failure reasons such as auth policy incorrect and username or password empty for user guidance when force login is required, call ameyo integration doforcelogin() from the crm to take over the prior session and continue the initialization auto‑select the agent’s extension implement a global getextensioninfo function that returns a json object { name '\<extension name>', phone '\<endpoint>' } so the toolbar auto‑binds the known device after login, and reflect the outcome via selectextensionhandler in the crm ui example function getextensioninfo(){ return { name 'sip 1001', phone '1001' }; } campaign selection and agent presence allow agents to select the target campaign and reflect that via selectcampaignhandler, then toggle availability with readyhandler or breakhandler to keep crm rosters and action controls in sync for preview or auto‑dial campaigns, also listen to autocallonhandler and autocalloffhandler to display current dialing mode in the crm header or status area screen pop flow for inbound and outbound define showcrm(phone, additionalparameters) in the crm to navigate to customer/case context for inbound acd, auto, manual, preview, callback, and click‑to‑dial scenarios, or override with registercustomfunction to centralize the pop logic across pages after rendering, call ameyo integration api setrecordinfoforshowcrm(requestid, requestid, phone, callback) to acknowledge completion and keep the toolbar and crm synchronized example pattern function customshowcrm(phone, params, requestid){ // resolve record, route crm ui, then acknowledge ameyo integration api setrecordinfoforshowcrm(requestid, requestid, phone, function(resp){ / log / }); } ameyo integration registercustomfunction("showcrm", { showcrm customshowcrm }); click‑to‑dial from crm records initiate calls using ameyo integration dodial(phone, customerid, additionalparameters) from record pages to pass context for routing and analytics, or prefill the dial box with ameyo integration populatenumberindialbox(phone) when agent confirmation is required example ameyo integration dodial('+14085551212', 'cust 567', { leadsource 'web' }); disposition and wrap‑up fetch two‑level dispositions with ameyo integration getdispositioncodes(campaignid?) and render crm dropdowns, then submit the agent’s selection with ameyo integration disposecallbydisposition(dispositioncode) and wait for handledisposecallbydispositioncode to confirm completion on errors like null crtobjectid or invalid codes, rely on handlefaileddispositionnotifygeneric to display validation feedback and keep the form open for correction dispose‑and‑dial use ameyo integration disposendial(dispositioncode, phone) to end the current call and immediately dial the next number, noting that the default release disallows the “callback” disposition in this path unless explicitly customized by professional services confirm both the disposition result and subsequent dial status via handledisposecallbydispositioncode to decide whether to advance the crm workflow or retry transfers and conferences log and visualize call routing by listening to transfertophonehandler, transfertoaqhandler, transfertouserhandler, transfertoivrhandler, transfertocampaignhandler and the conference counterparts, updating the crm timeline and participants accordingly use these events to annotate activity history, e g , “transfer to agent queue request sent,” and to keep ownership and queue metadata current on the crm record logout and session termination when crm signs out the agent, call ameyo integration dologout() to end the ameyo session; when the toolbar logs out, ameyo will call the crm’s /login logout with command=logout, which the crm must honor by terminating its session and cleaning up ui state display logouthandler results and remove any cached call context or disposition ui remnants to prevent accidental reuse on the next login error handling and diagnostics surface explicit login errors from loginhandler, including auth policy incorrect and username or password empty, and guide agents to retry or contact support, while handling invalid sessionid responses on logout gracefully for sso, display the \<status>failed\</status> and \<message> returned by the crm endpoint and avoid creating crm sessions or proceeding to extension binding until a success is received security and origin governance always include origin=\<crmorigin> in the iframe url and validate origin in custom message handlers to scope cross‑window communication to trusted pages only pass crmsessionid returned by the crm sso login in subsequent crm web requests where required by policy to preserve session integrity and auditability across interactions events and handlers name type when it fires payload typical crm use onloadhandler event when the current page fully loads, possibly multiple times due to redirects none initialize page state and verify toolbar iframe and messaging channel are ready loginhandler handler after a login attempt, including ui login, dologin, or auto‑relogin success status or force‑login required; on failure auth policy incorrect, username or password empty, unknown error occurred please refresh or retry reflect login result in crm header, prompt for force login if required, or display reason on failure loginstatushandler handler on open/refresh to communicate current session state; emitted once per load status show “logged in/out” banner or auto‑resume ui based on status forceloginhandler handler when a session is created forcefully because the same user was already logged in status forceloginrequired + responsetext ask agent to confirm takeover and then invoke doforcelogin from crm logouthandler handler when the server deletes the session due to user logout, supervisor action, or timeout onsuccess success; onfailure invalid sessionid end crm session and redirect to login; clear cached call context showcrm event on inbound, auto, manual, preview, callback, and click‑to‑dial to drive crm navigation currentphone, requested, additionalparameters (e g , crm url or callid) open or focus the customer/case record and acknowledge via setrecordinfoforshowcrm selectextensionhandler handler after an agent selects an extension onsuccess success, usercustomercrtinfo; onexception responsetext detail, usercustomercrtinfo confirm device binding and show active endpoint in agent bar modifyextensionhandler handler after an agent modifies the extension onsuccess success, usercustomercrtinfo; onexception responsetext detail, usercustomercrtinfo update device label and re‑validate reachability before next call selectcampaignhandler handler after an agent selects a campaign campaignnamewithid switch crm disposition set and list views to the selected campaign autocallonhandler handler when agent enables auto‑dial onsuccess success indicate predictive/progressive mode in crm status area autocalloffhandler handler when agent disables auto‑dial onsuccess success revert crm status to manual dialing mode readyhandler handler when agent sets presence to ready status available mark agent as available in crm roster and enable click‑to‑dial controls breakhandler handler when agent sets a break state status training, snacks, lunch, or unavailable show break reason in crm roster and disable outbound actions hanguphandler handler when an agent ends a call onsuccess success, usercustomercrtinfo trigger wrap‑up timer and show disposition form in crm transfertophonehandler handler when an agent transfers to another phone transfer to phone request sent, usercustomercrtinfo append transfer event to interaction timeline and update call party list transferincallhandler handler when an agent transfers to an in‑call party transfer to phone incall request sent, usercustomercrtinfo log warm transfer intent and hold state transitions in crm transfertoaqhandler handler when an agent transfers to an agent queue transfer to agent queue request sent, usercustomercrtinfo record queue transfer and show downstream queue/campaign in activity log transfertoivrhandler handler when an agent transfers to ivr transfer to ivr request sent, usercustomercrtinfo log ivr transfer and display self‑service path if applicable transfertouserhandler handler when an agent transfers to another user transfer to user request sent, usercustomercrtinfo show receiving user and update ownership on the crm record transfertocampaignhandler handler when an agent transfers to a campaign transfer to campaign request sent, usercustomercrtinfo track campaign reassignment in the case history conferwithphonehandler handler when an agent starts a conference with a phone confer phone request sent, usercustomercrtinfo add conference participant and mark three‑way call in ui conferwithtpvhandler handler when an agent starts a conference with tpv confer with tpv request sent, usercustomercrtinfo note tpv involvement and flag compliance workflow in crm conferwithuserhandler handler when an agent starts a conference with another user confer with user request sent, usercustomercrtinfo add internal participant and show consult state conferwithlocalivrhandler handler when an agent starts a conference with local ivr confer with local ivr request sent, usercustomercrtinfo indicate ivr assist and capture prompt path if exposed handledispositioncodes handler after requesting disposition codes array/list of disposition classes and codes populate crm wrap‑up dropdowns with two‑level options handledisposecallbydispositioncode handler after attempting to dispose a call or dispose‑and‑dial status for disposition result and, for disposendial, subsequent dial status confirm save, close wrap‑up modal, or show retry on failure handlefaileddispositionnotifygeneric handler on disposition exceptions such as null crtobjectid or invalid code reason string describing failure display validation error and keep wrap‑up form open for correction prerequisites licensing this is a licensable feature professional services requires enablement and deployment from professional services and support crm compatibility the third party crm must be web based and capable of embedding external content within an iframe user mapping user ids must be consistent between the ameyo system and the crm for single sign on use cases unified agent experience integrating the toolbar into the crm for sales or support workflows to eliminate context switching optimized sales dialing utilizing the click to dial function directly from a lead list in the crm automated customer context using the screen pop event to automatically display the customer's service ticket or history upon an incoming call session integrity leveraging the forceloginhandler and logouthandler to ensure sessions are correctly terminated in both ameyo and the crm to prevent unauthorized access