Omni URL Based CRM integration Guide

overview this document details the configuration and structural requirements for integrating a customer relationship management (crm) application as an embedded page within the exotel ameyo contact center (ecc) agent console, utilizing the omni sdk for communication introduction and integration approach url based app integration allows external web applications to be loaded directly inside an iframe within the ameyo ecc agent desktop 1\ query parameter integration (passive) this is the standard approach where ameyo ecc passes initial context (interaction ids, customer phone numbers, etc ) by appending get request parameters to the configured crm url best for simple screen pops and loading specific customer records based on call data limitation it is a "one way" push from ameyo to the crm at the moment the page loads 2\ omni sdk integration (active/two way) by injecting the omni sdk into the crm page, the embedded application moves beyond a static url load it establishes a real time, two way communication bridge between the ecc host and the crm iframe best for real time event handling (e g , updating the crm ui exactly when a call connects) and triggering ecc actions (e g , disposing a call or dialing a number) directly from crm buttons advantage unified behavior across all integration modes (toolbar, app, and iframe) key structural components iframe integration the ameyo ecc loads the crm's configured url into a dedicated iframe the crm must be configured to allow framing by the ameyo domain context via url (approach 1) ameyo sends metadata (e g , phone, interactionid) via url parameters the crm parses these to display relevant information communication layer (approach 2) the crm initializes the ameyo sdk js to listen for events and invoke methods, enabling a seamless "native" feel within the embedded console technical and security requirements the following requirements ensure seamless and secure integration of the third party crm application within the ecc requirement description impact on integration https support the crm application's url must be served over https (ssl/tls) ensures secure, encrypted communication between the ecc host and the embedded crm iframe, preventing browser security errors (mixed content) and protecting sensitive data iframe compatibility the crm page must not use security headers like x frame options sameorigin or content security policy frame ancestors 'self' that prevent it from being loaded in an iframe by a different domain (ameyo ecc) essential for the crm to be successfully displayed within the ameyo agent console cross domain communication the ameyo omni sdk is built on a post message architecture, which natively handles communication across different domains (ameyo $\rightleftarrows$ crm iframe) this negates the need for the developer to implement custom cross origin messaging, relying solely on the sdk session management the crm must support one of the configured session management policies for the agent no authentication , cookie based (for persistence), or single sign on (sso) determines how the agent's session is maintained or established within the embedded crm once the page loads url formats and integration points ameyo configures specific urls in its backend to load the crm page at different points in the call lifecycle the crm must be prepared to handle the parameters passed to these urls integration point (ameyo trigger) purpose placeholder parameters (passed via url) knowledge base url loads a preconfigured knowledge base url to the embedded browser for agent reference at login, where the crm landing page is opened userid username sessionid usertype iframeid campaignid crmsessionid usercrtobjectids instanceid locale origin contactcenterid processid incoming/outgoing call loads the crm to perform a screen pop and display the customer's record when a call arrives or connects crm push generated time usercrtobjectid phone disabledispositiononactivecall campaignid associationtype crtobjectid sessionid userid isorignalphonerequiredincrm calltype displayphone instanceid session id locale origin interactionid iframeid contactcenterid omni sdk initialization and event registration since the crm page is the one loaded inside the iframe, it must perform the sdk initialization to establish the communication bridge the apis and events remain identical to the standard omni sdk (generic toolbar) integration sdk initialization the crm must initialize the sdk using the crm context once its page has fully loaded inside the ameyo iframe (function loadsdk() { //import url of the site where ameyo sdk js is hosted import(" https //\<yourdomain>/omniapp/sdk/ameyo sdk js https //\<yourdomainname>/omniapp/sdk/ameyo sdk js ") then((module) => { const sdk = module default; const sdkconfig = { context "app", origin " https //\<crmdomain> https //localhost 3000 ", instanceid "ameyoiframe" }; const ameyoomnisdk = sdk initialize(sdkconfig); // optional if you want to expose sdk object globally, by default it will be //available to use wherever you want to use it window\ ameyoomnisdk = ameyoomnisdk; }) catch((error) => { console error("error in loading omnisdk", error); }); })(); event registration (listening to ameyo) the crm registers listeners to receive real time updates from ameyo (the ecc) based on the agent's activity ameyoomnisdk interaction register("interactioninitiated", (data) => { console log("integration interactioninitiated event received", data); }) then(() => { console log( "integration successfully registered interactioninitiated event" ); }) catch((error) => { console error( "integration error in registering interactioninitiated event", error ); }); api calls (sending commands to ameyo) the crm uses api calls to instruct ameyo (the ecc) to perform actions like disposing of a call or making an outbound dial ameyoomnisdk configuration getdispositioncodeswithdispositionclass(172) then(res => console log("result", res)) catch(err => console error(err)); executing call actions sdk & rest api to trigger telephony actions like dialing or disposing of a call from within your crm, you have two powerful options the choice depends on whether you want to use our client side framework or direct http requests option 1 client side via omni sdk (recommended) the most seamless way to trigger actions is through the omni sdk this ensures that the agent desktop and the crm stay in perfect sync without manual state management capabilities dialing, disposing, transferring, and more documentation for a full list of methods and event listeners, please refer to the omni toolbar docid\ jthp6inxptrgrl2it yz3 option 2 server side via voice rest apis for advanced cti capabilities or scenarios where the crm backend needs to trigger actions, we provide a suite of voice rest apis these endpoints allow for direct control over the telephony layer note these apis require the sessionid and usercrtobjectid, which are provided to the crm via the initial url query parameters upon loading manual dial api initiates an outbound manual call directly from the agent desktop or cti toolbar endpoint method url post https //\<your ameyo domain>/ameyorestapi/voice/manualdial headers header required description authorization yes the one time / time based authentication token (basic or bearer) generated for the account sessionid yes the active agent session id obtained from the knowledge base query parameters content type yes application/json parameters field type required description sessionid string yes the authentication token (matches the authorization header) shouldaddcustomer boolean yes whether to auto create a customer record if one does not exist campaignid number yes the active agent campaign id obtained from the knowledge base query parameters requestid string yes a client generated unique uuid for idempotency usercrtobjectid string yes the active agent usercrt id obtained from the knowledge base query parameters searchable string yes the primary search key (usually the phone number) phone string yes the destination phone number to dial additionalparams object no custom metadata passed from the crm to the contact center application selectedsearchables array no list of selected searchables if applicable curl location 'https //\<your ameyo domain>/ameyorestapi/voice/manualdial' \\ \ header 'authorization basic c2fjaglex2fkcwl5x2f6dxjlonnhy2hpbl9hzg1pbl9henvyzq==' \\ \ header 'content type application/json' \\ \ header 'sessionid d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593' \\ \ data raw '{ "sessionid" "basic c2fjaglux2fkbwlux2f6dxjlonnhy2hpbl9hzg1pbl9henvyzq==", "shouldaddcustomer" false, "campaignid" 60, "requestid" "manual dialf09f77ef ce66 498a 9bf5 a160b7ad7f48", "usercrtobjectid" "d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593 uce harmony1ardfyxqm\@43", "searchable" "8447380993", "contextvscontextadditionaldata" {}, "additionalparams" {}, "selectedsearchables" \[], "phone" "8447380993" }' dispose call api disposes of an active call without initiating a subsequent action this endpoint is required for crm driven disposition flows endpoint method url post https //\<your ameyo domain>/ameyorestapi/voice/disposecall export to sheets headers header required description authorization yes the one time / time based authentication token (basic or bearer) generated for the account sessionid yes the active agent session id obtained from the knowledge base query parameters content type yes application/json parameters field type required description sessionid string yes the authentication token (matches the authorization header) campaignid number yes the active agent campaign id obtained from the crm url query parameters usercrtobjectid string yes the active agent usercrt id obtained from the crm urlquery parameters crtobjectid string yes the active crt id obtained from the crm url query parameters dispositioncodeid number yes the internal numeric id of the disposition code dispositionparams object no custom attributes associated with the disposition notes string no agent notes or comments regarding the call requestid string yes a client generated unique uuid for idempotency curl location 'https //\<your ameyo domain>/ameyorestapi/voice/disposecall' \\ \ header 'authorization basic c2fjaglux2f2bwl2x2f6drjlonnhy2hpbl9hzg1pbl9henvyzq==' \\ \ header 'content type application/json' \\ \ header 'sessionid d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593' \\ \ data raw '{ "sessionid" "basic c2fjaglux2fkbwlux2f6dxjlonnhy2hpbl9hzg1pbl9henvyzq==", "campaignid" 60, "usercrtobjectid" "d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593 uce harmony1ardfyxqm\@43", "crtobjectid" "d604 69202d07 vce 27", "dispositioncodeid" 11, "dispositionparams" {}, "requestid" "dispose call d0996013 d2a7 41d9 b157 58e254f6d5af", "notes" "" }' dispose and manual dial api disposes of the currently active call and immediately triggers a new manual dial request endpoint method url post https //\<your ameyo domain>/ameyorestapi/voice/disposeandmanualdial headers header required description authorization yes the one time / time based authentication token (basic or bearer) generated for the account sessionid yes the active agent session id obtained from the knowledge base query parameters content type yes application/json parameters field type required description campaigncontextid number yes the numeric id of the campaign associated with the call being disposed usercrtobjectid string yes the active agent usercrt id obtained from the crm urlquery parameters crtobjectid string yes the active crt id obtained from the crm url query parameters dispositioncode string yes the string label of the disposition (e g , "sale", "callback") phone string yes the next phone number to dial immediately customerid number no the active customer id obtained from the crm url query parameters (send 1 if unknown) notes string no agent notes requestid string yes a client generated unique uuid for idempotency additionalparams object no custom metadata dictionary curl location 'https //\<your ameyo domain>/ameyorestapi/voice/disposeandmanualdial' \\ \ header 'authorization c2fjaglux2fkbwlfx2f6fxjlon5hy2hpbl9hzg1pbl9henvyzq==' \\ \ header 'content type application/json' \\ \ header 'sessionid d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593 uce harmony1ardfyxqm\@43' \\ \ data raw '{ "campaigncontextid" 270, "usercrtobjectid" "d108 6955296d ses harmony1 appid app server fyymsb770c lv9tb0w5dvv0fmcqziou6pygn3y9xa3pitd613plhoq51ui1tvgkqxlyltcjyvxk1vc4o8y523rosdpim8qzutpjdibxbakyhotwdlozhx80hoptdiwj 593 uce harmony1ardfyxqm\@43 uce 7905690272\@2", "crtobjectid" "d604 69202d07 vce 22", "dispositioncode" "sale", "phone" "7905690272", "customerid" "43800317962753", "requestid" "15da9c76 4a95 44a2 9972 915b953eabc1", "additionalparams" null, "notes" "" }'