CareAR Assist Invocation with Web API – CareAR Help Center

This article will aim to explore invocation of the CareAR Assist workflow from your application.

Parameters

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 Assist. 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 implementors 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.
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 NOTE: The callbackLabel parameter is only supported on mobile with Assist integrations.
assist	Mandatory if type= assist	This is the target guest participant’s contact information (one or both of mobile phone and email address). When present, this will preload the CareAR Assist experience with invite address information, making for a more fluid experience for the CareAR Assist host. Sub-parameters include: contact_mobile (mobile phone number (in globalized format “+” + ”country code” + ”national number”) contact_email (standard email format) Any of these parameters may be set to null if they are unavailable. However, the parameters must be present. If both mobile phone and email provided, Assist will use the mobile phone. NOTE: Value must be base64 encoded.

Example values

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

authToken
- 4bc6befca3df29c8641e
iVer
- 1.0
iName
- WEBAPI
refId
- 3CK8832
iParam
- WW91IGNhbiBpbnNlcnQgd2hhdGV2ZXIgeW91IHdhbnQgaW4gdGhpcyBzZWN0aW9uIGFzIGxvbmcgYXMgaXQgaXMgQmFzZTY0IGVuY29kZWQ=
type
- assist
callbackUrl
- aHR0cHM6Ly9wcm9kdWN0aW9uLnR1cmJvLXNlcnZpY2UuY29tL3JlY29yZC9UdXJiby1Xb3JrLU9yZGVyL2E0ZTQyODQ2ZDQzOTI=
callbackLabel
- Turbo Service Management Agent
assist
- Y29udGFjdF9tb2JpbGU9KzEyMjIzMzM0NDQ0O2NvbnRhY3RfZW1haWw9bmFtZUBkb21haW4uY29t

Example Launch URLs

The general structure between desktop and mobile apps is the same. However, the URL for mobile apps do include some additional static parameters. See below for examples of each.

Assist Desktop URL

https://carear.app/#/s/dl.htm?authToken= YOURTOKEN&iVer=1.0&iName=WEBAPI&type=assist &region=US&refId=YOURREFERENCE&assist=MOBILEPHONEANDEMAILBASE64ENCODED&iParam=YOURJSONBLOBBASE64ENCODED

Assist Mobile URL

For mobile devices the URL must be formatted with HTML character encoding in mind. This would mean from the previous URL characters such as '=' need to be converted to their HTML counter part '%3D'. While most of your parameters will likely remain similar between desktop and mobile it is important that the formatting will be different as a result of the HTML character encoding.

https://carear.page.link/?link=https://carear.page.link/?authToken%3DYOURTOKEN%26iVer%3D1.0%26iName%3DWEBAPI%26iParam%3DYOURJSONBLOBBASE64ENCODED=%26type%3Dassist%26region%3DUS%26callbackURL%3Dhttps://YOURLINK.COM%26callbackLabel%3DYOURAPPNAME%26refId%3DYOURREFERENCE%26assist%3DMOBILEPHONEANDEMAILBASE64ENCODED&apn=io.CareAR.connect&isi=1468965844&ibi=io.carear.CareConnect

NOTE: All mobile connections MUST include the following part of the URL to function properly:

&apn=io.CareAR.connect&isi=1468965844&ibi=io.carear.CareConnect

Callback Label & URL Presentation

Mobile phones do not support multiple applications to be open on screen simultaneously. For this reason, when CareAR Assist application is launched it occupies the full screen moving the third-party launching application to the background. CareAR Assist application can present the user with an option to return to the launching application using the callbackLabel and callbackUrl parameters. When the callbackLabel and callbackUrl parameters are including in the HTTPs GET request, the CareAR Assist application will present a user prompt at the conclusion of the call or as a banner on top of the screen as seen below.

Example showing callbackLabel set to “WebAPISampleLabel”

Sending Data Back to the Invoking Application

HTTPs POST Configuration

For Assist-related session data to be properly returned to your web service, you must supply the proper configuration within the Web API Connector found in the CareAR admin portal. You must supply the username and password the CareAR service should use to connect with your web service. Also, the FQDN and path where the HTTPs POST should send the data.

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 Assist session.

Image Attachment

CareAR Assist Snap Shot

{
  …
  <Your iParam JSON Blob>
  …
  "imageName": "filename.jpeg",
  "imageValue": "…………”
}

NOTE: The imageValue will be the base64 encoding version of the image. You will need to decode the image back to it's .jpeg form to utilize efficiently.

Text Attachment

End of Session Report

{
  …
  <Your iParam JSON Blob>
  …
  "Session": {
    "StartDateTime": "2022-09-13T18:42:54.496Z",
    "EndDateTime": "2022-09-13T18:43:48.667Z",
    "SessionDuration": "00:20:54",
    "Participants": "[18:42:54 - 18:43:48] Host - Name, \n [18:43:26 - 18:43:44] Guest - Name"
  }
}

End of Session Survey Response

{
  …
  <Your iParam JSON Blob>
  …
  "survey": {
    "Survey": {
      "userType": "Host User",
      "user": "Username",
      "SurveyResult": [
        {
          "Question": "Dropdown question",
          "Answer": "Response 1"
        },
        {
          "Question": "Radio Button question",
          "Answer": " Response 2"
        },
        {
          "Question": "Singleline question",
          "Answer": "Singleline response"
        },
        {
          "Question": "Rating question",
          "Answer": "5 of 5 Stars"
        },
        {
          "Question": "Multiline question",
          "Answer": "Multiline response"
        },
        {
          "Question": "Rating (Thumbs) question",
          "Answer": "Thumbs Up"
        }
      ]
    }
  }
}

Recording Link

{
  …
  <Your iParam JSON Blob>
  …
  "VideoRecordingURL": [
    {
      "AmazonS3URL": "https://your.S3.amazonaws.com/filename.mp4"
    }
  ]
}