Using the Connect API for PopFlow BUI

Learn about how to use the Connect API for PopFlow BUI

Last published on: May 4th, 2022

Introduction


The OpenMethods Connect API allows for the triggering of Interaction Workflows (screen pops) within the CRM, and for the passing of interaction-specific data into the CRM for further processing and automation. Triggering events, and their associated data can originate from a variety of sources to include agent softphones, telephony platforms (both on-premise or cloud-based) and/or any other source capable of generating the necessary API call. Once triggered, the OpenMethods solution handles the appropriate integrations in the CRM to accomplish the prescribed Interaction Workflows.



Payload Components

To trigger PopFlow using the OM Connect API, several components must be sent to the API:

  • agentId (string | required) - This is the unique telephony identifier of the agent (example: Agent ID). It is case sensitive.
  • jwt (string | required) - This is the JWT API key that gives access to the service.
  • crmId (string | required) - This is the CRM's instance name.
  • event (string | required) - This is the event where the published Interaction Workflow to be executed exists. This is case sensitive and must match the event name exactly.
  • (optional) Any additional properties will be viewed as interaction data.


Getting Started

Obtaining an API Key

In order to trigger PopFlow via the OM Connect API you must include, with the trigger, an API key. To get this key login to your OpenMethods account. You must be an administrator of your deployment to access this section.

Shell
https://your-company-name.openmethodscloud.com


On the left navigation pane, look for the API Key section.


Delete

Obtaining Your CRM ID

In order to trigger PopFlow via the OM Connect API you must also include, with the trigger, your CRM ID. To obtain the CRM ID, login to your Oracle Service Cloud or Oracle B2B instance and look at the URL for the instance. The CRM ID will be the domain of the instance.

In this example the CRM ID will be:  pts-isvup162-openm.rightnowdemo.com

Delete

Obtaining Event Name

In order to trigger a published Interaction Workflow, you must know the “Event” that will be used to trigger the Workflow (i.e. “On Ring, On Answer etc). To identify which Event the Interaction Workflow is associated to, login to your OpenMethods account. You must be an administrator of your deployment to access this section. 

From the Experience Designer, select the Instance where the Interaction Workflow is located

Find the Event of the published Interaction Workflow and copy the name exactly (case and length sensitive).

Delete


Triggers

Telephony/CTI Triggers

Telephony or CTI platforms can be used to trigger PopFlow Interaction Workflows based upon events that are happening on the agent's telephone, soft-phone or desktop application. For example, Interaction Workflows can be triggered "On Ring" or "On Answer". These trigger events can easily be sent to PopFlow, via the OM Connect API, provided that the telephony provider has the ability to call a URL when any of those events happen.


Base URL for CTI

https://connect.openmethods.com/api/sendmessage/CTI
Delete

CRM Triggers


CRM-based triggers allow administrators to trigger PopFlow Interaction Workflows from within a CRM Workspace or web page. For example, CRM administrators can place buttons on a workspace or web page to trigger PopFlow to lookup data in an external system or trigger an outbound SMS message to be sent.

Base URL for CRM Trigger

https://connect.openmethods.com/api/sendmessage/CRM
Delete


HTTP Requests


OpenMethods recommends using Postman for ease of use in formatting and testing Interaction Workflow triggers, but feel free to use any application you like. (https://www.getpostman.com/)

The following examples use Postman.

POST Requests

Set up the post URL (based on the type of trigger from above) : example:  https://connect.openmethods.com/api/sendmessage/CRM

Then set up the body, making sure that the Content-Type is set to application/json.

Finally, add the required body fields and any additional data desired for use in the Interaction Workflow. In the example below, “insert_prop_1” through “insert_prop_3” is Key-Value Pairs (KVP) containing the additional interaction data desired to be sent with the triggering event.

An Example Body message for a POST:

JSON
{
    "agentid": "insert_agentId",
    "jwt": "insert_api_key",
    "crmid": "insert_crmid",
    "event": "insert_event_name",
    "insert_prop_1": "insert_prop_1_value",
    "insert_prop_2": "insert_prop_2_value",
    "insert_prop_3": "insert_prop_3_value",
}
Delete

Send CTI messages with CtiId in the payload

https://connect.openmethods.com/api/sendmessage/CTI

"ctiid" is optional. (and it is case insensitive). If it is present, it is added to the topic when publish.

Client apps should subscribe to two Topics. one with CtiId and another without CtiId.

CTI/<CustomerID>/<CtiId>/<AgentId>
JSON
{
"agentid": "insert_agentId",
    "jwt": "insert_api_key",
    "ctiId": "insert_environmentId_From_ConfigServer",
    "event": "insert_event_name",
    "insert_prop_1": "insert_prop_1_value",
    "insert_prop_2": "insert_prop_2_value",
    "insert_prop_3": "insert_prop_3_value",
}
Delete

GET Requests

Set up the base URL

Text
https://connect.openmethods.com/api/sendmessage/CRM

Now add each required query parameter

Text
?agentid={insert_agentId}&jwt={insert_api_key}&crmid={insert_crmid}&event={name_of_event}

Finally, add any additional data need for Popflow workflow.

Text
&prop1={insert_prop1}&prop2={insert_prop2}

All together the request will look like this:

Text
https://connect.openmethods.com/api/sendmessage/CRM?agentid={insert_agentId}&jwt={insert_api_key}&crmid={insert_crmid}&event={name_of_event}&prop1={insert_prop1}&prop2={insert_prop2}
Delete


Troubleshooting

401
Please ensure that you have the correct API Key.

Event not being triggered
Please ensure the event name is typed correctly, both case and length (spaces included). Double-check that the intended Popflow to be triggered is published to the event that is being called.

Finally, if in Service Cloud CRM, ensure that the published profile matches the CRM user's profile.

Still, having trouble?
If issues are unresolvable, please contact OpenMethods Care for assistance.