Knowledge Base

How to create a new xAssist call using the API

1. Gather valid login credentials.

2. Set up a post call using the /rtc/createCall endpoint and set up the request body as explained below.

Annotated request body JSON:

{
  "callTitle": "Test Call", \\Name of the call
  "callReason": "STANDARD", \\Either Standard or SERVICE_REQUEST
  "callType": "SFU", \\ Defines the call technology used eg. MESH for 1:1 calls or SFU for Multicalls
  "invitedContacts": [ \\ List of multiple CallLogContact objects
    {
      "displayName": "Tester", 
      "domain": "ubimax",
      "email": "[email protected]",
      "phoneNumber": "",
      "userDbId": 8, \\The database id of the user, which the contact is linked too.
      "userId": "tester" \\The user id id of the user, which the contact is linked too.
    }
  ],
  "invitedTeams": [], \\ Leave empty or add a team object to invite a whole team.
  "joinAnonymousAllowed": true, \\ Set to true to allow anonymous joins else false
  "informOthersDirectly": true, \\ Set to true to trigger the call notification pop-up on invited contacts screen
  "creatorUser": 12, \\ The database id of the user. Leave empty or Set it to create calls on behalf of someone, behaving as a broker.

Annotated response body JSON (CallLog object):

{
 "id": 842, \\Incremental id generated by the database
 "callId": "e76e1d8a-8267-4bd4-ba5c-00ab76743e74", \\UUID generated by the application
 "anonymousJoinAllow": true, \\Whether anonymous joins are allowed or not
 "callStatus": "Ended", \\Possible values: Planned, Started or Ended
 "creatorContact": { \\ CallLogContact object. References the user that generated the call or the “creatorUser” specified when creating the call.
   ...
 }
 "invitedContacts": [ \\ List of multiple CallLogContact objects
  {
   ...
  }
 ]
 "callEvents": [ \\ List of multiple call Events
  {
   "id": 234, \\Incremental id generated by the database
   "type": "Created", \\Possible values: Created, Join, Leave, between others.
"contact": { \\ CallLogContact object. References the user related with the current event.
   ...
 }
  }
 ]

3. The server notifies the invited contacts via WebSocket, Mail, or SMS (if set in CallLogContactObject).

How to know the state of a call using the API

1. Gather valid login credentials.

2. Set up a get call using the /rtc/getCallLogById?callId=value endpoint with the callId obtained from the response of the createCall endpoint mentioned above.

Annotated response body JSON:

Same response as createCall endpoint. For example, for an ongoing mesh call originated by callertest1 to callertest2, the events would be as follows:

"callEvents": [
  {
   "id": 697,
   "type": "Created",
   "contact": {
    "id": 1,
    "userId": "callertest1",
    "userDbId": 8
   }
  },
  {
   "id": 698,
   "type": "Join",
   "contact": {
    "id": 1,
    "userId": "callertest1",
    "userDbId": 8
   }
  },
  {
   "id": 699,
   "type": "Join",
   "contact": {
    "id": 2,
    "userId": "callertest2",
    "userDbId": 9
   },
  }
 ],

How to create a mesh call from the Connector

Use the methods exposed by the RtcControllerApi. The ones that stand out are createCallForContacts to create the call and getCallLogById to know the state of the call.

To create a call, use the creatorUser property mentioned before. Set it to the userDbId of the smartglasses user, and add the expert user and the connector user to the invitedContacts array. Therefore, the connector ends up behaving like a broker. Keep in mind that the smartglasses user will only be called once the expert user answers the call.

Sequence diagram

Node.js example

Node.js example call (stripped down, might require further security headers and cookies, gathered via a Login).

fetch("https://<serverurl>/rtc/createCall", {
  "headers": {
    "authorization": "Bearer <token>",
  },
  "body": "{\"callType\":\"SFU\",\"invitedContacts\":[{\"userId\":\"tester\",\"userDbId\":8,\"email\":\"[email protected]\",\"domain\":\"ubimax\",\"displayName\":\"Tester\",\"phoneNumber\":null}],\"invitedTeams\":[],\"joinAnonymousAllowed\":false,\"callTitle\":\"New Call\",\"plannedDateTime\":null,\"callReason\":\"STANDARD\"}",
  "method": "POST",
  "mode": "cors"
});