API
How to guides

Create a custom plugin

7min

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 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:

  1. Implement a FastAPI server with a POST endpoint that will parse the input message and generate the reponse.
  2. Run the server locally and use ngrok to expose the plugin publicly.
  3. 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:

Text


Then create a file main.py with:

Python


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:

Bash


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

Text


Then run it providing the 8000 port

Text


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

Text


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)

JSON


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]",