Skip to main content

CareAR Instruct Invocation with Web API

  • Updated

This article will aim to explore invocation of the CareAR Assist workflow from your application. Similar to the Web API for Assist, this Web API for Instruct can also provide context with the launch of an Instruct session and return data back to the configured REST endpoint in the Web API Connector. 

Prerequisites

CareAR Web API implementations require the tenant to be subscribed to an appropriate subscription plan. You can confirm your plan type in the CareAR Admin Portal under the Administration screen.

CareAR Web API Reference

Invoking CareAR Instruct from an external application

The HTTPS GET request sent by the invoking application will include and encode URL parameters as indicated below.

Note: Parameter names are case sensitive.

PARAMETER MANDATORY/
OPTIONAL		 DESCRIPTION
authToken Mandatory Authentication token for tenant as defined in the Web API Connector profile in the Connector center
iVer Mandatory Version of the API
iName Mandatory Name of the custom Web API Connector. When using the Web API you should use the value ‘ WEBAPI ’

Reserved names include:

SNOW | SFDC | WEBAPI
refId Optional Generic reference ID providing context for the request. For example, a service management application might pass the ticket ID in this parameter. Other options could be work order identifier, case identifier, etc.

CareAR treats this string as an opaque alphanumeric character string and performs no action. When passed, this string is written to the CareAR session data object.

alphanumeric string
iParam Mandatory Parameters relating to the application that is invoking CareAR Instruct.
implementers are free to use this parameter to pass an opaque “data blob” in the form of a JSON object.

CareAR will not read, parse, or otherwise act on this JSON object and will simply pass this back to the implementer’s web service, should the implementer choose to do that.

Should implementers choose not to make use of this parameter, simple include as “iParam=” with null char string.

NOTE: Value must be base64 encoded. 
type Mandatory Name of the CareAR application your app will launch. Values of 'assist' or 'instruct' are accepted.
callbackUrl Optional

Mandatory if callbackLabel is used		 At the end of the CareAR session, most implementers will want to return the host to the invoking application. This URL should point to the FQDN and path of the invoking application and specific service object, if relevant.

The callbackUrl parameter is only supported on mobile.

IMPORTANT: This value must be base 64 encoded.
callbackLabel Optional

Mandatory if callbackUrl is used		 There is a button presented to the user with call to action to return to the invoking application. The label on the button is an alphanumeric character string that the implementer specifies. Generally, this is the name of the invoking application or service.

alphanumeric string
tenantId Mandatory CareAR Instruct Only: This is the ID number associated with the CareAR tenant where the experience is hosted. This ID can be obtained from the WebAPI Connector page in the CareAR web portal.

alphanumeric string
experienceId Mandatory CareAR Instruct Only: This is the ID number associated with the Instruct experience. This ID can be obtained from the Experience details page in the Content section of the CareAR web portal.

alphanumeric string
clusterId Mandatory CareAR Instruct Only: This is the ID number associated with the Instruct experience. This ID can be obtained from the Experience details page in the Content section of the CareAR web portal.

alphanumeric string
pageId Optional CareAR Instruct Only: This alphanumeric string is the ID associated with a specific page within an Instruct experience. This ID can be obtained from the Experience builder. For Advanced Content, the page ID is provided by the author of the content.

If no pageId parameter, or an invalid pageId parameter, is provided the experience will open to the initial page. 

Example Values

Using the table above examples for each value that for context are as follows:

  • authToken
    • 4bc6befca3df29c8641e
  • iVer
    • 1.0
  • iName
    • WEBAPI
  • refId
    • 3CK88832
  • iParam
    • WW91IGNhbiBpbnNlcnQgd2hhdGV2ZXIgeW91IHdhbnQgaW4gdGhpcyBzZWN0aW9uIGFzIGxvbmcgYXMgaXQgaXMgQmFzZTY0IGVuY29kZWQ=
  • type
    • instruct
  • callbackUrl
    • aHR0cHM6Ly9wcm9kdWN0aW9uLnR1cmJvLXNlcnZpY2UuY29tL3JlY29yZC9UdXJiby1Xb3JrLU9yZGVyL2E0ZTQyODQ2ZDQzOTI=
  • callbackLabel
    • Turbo Service Management Agent
  • tenantId
    • ukkFvZeMSeWSxeK2s0X9
  • experienceId
    • ieJG1pDejM0TLOHSs67b
  • clusterId
    • V46wbCxFkzXGuaW5
  • pageId
    • op8hxz0vg2vlcqna26yn

Obtaining Parameters for an Experience

The easiest way to obtain many of the parameters needed to use the web API is to simply copy them from the Experience Builder. Clicking on the Link icon on the top of a page within an experience will copy the experience link.

Instruct-WebAPI-URL.png

Using the link copy button captures a valid experience link with the following parameters:

• Tenant ID
• Experience ID
• Cluster ID
• Page ID

Example of link copied from experience

https://carear.app/eb/#/live-preview/?experienceId=fi3ztZWE5MiyM0lrqzyi&tenantId=dvlgG0tHr5zyt31u7E8I&clusterId=V46wbCxFkzXGuaW5&pageId=uib4eyQwwd8ppz8r5jey7j

Example Launch URL

The link obtained from the Experience Builder in the previous step will work for launching the experience. It can be used directly if needed. However, in order to utilize the full features of the web API you need to append additional parameters to the URL as outlined in the Web API reference.

Example of link with parameters added

https://carear.app/eb/#/live-preview/?experienceId=fi3ztZWE5MiyM0lrqzyi&tenantId=dvlgG0tHr5zyt31u7E8I&clusterId=V46wbCxFkzXGuaW5&pageId=uib4eyQwwd8ppz8r5jey7j&iParam=ewogICAieW91ckJsb2IiOiJpbnNlcnRZb3VyRGF0YSIKfQ==&type=instruct&iVer=1.0&iName=WEBAPI&authToken=uKkFvZeM2ewSXeK2s0X9&refId=abc123&callbackLabel=Example&callbackUrl= aHR0cHM6Ly9leGFtcGxlLmNvbS8=

Callback Label & URL Presentation

The callbackUrl and callbackLabel are represented differently in the CareAR Instruct app. The button to return the user out of the Instruct app is presented as a banner as seen below.

Instruct-WebAPI-callback.png

Example showing callbackLabel set to “support.xerox.com”

HTTPs POST Types

There are several types of messages that will be delivered via POST message from the CareAR platform. These messages can be sent at any time and are triggered based upon events occurring in the CareAR Instruct session.

Session Start

CareAR Instruct Session Start

{
  "YOUR IPARAM JSON BLOB}",
  "refId": "YOUR REFID",
  "instructTrigger": "instructSession",
  "Session": {
    "event": "CareAR Instruct: Session Start \n\n Session Start Time = Wed April 01 2024 21:17:03 GMT+0000 (Coordinated Universal Time) \n\n Experience = Feature Tester \n\n Experience ID = 3qJppkR5WtkhGtfAUnnW \n\n Session ID = 850394e1-067f-41c0-9e3b-4c88886448f8"
  }
}

CareAR Instruct Form Submission

{
  "YOUR IPARAM JSON BLOB}",
  "sessionId": "850394e1-067f-41c0-9e3b-4c88886448f8",
  "tenantId": "yPdp5QquBEU555j7ysDd",
  "experienceId": "3qJppkR5Wt555tfAUnnW",
  "pageId": "hg67ht7y555opfiyv3xda",
  "refId": "YOUR REFID",
  "formName": "Test Form",
  "formId": "element-lucqo0d2",
  "dataSavedTo": "",
  "headerText": "The following data was captured from a CareAR Instruct experience:",
  "submissionTime": "2024-04-01T21:17:14.977Z",
  "webhookType": "form",
  "event": "formInput",
  "instructTrigger": "formInput",
  "field0": {
    "Test Question": "Test Response",
    "type": "singleLine"
  },
}

CareAR Instruct Camera Capture

{
 "{YOUR IPARAM JSON BLOB}",
  "refId": "YOUR REFID",
  "imageName": "YOUR REFID.jpeg",
  "sessionId": "850394e1-067f-41c0-9e3b-4c88886448f8",
  "instructTrigger": "cameraCapture",
  "imageValue": "<IMAGE VALUE AS BASE64>"
}

Related articles

Powered by Zendesk