Custom CRM

The Custom CRM solution allows companies to take advantage of the Contact Center AI Platform (CCAI Platform) Portal when using a CRM that is not a current standard integration with CCAI Platform. Custom CRM configuration works when using a homegrown CRM or any non-standard CRM.

Agents handle calls and chats, and supervisors can monitor and pull reports using the CCAI Platform portal. All details about the call or chat session are stored in a session metadata file. This file can contain 20+ data points, including session information, transfers, handle duration, participants, diagnostic information, and much more. The session metadata file can be parsed and used for post-session analysis and tracking.

Session metadata and consumer-uploaded media files are pushed to an external storage service and agents are able to see consumer-uploaded media files directly in the Agent Adapter during the session.

Custom CRM solution is implemented with a combination of the following components. Some components may or may not apply to your configuration:

Generating the session metadata file for each call and chat session
Pushing metadata and media files to an external storage service
Generic API integration
Custom lookup URL
CRM record update by email
Account or case lookup from the Agent Adapter

Prerequisites

In order to use the Custom CRM feature, you must first set up external storage. Refer to External storage for custom CRM solutions for more information.

Session metadata

The session metadata file contains detailed information about the session. This is sent 15 mins after the session has completed. Refer to Session Metadata File for more information.

Custom CRM interaction and integration methods

	Generic API	Custom URL
Account lookup	Yes	Yes
Case lookup	Yes
Case update	Yes	No

Generic API

The Generic API integration method provides the ability to use the API of your Custom CRM to establish a two-way connection with CCAI Platform. This seamless method feels the same as the out of the box CRM integration experience. The Agent does not have to take an action to create a CRM record for call or chat sessions and depending on the unique API configuration. It can enable a seamless record lookup and record update.

Custom URL

The Custom Link option allows your agents to interact with your CRM by utilizing a custom link created for each session. Unlike the standard CRM integration and the Generic API experience, the Agent needs to take action for a CRM record to be created. In some cases this might be just launching a tab with the custom link from the session, and in other cases the Agent may need to manually create the record.

Custom lookup URL details and configuration

The basic functionality of the URL is to perform a CRM lookup, but depending on your CRM, more complex processes can be triggered based on the custom URL content. The URL for the custom CRM can be configured with variables containing session information and is accessible in the agent adapter during the session. Once the URL is accessed, it will trigger the custom CRM to perform a lookup. This CRM lookup is how agents can make use of a "ticket pop" for the active call or chat session. The custom link process solely relies upon the custom CRM's ability to process this link and modify or rewrite it if necessary.

The externally stored session metadata, call recordings, and other files won't be tied back to the CRM record unless the Email update method listed is also leveraged.

In this configuration, the Agent will log into the CCAI Platform Portal and log into their CRM on separate tabs. Calls and chats will be handled on the CCAI Platform tab, and ticket details will be accessed on a CRM tab.

For this configuration to work:

The Agent must be logged in to their CRM in their browser
The Agent must be logged into the CCAI Platform Portal in their browser
The custom lookup URL must be pre-configured
Your CRM needs to handle the custom URL to display relevant CRM record

Custom lookup URL behavior

CCAI Platform will only include parameters in the URL that are not empty.
CCAI Platform does not store the generated URL containing ANI/UID/Email in the CCAI Platform database once the session is finished.

Custom lookup URL configuration

Due to varying unique identifiers and CRM capabilities and behaviors, you will need to create 2 different URLs -- one for IVR/PSTN/SMS sessions and one for web and mobile SDK sessions. IVR/PSTN/SMS sessions will use ANI as the unique identifier whereas web and mobile SDK will likely use CUID and Email.

The following variables can be used to configure your lookup URL:

Variable	Values
`{ANI}`	Phone number
`{CUID}`	Custom User ID
`{EMAIL}`	Consumer email
`{MENU_PATH}`	The whole queue menu path. For example "Orders/Order confirmation/Order info".
`{MENU_ID}`	Menu ID
`{CHANNEL}`	- chat - voice_call
`{TYPE}`	For Calls - IncomingCall(app) - ScheduledCall(app) - IncomingCall(web) - ScheduledCall(web) - Outbound_Call - OutboundCall(api) - IncomingCall(api) - IVR_Call - IVRCall(app) - Voicemail For Chats - Mobile - Web - SMS

CCAI Platform portal configuration

Sign in to the CCAI Platform portal using an account with Admin role assigned.
Go to Settings > Developer Settings.
In the CRM section, select Custom CRM.
Under CRM lookup, enter your custom URLs.
Select the Phone Number Format to be used in CRM requests.
Click Save Changes.
If you have not already done so, configure your external storage service. For more information, see External Storage.

CRM record update by email

In configurations like the custom lookup URL, once a session has been completed, the session metadata needs to be updated in the CRM. With this feature, CCAI Platform can automatically send session data using email. Approximately 15 minutes after as a session ends, an email is sent to a configured location and the email content is used to update a record in your CRM. This feature can be configured globally and per-queue. Once the email is received, your CRM may be configured to update or create a new CRM record for the session.

Email details

Sent from no-reply@ccaiplatform.com
Contains:
- Subject line
- Body with the session metadata in JSON syntax
- Attachment in TXT format with chat transcript when applicable
The CCAI Platform will wait for 15 minutes after the session ends, then send the email.
Emails are sent for successfully finished sessions only. It is not sent for failed or abandoned sessions.

Global configuration

Sign in to the CCAI Platform portal using an account with Admin role assigned.
Go to Settings > Developer Settings.
In the CRM section ensure Custom CRM is selected.
Enable Send session outcome via Email.
Enter an email address where you would like the email to be sent.
Click Save Changes.

Per-queue configuration

Sign in to the CCAI Platform portal using an account with Admin role assigned.
Go to Settings > Queue and select any sub-queue.
Enable Send session outcome via Email.
Enter an email address where you would like the email to be sent.
Click Save Custom CRM setting.

Settings inheritance and overriding

Settings	Behavior
Global = NOT enabled Queue = NOT enabled	Don't send for all queues.
Global = NOT enabled Queue = Enabled	The queue setting (i.e., on/off state) overrides the global setting. Email is sent from a given queue to an email address defined in the queue setting.
Global = Enabled Queue = NOT enabled	The queue setting (email address, on/off state) inherits the global setting. Email is sent from a given queue to an email address defined in the global setting.
Global = Enabled Queue = Enabled	The queue setting (email address) overrides the global setting. Email is sent from a given queue to an email address defined in the queue setting. If the email address is empty, then email is not sent.

Agent experience

CRM record lookup

Sign in to the CCAI Platform portal using an account with the Agent role assigned.
Open the Call or Chat Adapter.
Use the Open in new browser window button to trigger the lookup.
Use the Copy link button to copy the lookup URL to clipboard.

Agent display

External storage for custom CRM solutions

External Storage for Custom Solutions enables the use of an external storage service to store and retrieve CCAI Platform session metadata, call recordings, chat transcripts, and consumer-uploaded media files. The files are stored outside of a CRM.

In order to configure External Storage, you must have:

A valid CCAI Platform account with Admin and Agent role assigned for configuration and testing
An external storage service

Folder structure

The following folder structure will be organized in your external storage in Folder Path:

ujet-chat-transcripts
ujet-media
ujet-metadata
ujet-voice-recordings
ujet-voicemails

File formats and naming conventions

The following file types can be pushed to the external storage service. Files are encrypted during transit using HTTPS:

File	Name
Call recordings	- call-{id}.mp3 - call-{id}.wav
Media files	- call-{id}-photo-{photo-id}.jpg - call-{id}-video-{video-id}.mp4 - chat-{id}-photo-{photo-id}.jpg - chat-{id}-video-{video-id}.mp4
Chat transcripts	- chat-{id}.txt
Session metadata	- call-{id}.json - chat-{id}.json

Agent and supervisor experience

During the call or chat session, photos and videos uploaded by the consumer using smart actions are displayed in the Agent Adapter.

If you are using the custom URL CRM interaction combined with the session metadata file email update method, agents and supervisors can access session information using your external server.

Configuring the external storage service

Complete these steps to configure your external storage:

Sign in to the CCAI Platform portal using an account with the Admin role assigned.
Go to Settings > Developer Settings.
On the Developer Settings page, navigate to the External Storage section.
Enable information storage outside CRM servers by toggling the switch to On, then select the types of files to be stored.
In the Server Setup section, select your storage type and complete the setup steps: SFTP server, Google Cloud bucket.

SFTP server

Enter the SFTP Host (URL or IP address.)
Enter the Port number.
Enter the SFTP Login User ID.
If the SFTP server requires a password for authentication, enter it in the Password field.
If the SFTP server requires a private key for authentication, select the SSH Private Key checkbox.
Enter (copy & paste) the SSH Private Key.
Enter the private key Passphrase. If the session information should be stored in a specific folder on the SFTP server, select the Folder Path checkbox and enter the SFTP folder path.
Click Save Changes.

Cloud Storage

Enter the destination Google Cloud Bucket Name.
Enter Google Cloud Client ID.
Enter the Google Cloud Client Secret.
If the session information should be stored in a specific folder in the Google Cloud bucket, select the Folder Path checkbox and enter the Google Cloud folder path.
Click Link & Save.

Testing the external storage configuration

For CRMs with existing standard integration:

Sign in to your CRM.
Sign in to CCAI Platform within the CRM using CCAI Platform credentials with an Agent role assigned.
Place a call or chat. The CRM record that is associated with the session is displayed.
When the session is finished, the transcript file should be uploaded within seconds.
Navigate to the external server storage folder directly and verify the file is available.

Sending session files to the CRM

When External Storage is enabled, the CRM Storage and External Storage URLs developer settings provides the ability to send session files and decide which source to use to display files in the Agent Adapter.

To view these settings External Storage must be enabled at Settings > Developer Settings > External Storage. Toggle the Enable information storage outside CRM servers to On.

CRM storage

Go to Settings > Developer Settings > External Storage > CRM Storage.
Check the box beside Also send session files to the CRM to send session files such as call recordings or chat transcripts to your CRM and to the configured external storage.
Click Save Changes.

If the checkbox is checked, then the recordings will be stored in both the CRM and the external storage.

External storage URLs

The External Storage URL is used in two places:

The Agent Adapter.
Reporting: displays the media URL in the report as well as in the menus such as Settings, Calls, Completed.

Go to Settings > Developer Settings > External Storage > External Storage URLs
Select the source CRM URLs or External Storage URLs to display files in the Agent Adapter.
Click Save Changes.

CRM storage

If the checkbox for CRM storage is unchecked, the recordings will be stored only in the external storage and a link to the CRM will be used.
If the checkbox is checked, then the recordings will be stored in both the CRM and the external storage.

External storage URLs

The URL is used in two places:

One is showing the media in the CCAI Platform adapter. The external storage or CRM.
The other one is in the report. We reveal the media URL in the reports as well as in the menus such as Settings, Calls, Completed.

Display Custom CRM in CCAI Platform portal

When using the Custom CRM integration with your own custom-built CRM, you can load your CRM on a dedicated page within the CCAI Platform Portal. Once enabled, the CRM tab in the CCAI Platform Portal loads and displays your custom-built CRM page. This can be configured in Developer Settings > CRM.

This capability allows agents to handle live support sessions using the CCAI Platform Call and Chat adapters while also working in your custom CRM. This includes reviewing automatically popped open account and record details and session specific files and data passed in from your mobile app or by consumers, all using the CCAI Platform portal.

Configure a custom CRM page

To configure a custom CRM page, follow these steps:

In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settings menu, click Menu.
In the CRM pane, click Custom CRM.
Click the Display CRM in CCAI Platform portal toggle to the on position.
Under Display URL, enter the URL for your custom CRM page, and then click Save.

Open Custom URL screen pop

Use Open Custom URL to bring up a custom URL screen pop when a contact isn't found in the system. Create a CRM record with a temporary account ID, and trigger a custom link with parameters based on the queue level configuration.

Enable screen pop on a per queue basis

Go to Settings > Queue > IVR, click a queue to edit.
Go to Open Custom URL in the panel.
Enter a URL to bring up a screen pop.

Include the variable parameters {ACCOUNT_ID} and {PHONE_NUMBER} into the URL.

An example is provided.

Click Save.

Custom CRM generic API integration

The generic API integration method provides the ability to use the API of your CRM to establish a two-way connection with CCAI Platform. This seamless method has the same feel as the out-of-the-box CRM integration experience.

The Agent does not have to take any action to create a CRM record for call or chat sessions. Depending on the unique API configuration, it can enable a seamless record lookup and record update.

Terminology

Term	Description
Account	It is used to refer to the Account/Contact/Customer/Lead entity in the CRM. Your CRM may have another name for this entity. Accounts contain Records.
Record	It is used to refer to the Case/Ticket/Conversation/Incident entity in the CRM. Your CRM may have another name for this entity. Records belong to Accounts.
Comment	It is used to refer to the Comment/Note entity in the CRM. Your CRM may have another name for this entity. Comments belong to Records.

API settings

This section outlines the settings specific to the custom CRM API settings.

Authentication method

CCAI Platform supports three authentication methods for your CRM:

Basic authentication: Configure authentication credentials that include Username and password.
Custom header: Configure custom header key-value pairs: Field Key and Field Value. Enter as many pairs as you need.
OAuth: CCAI Platform supports the industry-standard protocol for authorization OAuth 2.0. Specify OAuth information if you need to enable the "Include the Redirect URL as part of the Authorization URL and Token URL" option.

Configure the following values:
- Authorization URL (required)
- Token URL (required)
- Client ID (required)
- Client Secret (required)
- Scope
- State
- Access Type

Phone number format

Select the Phone Number Format to be used in CRM requests:

Automatic: Create: +1 222 333 4444, Search: *222*333*4444
E.164: +12223334444
US Local: 2223334444
US local standard: (111) 222-3333
International: +1 222 333 4444

API request timeout

Configure the API Request Timeout from 1-10 seconds using the drop-down. This timeout will be applied to all endpoints you configure.

CRM lookup URLs

Specify lookup URLs that will be used to point an Agent to the current account and record.

Enter lookup URLs as they appear in your CRM when you have an account or record page opened in your browser.

You can also use CRM lookup URLs with the web SDK and mobile SDKs. You can configure the SDKs to look up CRM account and record information to display in the agent adapter. For a complete list of CRM lookup URLs, see Request URL parameters.

Account lookup URL

Use the {ACCOUNT_ID} variable to insert the actual account ID.

Example:

https://www.example.com/contact/{ACCOUNT_ID}

Record lookup URL

Use the {RECORD_ID} variable to insert the actual record ID.

Example:

https://www.example.com/record/{RECORD_ID}

API endpoints

This is the most important configuration for Generic API.

To make account lookup available to your agents, you have to configure the Find an account and Create an account endpoints.
Additionally, you can set up Find a record and Create a record endpoints to enable record lookup or creation to your agents. Account setup from the previous step is required for this.
Finally, if you enter Update a record, Upload a file, and Comment endpoints, it will enable record updates. Record setup from the previous step is required for this.

Endpoint configuration

Configure the following settings:

Request URL: API endpoint URL.
Choose the request method from POST, GET, PUT, or PATCH.
Specify the request Parameters. You can use the CCAI Platform defined variables to pass the required information (see the table below). Also, you can enter plain text or numbers as parameters' values. You can add as many parameters as you need.
If the endpoint is POST/PUT/PATCH, CCAI Platform offers more fine-tuned controls on how the request is built. Choose Request Data Format from Property or Container. It specifies the format of the request JSON.
- Property. This indicates that the request object is a basic property map when CCAI Platform builds the request body from parameters.
- Container. This indicates the request object data to be sent needs to be nested within a structure. Choose Container Type from Map or Array. Enter Container Name. It is used as the parent object name when building the request body from parameters.
  - Example: Map: { container_name : { ...parameters } }
  - Example: Array: {container_name : [ { ...parameters } ] }
Enter Response Data Location. It is used to locate the target response object in the JSON response.

Request URL Parameters

Parameter	Variable	Comment
Agent ID	`{AGENT_ID}`	The internal agent ID.
Agent Custom ID	`{AGENT_CUSTOM_ID}`	Optional field from the user's profile.
Agent Email	`{AGENT_EMAIL}`	The answering agent's email if applicable.
Name of end-user	`{NAME}`
End user first name	`{FIRST_NAME}`	Taken from `Name`
End user last name	`{LAST_NAME}`	Taken from `Name`, defaults to -- if missing.
External ID	`{UJET_ID}`	CCAI Platform end-user ID
Email	`{EMAIL}`
Call Type/Session Type	`{SESSION_TYPE}`
End user phone number	`{PHONE_NUMBER}`	Formatted using setting choice
Call ID	`{Call_ID}`	CCAI Platform call ID.
Chat ID	`{Chat_ID}`	CCAI Platform chat ID.
Language	`{LANG}`
Custom UID	`{CUSTOM_USER_ID}`	For Mobile: this is the left-hand side of the email. For example, `test.user3` from `test.user3@test.co`
Account ID	`{ACCOUNT_ID}`	Found by calling Find/Create contact endpoint.
Record ID	`{RECORD_ID}`	Found by calling Find/Create record endpoint.
Session ID	`{SESSION_ID}`	CCAI Platform session ID
Menu path	`{MENU_PATH}`
Outbound phone number	`{OUTBOUND_PHONE_NUMBER}`	Formatted using setting choice
Queue name	`{QUEUE_NAME}`
Queue ID	`{QUEUE_ID}`	The internal queue ID.
SmartAction session id	`{SMART_ACTION_SESSION_ID}`
SmartAction: verification		(Coming soon)
SmartAction: text input		(Coming soon)
Rating	`{RATING}`	Only available if a user left it
Feedback message	`{FEEDBACK}`	Only available if a user left it
Call duration	`{CALL_DURATION}`	In mm:ss
Hold time	`{HOLD_TIME}`	In mm:ss
Wait time	`{WAIT_TIME}`	In mm:ss
After call work duration		(Coming soon)
Device Type	`{DEVICE_TYPE}`
Disconnected By	`{DISCONNECTED_BY}`
Channel	`{CHANNEL}`
Record Subject	`{TICKET_SUBJECT}`	Used as record title
Record Description	`{TICKET_DESCRIPTION}`
Record Description HTML	`{TICKET_DESCRIPTION_HTML}`	Same as description just formatted for html
Comment Body	`{COMMENT_BODY}`	Only available in add comment situation (save rating, end call/chat, call/chat started)
File Data	`{FILE_DATA}`	Only available in the upload file endpoint, but contains the base64 or data for multipart form.

Request URL Parameter Functions

Functions are provided to help with dynamic CCAI Platform variables. These functions are only available for use in the Request Parameter section of the endpoint settings.

The resulting value created from a function will be a string. If no values are returned from the function, the parameter is removed from the parameters list in the request before execution.

Function	Function Syntax	Description
Default Value	`=DEFAULT_VALUE(val1, val2)`	Value will use `val1` unless null or empty, and default back to `val2`.
Concatenation `Or`	`=CONCAT_OR(val1, val2, val3)`	Concatenation of multiple values with `or`. Example: 'val1 or val2 or val3'
Concatenation `And`	`=CONCAT_AND(val1, val2, val3)`	Concatenation of multiple values with `and`. Example: 'val1 and val2 and val3'

Examples

The following a some examples of use of the request URL parameter function.

Default

The following example uses DEFAULT_VALUE in the Create a Record Endpoint. The key and value for agent setup use the default function to have a fallback in case of an empty value for an agent email. Agent email may be empty on record creation for a few reasons: a customer may have ended the IVR call before an assigned agent answers the incoming call, or in the case of chats, a record will be created before an agent answers. In this way, required parameters might be defaulted to safe values until later updates or set in cases of abandoned calls.

Concatenation

The following example uses CONCAT_OR in the Find an Account by Query endpoint. This example is specific to Zoho CRM, but shows how CONCAT_OR can be used. CONCAT_AND follows the same rules instead connecting values with and instead of or. Refer to the following cases for values present in the endpoint at the time of execution and the resulting value passed as the request parameter.

Keys present	Resulting value
`ACCOUNT_ID`	`(Id:equals:<uuid>)`
`ACCOUNT_ID`, `EMAIL`	`(Id:equals:<uuid>)` or `(Email:equals:james.bond@007)`
`PHONE_NUMBER`, `EMAIL`	`(Phone:equals:+12223334444)` or `(Email:equals:james.bond@007)`

API account

The API account endpoints support the integration with accounts in the CRM.

Calls to endpoints that return a 400 error retry. Calls that return other errors don't retry. Retries continue for a week, decreasing with an exponential ramp down. For information about API flows, see Custom CRM generic API: Flows.

Find an account by query endpoint (formerly find an account endpoint)

This endpoint is used to find an account by phone number, email, or internal CRM ID. This is the default endpoint used for finding an account.

Example response:

{
  "id": 123,
  "name": "James Bond",
  "phone": "11234567890",
  "email": "james.bond@agents.co"
}

Find an account by ID endpoint

This endpoint is used to find an account by ID. Generally, this ID will be part of the URL. URL validation will also account for if the URL is not formed with the ID, then this endpoint won't be used. This will follow REST standards. If a 404 is returned on failed lookup, find by query will be next.

Example response:

{
  "id": 123,
  "name": "James Bond",
  "phone": "11234567890",
  "email": "james.bond@agents.co"
}

Create an account endpoint

This endpoint is used to create an account if we haven't found one. Most CRMs require records to be attached to accounts. To create a unified flow, we enforce this requirement for all CRMs.

API record

The API record endpoints provide the ability to integrate with records or cases in your CRM.

Find a record by query (formerly find a record endpoint)

This endpoint is used to find a record by a criteria. Generally, this is used to find associated records to an account. If the CCAI Platform is configured to re-use existing records, then the found record will be used. This is the default endpoint used for finding a record.

Example response:

{
  "id": 456,
  "subject": "Record title",
  "status": "open", // enumerated status open/closed, or 1,2,3
  "contactId": 123, // contact attached to ticket
  "phone": "11234567890", // contact phone
}

Create a record endpoint

This endpoint is used to create a record. A new record is created if a record is not found from the Find a record request or if CCAI Platform is configured not to re-use existing records.

Example request:

{
  "id": 123,
  "subject": "Record title", 
  "description": "A longer description of the record, can be formatted in html",
  "phone": "11234567890", // can be saved in multiple formats
  "contactId": 123,
  "sourceType": "PHONE", // PHONE/CHAT
  "menu": "queue1",
  "direction": "outgoing",
  "rating": 5, // 1-5 scale
  "feedback": "the agent was great!" // description of rating
}

Update a record endpoint

This endpoint is used to update a record. It updates the record's title and description. This endpoint also optionally works to update the record according to CCAI Platform events, such as save CSAT rating, call or chat finish events, selected queues, verifying users, and others.

Upload a file endpoint

This endpoint is used to upload an attachment.

Choose the Type for your upload endpoint

Base64 encoded form
Multipart form

Select which files to attach

Call recordings
Chat transcripts
Voicemails
Photos
Videos
Session metadata file

Choose Attachment Type from ID and Attachment URL. It specifies the format of the response JSON.

ID
Attachment ID. Enter the location of a parameter in JSON response for attachment's ID. This will be available for attachment builder URL as {ATTACHMENT_ID}.
Attachment Builder URL. Enter URL to download the file attachment. RECORD_ID and ATTACHMENT_ID are available variables.

Example: https://www.example.com/Accounts/{RECORD_ID}/Attachments/{ATTACHMENT_ID}
Attachment URL

Enter the location of a parameter in JSON response for the file download URL.

Select the Add comment to CRM record checkbox if you want CCAI Platform to leave a comment to a record when a file was uploaded. The Text Format setting from the Comment endpoint will be respected for these comments.

The following example is a multipart form example using POST/PUT/PATCH:

{
  "file": <file data>
  "id": 123, // optional, this can also just be part of the URL;
             // for example https://example-customer.com/upload/record/{RECORD_ID}
}

Example response:

Example A: A download URL exists

{
  "id": 123,
  "url": "https://some-hosted-url.com"
}

Example B

In this case a download URL does not exist but there is a download attachment endpoint that uses this ID. For example, https://www.customer-api.com/record/{RECORD_ID}/Attachments/{ATTACHMENT_ID}.

{
  "id": 123
}

Comment endpoint

This endpoint is used to add a comment to a record. If the endpoint is configured, the CCAI Platform Platform will add comments to records with the events:

call or chat start
call or chat end
CSAT rating and comment
custom data package
transfer comments
disposition code and notes
survey questions and answers

Choose Text Format for comments. If the Convert text to HTML checkbox is checked, the text will be in HTML format or plain text otherwise.

Example request, POST/PUT/PATCH:

{
  "comment": "Some text",
 // string can also be formatted on ujet side as html
  "id": 123,
 // optional, this can also just be part of the URL;
 // for example https://example-customer.com/comment/record/{RECORD_ID}
}

Custom CRM generic API: Flows

This section provides flow charts for the custom CRM generic API flows.

Basic flow charts

Basic flow chart

Find or create account flow

Find or create record flow

Post call or chat actions flow

Update record flow

Comment flow

Upload file flow

Agent adapters

Custom CRM offers a generic method to integrate adapters (UI widgets) into CRM systems. The CRM system must be able to handle the way the adapters are activated and triggered within it.

In order to integrate user interface adapters, a CRM software or application is typically necessary. We already provide this capability for several CRM software such as Salesforce, Kustomer, Zendesk and others.

iFrame

Agent Adapters can be seamlessly integrated into a CRM or any other tool through the use of an iFrame tag. To learn more about the HTML iframe Tag see HTML iframe Tag.

However, the CRM needs to handle how the Adapters are presented to the user. For example it might feature UI buttons to allow for showing and hiding the Adapters. Furthermore, the Adapters can be designed to be draggable, allowing the Agent to reposition them on the screen at their convenience. The following examples demonstrate URL format.

Call adapter: https://tenant.loc.CCAI Platformlatform.com/agent/?type=call&from=custom

Chat adapter: https://tenant.loc.CCAI Platformlatform.com/agent/?type=chat&from=custom

iFrame template

Call Adapter: html <iframe src="https://tenant.loc.CCAI Platformlatform.com/agent/?type=call&from=custom" allow="microphone; camera; geolocation" width="290" height="600"></iframe>

Chat Adapter: html <iframe src="https://tenant.loc.CCAI Platformlatform.com/agent/?type=chat&from=custom" allow="microphone; camera; geolocation" width="450" height="590"></iframe>

URL Parameters

URL parameters can be used to provide additional information to the software, such as the type of interaction (call or chat), the source of the interaction (custom), and other relevant details.

If the tenant CRM setting is not available in the lists, the From parameter must always be set to Custom.

Type

Call
Chat

From

Custom (This must match with the tenant CRM setting). It must always be custom for any CRM other than in the lists. If there is no CRM setup, you can skip this parameter.

Events in agent adapters

Agent adapters post events that can be hooked into by the CRM system, which then processes updates to the CRM. To do this, the CRM needs to listen to the posts from the parent window and read the post data. Based on the data, it can trigger actions such as opening a ticket tab for a specific session ID.

Both the Call Adapter and Chat Adapter have specific events that can be utilized to enhance the CRM capabilities.

Call Adapter

New Call
End Call

Chat Adapter

New Chat
Active Chat
Chat Inbound Message
Chat Outbound Message
End Chat
Dismissed Chat

Both Adapters

Agent Login
Co-browse session started
Co-browse session remote control changed
Co-browse session full device changed
Co-browse session ended
Transfer
Add Party
Agent Connects to Session

Data for events

call_id: This is a unique identifier for a voice inbound call with IVR (Interactive Voice Response).
chat_id: This is a unique identifier for a messaging inbound call (web or mobile chat).
cobrowse_session_id: This is a unique identifier for a co-browse session. A co-browse session can be initiated in a call or chat session.
session_type: This is the type of session, such as voice, chat, or messaging.
va_data_parameters: Optional. All the variables configured in the queue to send to the Virtual Agent. This is only required for events involving the Virtual Agent.
session_variable: Optional. All the variables from the Virtual Agent that get sent to CCAI Platform in the payload.
custom_sip_headers: Optional. This enables custom SIP headers from incoming SIP calls to appear in the POST event log. It is only required if custom SIP headers are used.
custom_data_secured: Optional. Contains signed, custom data from your server.
custom_data_not_secured: Optional. Contains unsigned, custom data from your web page. For more information, see Chat unsigned custom data.

Agent IDs

agent_id: This is a unique identifier for an agent.
- from_agent_id: Used when routing calls or chats from one agent to another, to indicate the originating agent.
- to_agent_id: Used when routing calls or chats from one agent to another, to indicate the destination agent.
agent_custom_id: Optional. This is an agent ID from the user profile, if it has been entered in the profile.
- from_agent_custom_id: Used when routing calls or chats from one agent to another, to indicate the originating agent.
- to_agent_custom_id: Used when routing calls or chats from one agent to another, to indicate the destination agent.
agent_email: This is the email address of the agent.
- from_agent_email: Used when routing calls or chats from one agent to another, to indicate the originating agent.
- to_agent_email: Used when routing calls or chats from one agent to another, to indicate the destination agent.

Virtual Agent IDs

virtual_agent_id: This is the ID number assigned to a specific Virtual Agent.

Queue IDs

queue_id: This is the unique identifier for a CCAI Platform queue, and only exists when the call originates from a queue.
- from_queue_id: Used when routing calls or chats from one queue to another, to indicate the originating queue.
- to_queue_id: Used when routing calls or chats from one queue to another, to indicate the destination queue.
queue_path: This is the path for a CCAI Platform queue, and only exists when the call originates from a queue.
- from_queue_path: Used when routing calls or chats from one queue to another, to indicate the originating queue.
- to_queue_path: Used when routing calls or chats from one queue to another, to indicate the destination queue.

Campaign ID

campaign_id: A CCAI Platform campaign ID (only exists when the call type is a campaign call).
campaign_name: A CCAI Platform campaign name (only exists when the call type is a campaign call).

Message

message: Event indicating a new consumer message was received, plus message content.

Session Types

session_type: A CCAI Platform session type. The following section details the session or interaction types.
cobrowse_session_remote_control: Indicates the status of a requested remote control co-browse session. Values: off, requested, rejected, on.
cobrowse_session_full_device: Indicates the status of a full device co-browse session. Values: off, requested, rejected, on.

Participants

type: Participant type - end_user; agent; (from participants.type of /api/v1/calls or /api/v1/chats response).
cobrowse_session_requested_by: Indicates who initiated a co-browse session. Values: agent, end_user.
cobrowse_session_ended_by: Indicates who ended a co-browse session. Values: agent, end_user, api.
end_user_id: participants.end_user_id of /api/v1/calls or /api/v1/chats response. This field is only present if type: end_user.

Interaction / Session Types

Call Types

Voice Inbound: Standard PSTN calls.
Voice Inbound (IVR using Mobile): Fallback PSTN calls made from the Mobile SDK.
Voice Inbound (Mobile): Placed by consumers using an installed Mobile SDK.
Voice Callback (Web): Initiated from the Web SDK.
Voice Inbound (API): Initiated using API.
Voice Scheduled (Mobile): Scheduled using an installed Mobile SDK.
Voice Scheduled (Web): Scheduled using an installed Web SDK.
Voice Outbound: Initiated by an Agent by dialing a number.
Voice Outbound (API): Initiated using API.
Voice Campaign: Initiated using an Outbound Dialer (Campaign).

Chat Types

Messaging (Whatsapp): Initiated using Whatsapp.
Messaging Inbound (SMS)
Messaging Outbound (SMS)
Messaging Outbound (SMS using API)
Messaging (Web): Initiated using an installed Web SDK.
Messaging (Mobile): Initiated using an installed Mobile SDK.

Call or Chat Type

Co-browse Session: Initiated by an agent or end-user during a call or a chat.

Event types

Here are the event types that are posted by the agent adapter:

Agent login
New call
End call
New chat
Active chat
Dismissed chat
Co-browse session started
Co-browse session remote control changed
Co-browse session full device changed
Co-browse session ended
Agent assist started

An agent login event occurs when the agent logs into the adapter.

Here's an example of a JSON object for an agent login event:

{
  "type": "Agent_Login",
    "data": {
    "agent_id": 1,
    "agent_custom_id": "007",
    "agent_email": "james.bond@agents.co",
  }
}