PhoneApp

Disclaimer

This document is a prelimary version and work-in-progress,
Details discussed in this document will be subject to future modifications.

Workflow

The workflow is summarized as follow once a phone call has been recorded and transcript completed:

1. Delos will send a request to PhoneNotifications server that a new call has been recorded, with optional parameter WMSG_TRANSCRIPT_STATUS=Queued in case the associated contact (CPSN) is marked for automatic transcript foreach call recording
2. The PhoneNotifications server notifies the appropriate PhoneApp
3. PhoneApp MAY request the WMSG on Delos instance to display basic infos about call recording
4. PhoneApp SHOULD request /Phone_GetCPSN from WMSGPSN_PSN to verify that the contact details stored in Delos database are up-to-date
5. In case the contact needs update, PhoneApp will invoke /Phone_BatchCPSN, this action provides important informations to facilitate the process of transcript, such as first name, last name, organization name, address (city).
6. The user of the PhoneApp MAY trigger the transcript of the call by invoking Delos server
7. Once the transcript has been completed, Delos server send a request to the PhoneNotifications server for this WMSG[WMSG_ID]
8. PhoneNotifications relay to the proper PhoneApp
9. PhoneApp invokes Delos server Phone_FormWSMG to retrieve the summary and transcript of the call.
10. PhoneApp may download the recording of the call using Phone_DownloadFile.

At the end of this document, there is the description of Delos acting as a relay for originating a MakeCall between the PhoneApp and the S2T server transmitting the parameters Line, Source, and Destination.

HTTP Authorization and Protocol

Authorization for the communications between Delos and PhoneNotifications is granted by IP bypass for the restricted range of Delos instances.

Authorization between PhoneApp and Delos instance of the user requires XMLC_Credential, a token value encoding XMLC_UserID + XMLC_Session.
And so all HTTP requests to Delos instance from the PhoneApp will be considered in this specification formatted as: 
https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_ListWMSG
where 1xxx1abcdef is the XMLC_Credential encoding XMLC_UserID+XMLC_Session
This credential is obtained after initial registration.

/sendNotification [type=new_call_record] (Delos -> PhoneNotifications)

When a new call has been inserted from the S2T server, Delos instance sends a HTTP GET request to the PhoneNotifications server, with the following parameters:

http://phoneappnotifications.buzzee.tel/sendNotification?
XMLC_UserID=1000001&
XMLC_Credential=1xx1abcdef&
Domain=fr01.buzzee.tel&
Host=fr01a.buzzee.tel&
type=new_call_record&
Application=Phone&
Token=abcdef0123456789&
WMSG_ID=1001002

Note: in the case of HTTP GET request, the character '&' is a separator between parameters formatted as: FieldName=FieldValue
 

Note: If the contact associated with the call recording has been setup to always skip transcript (CPSN_TRANSCRIPT=0),
then Delos will not send a notification to PhoneNotifications server.

/Phone_FormWMSG (PhoneApp -> Delos)

PhoneApp may retrieve the details of the phone call recording by invoking a HTTP GET request,
at this stage the response will not contain the transcript of the conversation.

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_FormWMSG?WMSG_ID=1001002

 

Delos instance will respond with a JSON document corresponding to the message:

{ "WMSG" : {
    "WMSG_ID": "1001002",
    "WMSG_DATETIME" : "2023-12-31 09:00:00", 
    "WMSG_DURATION" : "00:10:00",
    "WMSG_INOUT" : "1", 
    "WMSG_MEDIA" : "-3515", 
    "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT",
    "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" }
} 

On real Delos servers the JSON document will return a larger document with a lot more fields, but these are the minimalists to be useful in the context of PhoneApp.

To obtain details of the contact PhoneApp may request /Phone_GetCPSN?CPSN_ID=1000202

/Phone_GetCPSN (PhoneApp -> Delos)

The PhoneApp SHOULD lookup contact details from Delos instance to check if informations are up-to-date.
These data facilitate the process of transcript for the recorded call,
PhoneApp sends a HTTP GET request to Delos instance:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_GetCPSN?CPSN_ID=1001001

Delos instance will respond with a JSON document:

{ "CPSN" : 
  { "CPSN_ID" : "1000202", "CPSN_VERSION" : "1000042"
    "CPSN_FIRST_NAME" : "Dave", "CPSN_LAST_NAME" : "THEUGLY",
    "CCOMS" : { "CCOM" :
          [ { "CCOM_ID" : "1001", "CCOMKND_ID" : "-3515", "CCOM_VALUE" : "33609876543" },
            { "CCOM_ID" : "1002", "CCOMKND_ID" : "-3501", "CCOM_VALUE" : "dave@acme.com" },  ….
          ] }
  },
  "CLOC" : { "CLOC_ID" : "10000201", "CLOC_VERSION" : "1000041", "CLOC_NAME" : "ACME" }
}

The major fields are:

The following table summarizes the different error codes:

/Phone_BatchCPSN (PhoneApp -> Delos)

If the PhoneApp detects contact informations are not up-to-date between local version and Delos database,
PhoneApp will POST a request to Delos instance with the content of the body as a JSON document:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_BatchCPSN

{ "CPSN" : 
  { "CPSN_ID" : "1000202", "CPSN_VERSION" : "1000042"
    "CPSN_FIRST_NAME" : "Dave", "CPSN_LAST_NAME" : "THEUGLY",
    "CCOMS" : { "CCOM" :
          [ { "CCOM_ID" : "1001", "CCOMKND_ID" : "-3515", "CCOM_VALUE" : "33609876543" },
            { "CCOM_ID" : "1002", "CCOMKND_ID" : "-3501", "CCOM_VALUE" : "dave@acme.com" },  ….
          ] }
  },
  "CLOC" : { "CLOC_ID" : "10000201", "CLOC_VERSION" : "1000041", "CLOC_NAME" : "ACME" }
}

The major fields are:

The following table summarizes the different error codes:

/Phone_Transcript (PhoneApp -> Delos)

PhoneApp may trigger the transcript by invoking a HTTP GET request:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_Transcript?WMSG_ID=1001002

Delos instance will respond with the Status Queued, meaning the request has been forwarded to S2T server:

{ "Status" : "Queued" } 

Note: PhoneApp can pass the parameter CPSN_TRANSCRIPT=1 along the action Phone_Transcript as a hint for Delos instance to store this parameter associated with this contact, in order for future phone call recording to start transcript without prompting the user.

Note: PhoneApp MAY invoke Phone_UpdateCPSN_TRANSCRIPT to store for a contact (CPSN_ID) the behavior on new phone call recording. 0=Never. 1=Always. 2=Prompt.
https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_UpdateCPSN_TRANSCRIPT?CPSN_ID=1000202&CPSN_TRANSCRIPT=0

/sendNotification [type=transcript_ready] (Delos -> PhoneNotifications)

Once the transcript has been completed by S2T server, Delos instance sends a HTTP GET request to the PhoneNotifications server, with the following parameters:

http://phoneappnotifications.buzzee.tel/sendNotification?
XMLC_UserID=1000001&
XMLC_Credential=1xx1abcdef&
Host=fr01a.buzzee.tel&
Domain=fr01.buzzee.tel&
type=transcript_ready&
Application=Phone&
Token=abcdef0123456789&
WMSG_ID=1001002

/Phone_FormWMSG (PhoneApp -> Delos)

At this stage PhoneApp may retrieve the summary and the transcript by invoking a HTTP GET request

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_FormWMSG?WMSG_ID=1001002

 

Delos instance will respond with a JSON document corresponding to the message:

{ "WMSG" : {
    "WMSG_ID": "1001002",
    "WMSG_DATE" : "26/12/2023 09:00:00",   
    "WMSG_DURATION" : "00:10:00",
    "WMSG_INOUT" : "1",
    "WMSG_MEDIA" : "-3515",
    "WMSG_INFO" : "Once upon a time…",
    "WMSG_SUMMARY" : "Long story short, this field includes an 
                      extended description of the transcription",
    "WMSG_TRANSCRIPT" : { "Sequence" :
      [ { "ID" : "00:00:00.980", "Time" : "09:00:00", From : "1000202", "Message" : "Hello Bob" },
        { "ID" : "00:00:02.140", "Time" : "09:00:02", From : "1000003", "Message" : "Hi Dave" },  ….
      ] }
} } 

On real Delos servers the JSON document will return a larger document with a lot more fields, but these are the minimalists to be useful in the context of PhoneApp.

/Phone_DownloadFile (PhoneApp -> Delos)

PhoneApp may download the WAV of the recording by sending a HTTP GET request to Delos instance:

http://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_DownloadFile?WMSG_ID=1001001&Stream=in&TrackID=1&Start=0&Stop=30

All the parameters of DownloadURL are provided when invoking /TranscribeFile.

The following table summarizes the different error codes:

/UpdateCPSN_AUDIO_HINT (PhoneApp -> Delos)

To improve transcription, the user may add hints for keywords,
first, the PhoneApp will retrieve the actual CPSN_AUDIO_HINT either using /Phone_GetCPSN or /FormCPSN_AUDIO_HINT
PhoneApp will POST a request to Delos instance with the modified field CPSN_AUDIO_HINT:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_BatchCPSN
CPSN_ID=1001002
CPSN_AUDIO_HINT=Buzzee Talk DelosLabs XMLRAD

Delos will respond with Status = OK

{ "Status" : "OK" } 

The main fields for this request are:

The following table summarizes the different error codes:

Workflow when opening PhoneApp

 

When starting the PhoneApp, it retrieves the list of messages (of type phone recorded) by sending a Phone_ListWMSG request to Delos, and may request some details per phone call by invoking Phone_FormWMSG

/Phone_ListWMSG (PhoneApp -> Delos)

PhoneApp may retrieve the list of recent conversations by invoking as HTTP GET request

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_ListWMSG?WMSGKND_ID=-3515

 Delos instance respond with a JSON document corresponding to the list of messages:

{ "WMSGS" : { "WMSG" : [ 
   { "WMSG_ID": "1001002", "WMSG_DATETIME": "2023-12-31 09:20:00", "WMSG_INOUT" : "2", 
     "WMSG_INFO" : "Custom summary for confcall #2",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT",
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   { "WMSG_ID": "1001004", "WMSG_DATETIME": "2023-12-31 09:00:00", "WMSG_INOUT" : "1",
     "WMSG_INFO" : "Summary ConfCall #1",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT", 
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   ...
   ] } 
} 

Actually, JSON document will return a larger document with a lot more fields, but these are the minimalists to be useful in the context of PhoneApp to display the recent calls

/Phone_DeleteAudio (PhoneApp -> Delos)

PhoneApp may delete audio file associated with a recording, (phone call, voicemail, conversation, recording, conference).
All stream files will be removed from disk, stream .all.wav, .in.wav, .out.wav.
Delete audio files by sending a HTTP GET request to Delos instance:

http://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_DeleteAudio?WMSG_ID=1001001

Delos instance will respond with the Status OK:

{ "Status" : "OK" } 

Delos will set in DB KURL_AUDIO_DELETED=1 in the record WMSG which will be available for /Phone_FormWMSG to indicate if the audio files have been deleted.
The following table summarizes the different error codes:

/DeleteWMSG (PhoneApp -> Delos)

PhoneApp may delete a WMSG (phone call, voicemail, conversation, recording, conference).
All stream files will be removed from disk, stream .all.wav, .in.wav, .out.wav. and all content of the transcription will be deleted from the database.
Delete a WMSG by sending a HTTP GET request to Delos instance:

http://fr01a.buzzee.tel/JSON/1xxx1abcdef/DeleteWMSG?WMSG_ID=1001001

Delos instance *may* respond with the Status OK:

{ "Status" : "OK" } 

The following table summarizes the different error codes:

/Phone_ListDeletedWMSG (PhoneApp -> Delos)

PhoneApp may retrieve the list of deleted conversations by invoking as HTTP GET request

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_ListDeletedWMSG?WMSGKND_ID=-3515

 Delos instance respond with a JSON document corresponding to the list of messages,
note that deleted WMSG will have a WMSG_DELETED with a date:

{ "WMSGS" : { "WMSG" : [ 
   { "WMSG_ID": "1001002", "WMSG_DATE": "12/12/2023 09:20:00", "WMSG_INOUT" : "2", 
     "WMSG_DELETED": "01/01/2024 11:30:00", 
     "WMSG_INFO" : "Custom summary for confcall #2",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT",
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   { "WMSG_ID": "1001004", "WMSG_DATE": "12/12/2023 09:00:00", "WMSG_INOUT" : "1",
     "WMSG_DELETED": "01/01/2024 11:00:00", 
     "WMSG_INFO" : "Summary ConfCall #1",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT", 
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   ...
   ] } 
} 

Actually, JSON document will return a larger document with a lot more fields, but these are the minimalists to be useful in the context of PhoneApp to display the recent calls

/Phone_RestoreAudio (PhoneApp -> Delos)

PhoneApp may restore deleted audio files associated with a recording, (phone call, voicemail, conversation, recording, conference).
All stream files will be restored from trash, stream .all.wav, .in.wav, .out.wav.
Restore deleted audio files by sending a HTTP GET request to Delos instance:

http://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_RestoreAudio?WMSG_ID=1001001

Delos instance will respond with the Status OK:

{ "Status" : "OK" } 

The following table summarizes the different error codes:

/RestoreDeletedWMSG (PhoneApp -> Delos)

PhoneApp may restore a deleted WMSG (phone call, voicemail, conversation, recording, conference).
All stream files will be restored from disk, stream .all.wav, .in.wav, .out.wav. and content of the transcription will be restored from the database.
Restore a deleted WMSG by sending a HTTP GET request to Delos instance:

http://fr01a.buzzee.tel/JSON/1xxx1abcdef/RestoreDeletedWMSG?WMSG_ID=1001001

Delos instance *may* respond with the Status OK:

{ "Status" : "OK" } 

The following table summarizes the different error codes:

/Phone_ListCPSNMSG (PhoneApp -> Delos)

PhoneApp may retrieve the list of recent conversations per contact (Dave THEUGLY) by invoking as HTTP GET request with the CPSN_ID as parameter:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_ListCPSNMSG?CPSN_ID=1000202&WMSGKND_ID=-3515

Delos instance responds with a JSON document corresponding to the list of messages for this contact:

{ "WMSGS" : { "WMSG" : [ 
   { "WMSG_ID": "1001002", "WMSG_DATE": "12/12/2023 09:20:00", "WMSG_INOUT" : "2", 
     "WMSG_INFO" : "Custom summary for confcall #2",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT",
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   { "WMSG_ID": "1001004", "WMSG_DATE": "12/12/2023 09:00:00", "WMSG_INOUT" : "1",
     "WMSG_INFO" : "Summary ConfCall #1",
     "WMSG_SUMMARY" : "Once upon a time...",
     "WMSGUSR_PSN" : "1000002", "WMSGUSR_FIRST_NAME" : "Bob", "WMSGUSR_LAST_NAME" : "THEGREAT", 
     "WMSGPSN_PSN" : "1000202", "WMSGPSN_FIRST_NAME" : "Dave", "WMSGPSN_LAST_NAME" : "THEUGLY" },
   ...
   ] } 
} 

Actually, JSON document will return a larger document with a lot more fields, but these are the minimalists to be useful in the context of PhoneApp to display the recent calls.

/Phone_UpdateWMSG_TRANSCRIPT_STATUS (PhoneApp -> Delos)

PhoneApp can update the status of the transcript (WMSG_TRANSCRIPT_STATUS) by invoking Delos with a POST request:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_UpdateWMSG_TRANSCRIPT_STATUS

with the following parameters:

The response will be blank

{} 

The following table summarizes the different error codes:

/Phone_UpdateWMSG_INFO (PhoneApp -> Delos)

PhoneApp can update the summary of the transcript (WMSG_INFO) by invoking Delos with a POST request:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_UpdateWMSG_INFO

with the following parameters:

The response will include the WMSG_ID

{ "WMSG_ID" : "1001002" }

The following table summarizes the different error codes:

/Phone_Summarize (PhoneApp -> Delos)

PhoneApp lookup in the local contact manager of the device when the CPSN_LAST_NAME is a phone number,
if the contact exists, PhoneApp may batch the contact infos to Delos,
in order to take advantage of the contact infos for the summarization of a transcription,
PhoneApp may invoke Phone_Summarize to reprocess the summarization taking into account the contact infos newly updated.

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_Summarize?WMSG_ID=1001003&Preview=1

The response will be Status=OK

{ "Status" : "OK" }

The following table summarizes the different error codes:

/Phone_UpdateWMSG_TRANSCRIPT (PhoneApp -> Delos)

PhoneApp can update a specific sequence of the transcript (WMSG_TRANSCRIPT) by invoking Delos with a POST request:

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_UpdateWMSG_TRANSCRIPT

with the following parameters:

The response will include the WMSG_ID

{ "WMSG_ID" : "1001002" }

The following table summarizes the different error codes:

/Phone_MakeCall

Delos may relay from PhoneApp a request MakeCall with parameters Source and Destination

PhoneApp will invoke Delos instance with a HTTP GET request

https://fr01a.buzzee.tel/JSON/1xxx1abcdef/Phone_MakeCall?Source=336122345678&Line=33712345678&Destination=3309876543

Les paramètres à fournir sont les suivants :

Delos instance will respond with the Status Originating, meaning the request has been forwarded to S2T server:

{ "Status" : "Originating" } 

The VoIP centrex should then make ring the mobile phone of the user and the standard phone utility application will take over.

This endpoint may raise an error which is formatted as follow:

{ "Code" : "ERR_SOURCE_IS_NOT_USER", "Message": "Source is not a user" }

The following table summarizes the different error codes: