Omni URL Based CRM integration Guide

19 min

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") .then((module) => { const sdk = module.default; const sdkConfig = { context: "app", origin: "https://<crmDomain>", 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

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.

Sample Manual Dial API

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.

Sample Dispose API

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.

Sample DisposeDial API

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": ""
}'