Connect API

Discover how to easily integrate a Connect API into your website allowing for seamless user experience.

Last published at: December 6th, 2023

New Updates In Progress!

Updates to Connect API documentation are coming soon. 

  • New JSON responses
  • New API Endpoints
 

 

 

We've made some updates to our Connect API Endpoints. Please review the following information before going further!

 

Using "connect.openmethods.com" in PopFlow❓

Yes ⛔️

 

No ✅

 

I Don't Know❓

 
 

 

⛔️ You are accessing a legacy end of life URL 

Please follow the advice/steps below and review the connect.openmethods.com EOL announcement.

 

 

1. Please update and remove any reference of: 

connect.openmethods.com

and replace with the following URL:

connect.openmethodscloud.com

 

2. These updates should be made to any/all PopFlow's which reference the legacy URL.

 

3. ⚠️ Requirement: Re-Generate a new API Token:

Login to Experience Cloud.

Expand Navigation Menu and Click "System Settings" 

  • Select "API Key" from Menu
  • Click "Re-generate"
  • Copy New Key
  • Update any references of the old key with newly re-generated key.
 

 

🎉 Congrats! ✅

 

You are using the latest URL and API Endpoint. You do not need to change anything, please continue!

 

 

Warning: Please Verify URL

Please investigate your current PopFlows for the following and review the connect.openmethods.com EOL announcement.

 

 

Look for and remove any reference of the following URL. 

Note: The URL could be used in multiple areas of your PopFlows. If you need further assistance and help, please contact support.

connect.openmethods.com

and replace with the following URL:

connect.openmethodscloud.com

 

If you are using the URL "connect.openmethods.com" please go back and answer "Yes" to this question.

 
 

 

 

 

The OM Connect API is used for notifying connected clients with real-time events. The API messages POST and GET payloads to the Messaging Server to invoke PopFlow Events.

Get vs POST

POST should be used if the integrated platform supports it as it provides enhanced security compared to GET.

 

 

 

URL

 

CRM connection

If you want to send an OM Connect event to an agent that is NOT logged into the CTI platform but the Client has loaded and you have the CRM ID, then use the following URL.

  • https://connect.openmethodscloud.com/api/sendmessage/CRM
 

CTI connection

If you want to send an OM Connect event to a logged in CTI agent, then use the following URL

  • https://connect.openmethodscloud.com/api/sendmessage/v1/CTI

 

Using this url will return JSON response message for success with status code 200 as:

{
    "result": "Success",
    "message": "OK"
}

 

If you want to send an OM Connect event to a logged-in CTI agent, then use the following URL

  • https://connect.openmethodscloud.com/api/sendmessage/CTI

 

Using this URL will return string response message for success with status code 200 as:

"Result:OK"

 

If you want to send an OM Connect event to a logged-in CTI agent and you are invoking this by opening a browser window. and the browser has to be closed automatically.

  • https://connect.openmethodscloud.com/api/sendmessage/bc/CTI

 

Both Get and Post methods are supported. For successful results, the browser will be closed in 100 milliseconds.

 

Response message:

<body> Result:OK <br>This Browser will close in a second... </body>

<script type='text/javascript'>

setTimeout(function(){window.open('','_parent',''); window.close(); }, 100);

</script>

 

 

For failure results, the error message will be displayed in the browser for 2 seconds and the browser will be closed.

 

Response message:

<body> Error Message : <b></b> : IDX12729: Unable to decode the header '[PII is hidden]' as Base64Url encoded string.
jwtEncodedString: '[PII is hidden]'. <br>This Browser will close in 2 seconds... </body>
<script type='text/javascript'>
setTimeout(function(){window.open('','_parent',''); window.close(); }, 2000);
</script>

 

 

 

Authentication

You will need a few pieces of information in order to authenticate:

  • JWT Key
  • CRM ID
  • Event Name

 

JWT Key

⚠️ Requirement: Copy the API Token or Re-Generate a new token if applicable.

Login to Experience Cloud.

Expand Navigation Menu and Click "System Settings" 

  • Select "API Key" from Menu
  • Click “Re-generate”
  • Copy New Key
  • Update any references of the old key with newly re-generated key.

 

CRM ID

In Service Cloud or Fusion, the CRM ID is the domain:

 

Event Name

In order to trigger the published PopFlow, we must get the event it belongs to. 

  1. Login to Popflow and navigate to the Instance
  2. Find the event of the published PopFlow and copy the name exactly (case and length sensitive).

 

Parameters

 

CRM

Parameter Description Data Type Required?
agentId CRM's login user name. Make sure the characters are all in lower case. String Y
jwt JWT API key that gives access to the service. String Y
crmId CRM instance name String Y
event Event where the published PopFlow to be executed exists. This is case sensitive and must match the event name exactly. String Y
Optional parameters Any additional properties that will be viewed as interaction data. String N

 

 

CTI

Parameter Description Data Type Required?
agentId CTI login user name. This is case sensitive. String Y
jwt JWT API key that gives access to the service. String Y
event This is the event where the published Popflow to be executed exists. This is case-sensitive and must match the event name exactly. String Y
Optional Any additional properties that will be viewed as interaction data. String N

 

 

 

Sample request

GET

Set up the base URL: https://connect.openmethodscloud.com/api/sendmessage/CRM?

 

Add each required query parameter

agentid={insert_agentId}&jwt={insert_api_key}&crmId={insert_crmid}&event={name_of_event}

 

Ex: agentid=123&jwt=456&crmid=789&event=testing123

 

Add any additional data need for PopFlow workflow.

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

 

All together will look like this:

  • https://connect.openmethodscloud.com/api/sendmessage/CRM?agentId={insert_agentId}&jwt={insert_api_key}&crmId={insert_crmid}&event={name_of_event}&prop1={insert_prop1}&prop2={insert_prop2}
 

POST

Set up the base URL: https://connect.openmethodscloud.com/api/sendmessage/CRM?

 

  1. Then set up the body, making sure that the Content-Type is set to application/json.
  2. Finally, add the required body fields and the additional data need for Popflow workflow.

 

{
    "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",
}
 

 

Errors

Error Code Description Resolution
401 Unauthorized Response Verify you have the correct API Key.

 

Event not triggered?

  1. Ensure the event name is typed correctly, both case and length (spaces included).
  2. Double-check that the intended Popflow to be triggered is published to the event that is being called.
  3. Finally, if in Service Cloud CRM, ensure that the published profile is matching to CRM user's profile.

Related Articles