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 integration reverses the traditional toolbar setup instead of the exotel toolbar being embedded in the crm, the crm application is loaded inside an iframe within the ameyo ecc agent desktop this approach allows the crm to be contextually displayed based on the agent's actions (e g , an incoming call) and receive/send real time data using the omni sdk's established api and event framework key structural components iframe integration the ameyo ecc loads the crm's configured url into a dedicated iframe element on the agent interface the crm application must be engineered to function correctly within this embedded context data transmission via url initial context setting data (e g , interaction ids, customer identifiers, call types) is typically passed from ameyo to the crm via get request parameters appended to the configured url the crm application must be able to parse and utilize these parameters upon loading communication layer (omni sdk) once loaded, the crm page initializes the omni sdk within the iframe to establish the two way communication bridge needed for real time events (like interactionconnected) and api calls (like disposeinteraction) 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) crm url type purpose placeholder parameters (passed via url) incoming/connected call customer url loads the crm to perform a screen pop and display the customer's record when a call arrives or connects ?customerid=\[customer id], interactionid=\[interaction id], calldirection=\[direction] preview dialing preview url loads the crm to display customer information before the call is initiated, typically in a manual dialing scenario ?customerid=\[customer id], listid=\[list id], previewrecordid=\[record id] call end/wrap up dispose url loads the crm with call disposition information, allowing the agent to capture wrap up data and finalize the interaction ?interactionid=\[interaction id], callduration=\[duration], userid=\[agent id] 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 //gateway engg preprod cc exotel com/omniapp/sdk/ameyo sdk js ") then((module) => { const sdk = module default; const sdkconfig = { context "app", origin " 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)); additional voice apis (cti toolbar / crm actions) this section documents additional voice apis required for advanced cti toolbar capabilities and crm driven call actions these endpoints enable direct control over call initiation, disposition, and post call data retrieval from external systems 1\ 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" }' 2\ 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' \\ \ header 'cookie metadata =e3a3f5a5 71fd 407f 91d7 6556534ead65' \\ \ 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" "" }' 3\ 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" "" }'