Create a custom plugin

In this step by step tutorial we will show how to create a custom Plugin and how to use with a Digital Human.

In this tutorial, we'll build a simple plugin that responds to user messages with "Hello user." To keep the example straightforward, we'll deploy the server locally and expose it using ngrok. For production deployments, you'll need to host the server on a proper hosting service.

Note: This tutorial uses Python and FastAPI, but you can use any language or framework that suits your needs.

Here's what we'll cover:

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:

code

pip install fastapi
pip install "uvicorn[standard]"

Then create a file main.py with:

code


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:

code

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.

Then in a new terminal add the token provided in your ngrok account

code

ngrok config add-authtoken <token>

Then run it providing the 8000 port

code

ngrok http 8000

This will give us a public URL that should look something like this

code

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)

code


{
    "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": "elevenlabs",
    "operationMode": "plugin",
    "ocProvider": "playground",
    "ttsVoice": "pNInz6obpgDQGcFmaJgB_eleven_flash_v2",
    "pluginOperationalModeConfig":{
            "name": "testPlugin",
            "url": <PLUGIN URL>,
            "options": {}
    }

}

Once the head is created you can test it at the: https://chat.unith.ai/[org-id]/[head-id]?api_key=[org-api-key]. The endpoint HEAD/CREATE will return a publicURL value that holds the URL of the digital human.

scheduleLast updated Feb 18, 2026