# com.innovaphone.conference-transcriptions

This API can be used to obtain audio transcriptions from conferences and to receive summaries of the transcripts.

## Messages

SubscribeStatus
UnsubscribeStatus
StartTranscription
StopTranscription
SubscribeListen
UnsubscribeListen
GetSummary
GetTranscript
GetParticipants

### SubscribeStatus

sends a transcription status subscription request for a conference room. By subscribing, you will receive StatusUpdate messages that indicate whether a transcript of the room is currently in progress and provide the GUID required to retrieve the transcript and the summary. The GUID will be sent as soon as the transcription of the conference room is started.

    {
        mt:  "SubscribeStatus",
        sip: "endeavour",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt:      "SubscribeStatusResult",
        error:   "Connection to transcription service could not be established!"
    }

#### Parameters

string mt | message type (is "SubscribeStatusResult")
string error | in case of an error that error is sent here [optional]

#### Response Info

These messages are sent regularly depending on the 'Minimal latency' setting in the service settings plugin. The guid is valid for one call. Each new call started with a StartTranscription will receive a new guid. The on parameter might switch during the call depending on the status of the remote transcription server (e.g., whisper)

    {
        mt:    "StatusUpdate",
        on:    true,
        guid:  "aab3f080f57c4e6f9ecee23194d3eeeb",
        error: "INTERNAL SERVER ERROR",
        end:   true
    }

#### Parameters

string mt | message type (is "StatusUpdate")
bool on | true when actually transcribing, false when some error occured e.g. audio signal to weak
string guid | Globally Unique Identifier created for that transcript and call
string error | The error occured if the transcript failed [optional]
bool end | is true when the call ended [optional]

### UnsubscribeStatus

Stops receiving real-time transcription updates.

    {
        mt:  "UnsubscribeStatus",
        sip: "softconference?room=10",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt: "UnsubscribeStatusResult"
    }

#### Parameters

string mt | message type (is "UnsubscribeStatusResult")

### StartTranscription

Starts transcription for a given conference room.

    {
        mt:  "StartTranscription",
        sip: "softconference?room=10",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt:   "StartTranscriptionResult",
        guid: "aab3f080f57c4e6f9ecee23194d3eeeb"
    }

#### Parameters

string mt | message type (is "StartTranscriptionResult")
string guid | Globally Unique Identifier created for that transcript

### StopTranscription

Stops an ongoing transcription session.

    {
        mt:  "StopTranscription",
        sip: "softconference?room=10",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt: "StopTranscriptionResult"
    }

#### Parameters

string mt | message type (is "StopTranscriptionResult")

### SubscribeListen

Subscribes to real-time transcription updates during a conference.

    {
        mt:  "SubscribeListen",
        sip: "softconference?room=10",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt: "SubscribeListenResult"
    }

#### Response Info

    {
        mt:               "ListenUpdate",
        speaker:          "John Doe",
        text:             "Welcome everyone to the meeting.",
        sentenceComplete: true,
        end:              false
    }

#### Parameters

string mt | message type (is "ListenUpdate")
string speaker | Name or identifier of the speaker
string text | Transcribed text
bool sentenceComplete | True if the sentence is complete
bool end | True if the transcription session has ended

### UnsubscribeListen

Stops receiving real-time transcription updates.

    {
        mt:  "UnsubscribeListen",
        sip: "softconference?room=10",
        pin: "1234"
    }

#### Parameters

string mt | message type [mandatory]
string sip | the sip of the conference room [mandatory]
string pin | the pin of the conference room if required [optional]

#### Response

    {
        mt: "UnsubscribeListenResult"
    }

#### Parameters

string mt | message type (is "UnsubscribeListenResult")

### GetSummary

Retrieves a summary of the transcription session.

    {
        mt:   "GetSummary",
        guid: "aab3f080f57c4e6f9ecee23194d3eeeb"
    }

#### Parameters

string mt | message type [mandatory]
string guid | Globally Unique Identifier of the transcript [mandatory]

#### Response

    {
        mt:      "GetSummaryResult",
        summary: "Meeting covered project updates, budget planning, and next steps."
    }

#### Parameters

string mt | message type (is "GetSummaryResult")
string summary | Summary of the transcription session

### GetTranscript

Retrieves the full transcript of a transcription session.

    {
        mt:   "GetTranscript",
        guid: "aab3f080f57c4e6f9ecee23194d3eeeb"
    }

#### Parameters

string mt | message type [mandatory]
string guid | Globally Unique Identifier of the transcript [mandatory]

#### Response

    {
        mt:        "GetTranscriptResult",
        transcript: "John: Welcome everyone...\nJane: Thanks John..."
    }

#### Parameters

string mt | message type (is "GetTranscriptResult")
string transcript | Full transcript of the session

### GetParticipants

Retrieves the full transcript of a transcription session.

    {
        mt:   "GetParticipants",
        guid: "aab3f080f57c4e6f9ecee23194d3eeeb"
    }

#### Parameters

string mt | message type [mandatory]
string guid | Globally Unique Identifier of the transcript [mandatory]

#### Response

    {
        mt:        "GetParticipantsResult",
        participant: {name:"John Doe", sip:"jdo", num:"123"}
    }

#### Parameters

string mt | message type (is "GetParticipantsResult")
object participant | objects of a participant of the transcribed meeting

When no more participants will be send the message will contain the paramter last set to true.

#### Response

    {
        mt:        "GetParticipantsResult",
        last:       true
    }

#### Parameters

string mt | message type (is "GetParticipantsResult")
bool last | true if no more messages are following

## Example

You can consume the API com.innovaphone.conference-transcriptions and send request to it. Inside the callback you can access the response text via recv.msg.message.content

        var conferenceTranscriptionsApi = start.consumeApi("com.innovaphone.conference-transcriptions");
        var guid = null;

        // Start transcription
        function startTranscription() {
        conferenceTranscriptionsApi.sendSrc({ mt: "StartTranscription", sip: "softconference?room=10", pin: "1234" }, conferenceTranscriptionsApi.providers[0], onStart);
        }

        // Callback for StartTranscription
        function onStart(recv) {
        guid = recv.msg?.guid;
        setTimeout(stopTranscription, 10000);
        }

        // Stop transcription
        function stopTranscription() {
        conferenceTranscriptionsApi.sendSrc({ mt: "StopTranscription", pin: "1234" }, conferenceTranscriptionsApi.providers[0], onStop);
        }

        // Callback for StopTranscription
        function onStop(recv) {
        setTimeout(getSummary, 10000);
        }

        // Get summary
        function getSummary() {
        conferenceTranscriptionsApi.sendSrc({ mt: "GetSummary", guid: guid }, conferenceTranscriptionsApi.providers[0], onSummary);
        }

        // Callback for GetSummary
        function onSummary(recv) {
        console.log(recv.msg.summary);
        }

        startTranscription();