UNITHdocs
Sign inarrow_forward
API

n8n Integration

This guide explains how to integrate UNITH Digital Humans with n8n, a powerful automation platform, using Webhooks. This allows Digital Humans to send collected conversation data to an external system for processing and dynamic response.

Although UNITH does not currently provide a native integration with n8n (as we do with Zapier), this approach enables full interoperability and automation capabilities using HTTP POST requests and n8n's flexible workflow engine.

We’re actively working on a native n8n app as well, which will be available soon to make integration even easier.

What is n8n?

n8n is a fair-code licensed workflow automation tool that enables you to connect various systems, APIs, and databases using a visual, node-based interface. You can self-host it or run it in the cloud. Workflows are built by chaining nodes like Webhooks, HTTP requests, databases, emails, and more.

In the context of Unith, n8n is ideal for:

  • Capturing structured data from Digital Humans
  • Storing or forwarding data to CRMs, databases, or ticketing systems
  • Sending dynamic responses back to the Digital Human during a conversation

Use Case

Enable a Digital Human in OC Mode to send structured user data—like name, email, or issue descriptions—to an n8n Webhook, which processes the data and optionally returns a custom response to the avatar in real time.

Architecture Flow

code
[User interacts with the Digital Human]
        ↓
[The LLM detects a trigger based on prompt instructions]
        ↓
[The Digital Human activates a Tool → sends POST request]
        ↓
[n8n receives the POST via Webhook node]
        ↓
[n8n processes data (optional: triggers external actions)]
        ↓
[n8n returns a JSON response via the Respond to Webhook node]

Prerequisites

To proceed, you will need:

  • A Unith Digital Human with OC (Open Conversation) Mode enabled.
  • Access to the UNITH API.
  • A running instance of n8n (locally or hosted).
  • Optionally, ngrok for exposing local n8n endpoints to the internet.

Step 1: Set Up Your Webhook in n8n

  1. Open your n8n editor.
  2. Add a Webhook node to your workflow.
  3. Configure it as follows:
    • HTTP Method: POST
    • Path: create-ticket (you can choose your own path)
    • Response Mode: Using "Respond to Webhook" node
  4. Activate the workflow to generate the public URL (e.g. https://your-subdomain/webhook/create-ticket).
  5. Copy this URL — it will be used in the Tool definition in the next step.

⚠️ n8n will automatically generate the full Webhook URL based on your instance's environment and the path you define.

Step 2: Define a Tool for the Digital Human

Tools allow the LLM to invoke external services during a conversation. You'll define a Tool that sends a POST to your n8n webhook.

Tool JSON Example

code

{
  "conversationSettings": {
    "tools": [
      {
        "name": "Create_Ticket",
        "description": "Submit a support ticket with user-provided information",
        "parameters": [
          { "name": "userName", "type": "string", "description": "User's full name" },
          { "name": "userEmail", "type": "string", "description": "User's email address" },
          { "name": "userIssue", "type": "string", "description": "Issue description" }
        ],
        "url": "https://your-subdomain/webhook/create-ticket"
      }
    ]
  }
}

Apply the Tool using the UNITH API

code

curl -X PUT \
  'https://platform-api.unith.ai/head/<HEAD_ID>/conversation-settings' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<YOUR_TOOL_JSON>'

Replace:

  • <HEAD_ID> with your Digital Human's ID.
  • <YOUR_API_TOKEN> with your authenticated bearer token.
  • <YOUR_TOOL_JSON> with the JSON structure shown above.

Step 3: Define Prompt Instructions

The prompt must clearly guide the LLM on when and how to invoke the Tool.

Example:

If the user wants to open a support ticket, collect their name, email, and a description of the issue. As soon as the user provides the issue description, immediately call the Create_Ticket tool with the parameters 'name', 'email' and 'issueDescription'.

Make sure the parameter names in the prompt match those defined in the Tool's configuration.

Step 4: Build the n8n Workflow

A basic setup may include the following nodes:

code

[Webhook (POST)]
      ↓
[Optional: call APIs, write to database, send email]
      ↓
[Respond to Webhook]

Set Node Configuration Example

Create a JSON output like:

code

{
  "message": "Tell the user: Thank you, {{ $json.userName }}. We have received your issue: '{{ $json.userIssue }}'."
}

This message will be returned directly to the Digital Human and it will be used in the conversation.

Respond to Webhook Node

  • Status Code: 200
  • Response Data: First Entry JSON
  • Content-Type: application/json

Step 5: Testing & Validation

Once your Webhook node is configured and your workflow is activated, you can test whether your Digital Human’s Tool is correctly reaching n8n:

  • Go to your Webhook node in n8n.
  • Click "Execute Node".
  • n8n will go into "listening" mode and wait for an incoming request.
  • Use ngrok if running n8n locally to get a public URL.
  • Trigger the tool in a conversation to simulate a live request.
  • Monitor incoming requests and responses via http://localhost:4040 (if you are using ngrok UI).

You can also check n8n’s execution logs to debug or monitor workflows.

Summary

For more advanced use cases, n8n can also:

  • Store data in Google Sheets, Airtable, Notion, or databases.
  • Trigger ticket creation in platforms like Zendesk or Jira.
  • Send confirmation emails to users.
  • Integrate with CRM systems or internal APIs.

Need Assistance?

Feel free to contact the UNITH Support team at support@unith.ai.

scheduleLast updated Jun 11, 2025