# com.innovaphone.assistant.plugin

This API is used for other apps to integrate their functionalities into the Assistant App. For example a contacts app may enable the Assistant App to search for contacts stored of the contacts app database and display these contacts in the Assistant App.

## Messages

AssistantGetPrompt
AssistantGetPromptResult
YourCostumMessage
AssistantInfo
AssistantResult

### AssistantGetPrompt

#### Request

Send by the Assistant App at startup. Gathers all prompt information related to the assistant plugin.

    {
        mt:   "AssistantGetPrompt"
    }

#### Response

of the plugin provider containing the actual prompt header and text that should be part of the systen prompt of the Assistant App

    {
        mt:   "AssistantGetPromptResult",
        prompt: {
            header: "Previous calls of the user",
            prompt: "If the user needs information about ..."
        }
    }

#### Parameters

string mt | message type [mandatory]
object prompt | contains the prompt object with header and prompt text [mandatory]
string header | short summary of the functionality [mandatory]
string prompt | the actual prompt text containing your costum messages and when they should be send [mandatory]

### YourCostumMessage

These messages must be defined in your prompt and depend on your implementation. Could be something like "GetPhoneNumber" or "GetCalllist"... You may add as many attributes as you like provided that the connected LLM is able to understand your prompt and correctly send the message.

    {
        mt:   "YourCostumMessage"
        ...
    }

#### Response

If you need to make a database request to your service and that service sends its entries you may send each of these entries to the LLM. They will be concatenated until the AssistantResult message is received and then send to the LLM together with extra instructions contained in the "AssistantResult" message.

    {
        mt:    "AssistantInfo",
        info: { ... }
    }

#### Parameters

string mt | message type [mandatory]
object info | contains the all the information you want to send to the LLM. This will be "stringyfied" and directly fed into the LLM [mandatory]

#### Response

The final message when your service request is finished. You may add an error message if no information could be found ("hide":false) or an extra prompt to the LLM (hide:true).

#### Important

When the hide attribute is set to "true", the instruction won't be shown to the user and the whole conversation/text will be fed again into the LLM. If hide is set to "false" then the instruction is shown to the user and no content is send to the LLM.

    {
        mt:    "AssistantResult",
        hide: true,
        instruction: "Some extra instructions or an error message"
    }

#### Parameters

string mt | message type [mandatory]
string instruction | final instruction to the LLM. May be an error message ("hide":false) or an extra prompt message.
boolean hide | tells the Assistant App wether or not the instruction should be shown to the user or not

## Example

The following example showcasts how an app could add the functionality to the Assistant App of displaying the calllist of the user. Therefore it adds a prompt to the system prompt of the Assistant App which announces the functionality (Previoud calls of the user) and explains how the respective costum messages (here "AssistantGetCalllist") should be created by the LLM.
The calllist entries are then fetched from the service ("GetCallList" message) and each entry is send to the Assistant App using a "AssistantInfo" message. When the last entry is fetched, or no entry was found the "AssistantResult" message is send with further instructions for the user ("hide":false) or the LLM ("hide":true).

        let app = new innovaphone.appwebsocket.Connection(start.url, start.name, null, null, appConnected);
        let assistantPluginApi = null;

        function appConnected {
             if (!assistantPluginApi) {
                assistantPluginApi = start.provideApi("com.innovaphone.assistant.plugin");
                assistantPluginApi.onmessage.attach(onApiMessage);
            }

            function onApiMessage(sender, obj) {
                switch (obj.msg.mt) {
                    case "AssistantGetPrompt":

                        let callListPrompt = {
                        header: 'Previous calls of the user',
                        prompt: '<p>If the user needs information about his/her previous calls, respond with <code>' + start.name + '</code> and include a JSON object with the count of calls. Example:' +
                                '<pre>' + start.name + ':{ "mt": "AssistantGetCalllist", "count": 100}</pre>'
                        };

                        assistantPluginApi.send({ mt: "AssistantGetPromptResult", prompt: callListPrompt }, obj.consumer, obj.src);
                        break;

                    case "AssistantGetCalllist":
                        let callsFound = false;
                        let src = new app.Src((msg) => {
                            if (msg.mt == "GetCalllistResult") {
                                let instruction = callsFound ? "<br> <h1> Instruction: </h1> Answer my question based on that new information and display it all in a nice format! " : "You don't have any recent calls";
                                assistantPluginApi.send({ mt: "AssistantResult", hide: callsFound, instruction: instruction }, obj.consumer, obj.src);
                                src.close();
                            }
                            else {
                                callFound = true;
                                assistantPluginApi.send({ mt: "AssistantInfo", info: msg.entry }, obj.consumer, obj.src);
                            }
                        }).send({ mt: "GetCalllist", count: obj.msg.count });
                        break;
                }
            }
        }