API
How to guides
Create a custom plugin
7 min
in this step by step tutorial we will show how to create a custom conversational plugins docid\ ey7zhhhop3n1hv pgqks9 and how to use with a digital human in this tutorial we will implement a simple plugin that responds to user messages with a fixed "hello user" in order to keep the example simple, we'll deploy the server locally and expose it using ngrok for production you will need to host the server somewhere note that we'll use python and fastapi but you can use any language or framework if that's more convenient to achieve that we'll do the following implement a fastapi server with a post endpoint that will parse the input message and generate the reponse run the server locally and use ngrok to expose the plugin publicly create a digital human that uses the plugin 1\ the server to implement the server using fastapi you need the python packages that you can install with pip pip install fastapi pip install "uvicorn\[standard]" then create a file main py with from typing import union, list, annotated from fastapi import fastapi, path, body from pydantic import basemodel class payload(basemodel) type str message str class pluginmessage(basemodel) type str payload payload app = fastapi() @app post("/conversation/{userid}/message") def post message(userid annotated\[str, path()], body annotated\[list\[pluginmessage], body()]) user message = "" if len(body) body = body\[0] user message = body payload message plugin response = \[ pluginmessage( type="text", payload=payload(type="text", message=f"hello user, you said {user message}!")) ] return plugin response this server implements a post endpoint that validates the input message and creates and returns the response message that includes the input message 2\ run locally and expose using ngrok to run the server locally launch the following command from bash uvicorn main\ app reload at this point the server is running locally at http //127 0 0 1 8000 now we will need a public endpoint for this plugin to register it with the digital human in a production setting you will need to deploy the server somewhere and host it but for the sake of the tutorial, we will just use a ngrok, that will be useful for testing first create a ngrok account and install it following the instructions here https //ngrok com/download then in a new terminal add the token provided in your ngrok account ngrok config add authtoken \<token> then run it providing the 8000 port ngrok http 8000 this will give us a public url that should look something like this https //0246 140 228 56 51 ngrok free app 3\ create a digital human registered with the plugin in order to create a digital human an register the plugin you have to use the /head/create endpoint of the unith api use the following parameters in the post /head/create endpoint as reference replace the \<head visual id> with the head visual of your choice replace \<plugin url> with the ngrok url (e g https //0246 140 228 56 51 ngrok free app https //0246 140 228 56 51 ngrok free app ) { "headvisualid" \<head visual id>, "suggestions" \[], "name" "my plugin example", "alias" "my plugin example", "greetings" "hello, this is a welcome message ", "language" "en us", "languagespeechrecognition" "en us", "phrases" \[ ], "ttsprovider" "audiostack", "operationmode" "plugin", "ocprovider" "playground", "ttsvoice" "carmela", "pluginoperationalmodeconfig" { "name" "testplugin", "url" \<plugin url>, "options" {} } } once the head is created you can test it at the "publicurl" " https //chat unith ai/\[org id]/\[head id]?api key=\[org api key] https //chat unith ai/\[org id]/\[head id]?api key=\[org api key] ",