Christina richard/ts webhooks example (#137)

Co-authored-by: christinapeng1 <[email protected]>
Co-authored-by: twitchard <[email protected]>

README.md

@@ -12,6 +12,7 @@ This repository contains examples of how to use the [Hume API](https://docs.hume
 | [`evi-typescript-example`](/evi-typescript-example/README.md)                           | Typescript |                 |
 | [`evi-typescript-chat-history-example`](/evi-typescript-chat-history-example/README.md) | Typescript |                 |
 | [`evi-typescript-function-calling`](/evi-typescript-function-calling/README.md)         | Typescript |                 |
+| [`evi-typescript-webhooks-example`](/evi-typescript-webhooks-example/README.md)         | Typescript | Express         |
 | [`evi-embed-vue`](/evi-embed-vue/README.md)                                             | Typescript | Vue             |
 | [`evi-python-example`](/evi-python-example/README.md)                                   | Python     |                 |
 | [`evi-python-chat-history-example`](/evi-python-chat-history-example/README.md)         | Python     |                 |

evi-python-webhooks-example/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="https://storage.googleapis.com/hume-public-logos/hume/hume-banner.png">
-  <h1>Empathic Voice Interface | Webhook Example</h1>
+  <h1>Empathic Voice Interface | Python Webhook Example</h1>
   <p>
     <strong>Receive and Handle Webhook Events from Hume's Empathic Voice Interface (EVI)</strong>
   </p>
@@ -10,7 +10,7 @@
 
 **This project demonstrates how to:**
 
-- Set up a FastAPI server to receive webhook events from Hume's Empathic Voice Interface (EVI).
+- Set up a basic FastAPI server to receive webhook events from Hume's Empathic Voice Interface (EVI).
 - Handle `chat_started` and `chat_ended` webhook events.
 - Process events to create workflows, such as generating transcripts or logging session details.
 

evi-python-webhooks-example/app.py

@@ -38,7 +38,7 @@ async def hume_webhook_handler(request: Request, event: WebhookEvent):
         # Process chat_started event
         print(f"Processing chat_started event: {event.dict()}")
 
-        # Add additional chat_started processing logic here if needed
+        # Add additional chat_started processing logic here as needed
 
     elif isinstance(event, WebhookEventChatEnded):
         # Process chat_ended event
@@ -47,7 +47,7 @@ async def hume_webhook_handler(request: Request, event: WebhookEvent):
         # Fetch Chat events, construct a Chat transcript, and write transcript to a file
         await get_chat_transcript(event.chat_id)
 
-        # Add additional chat_ended processing logic here if needed
+        # Add additional chat_ended processing logic here as needed
 
 # Run the Uvicorn server
 if __name__ == "__main__":

evi-typescript-webhooks-example/.env.example

@@ -0,0 +1 @@
+HUME_API_KEY="<YOUR_API_KEY>"

evi-typescript-webhooks-example/.gitignore

@@ -0,0 +1,31 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Secrets
+.env
+.env*.local
+
+# Generated transcripts
+transcripts/

evi-typescript-webhooks-example/README.md

@@ -0,0 +1,93 @@
+<div align="center">
+  <img src="https://storage.googleapis.com/hume-public-logos/hume/hume-banner.png">
+  <h1>Empathic Voice Interface | TypeScript Webhook Example</h1>
+  <p>
+    <strong>Receive and Handle Webhook Events from Hume's Empathic Voice Interface (EVI)</strong>
+  </p>
+</div>
+
+## Overview
+
+**This project demonstrates how to:**
+
+- Set up a basic (Node) Express server to receive webhook events from Hume's Empathic Voice Interface (EVI).
+- Handle `chat_started` and `chat_ended` webhook events.
+- Process events to create workflows, such as generating transcripts or logging session details.
+
+**Key Features:**
+
+- **Webhook integration:** Configurable endpoint to receive real-time events.
+- **Event handling:** Parse and process `chat_started` and `chat_ended` events with Python utilities.
+- **Extensibility:** A base framework for building advanced workflows triggered by EVI events.
+
+## Prerequisites
+
+To run this project locally, ensure your development environment meets the following requirements:
+
+- [Node.js](https://nodejs.org/en) (`v18.0.0` or higher)
+- [pnpm](https://pnpm.io/installation) (`v8.0.0` or higher)
+
+To check the versions of `pnpm` and `Node.js` installed on a Mac via the terminal, you can use the following commands:
+
+1. **For Node.js**, enter the following command and press Enter:
+
+```bash
+node -v
+```
+
+This command will display the version of Node.js currently installed on your system, for example, `v21.6.1`.
+
+2. **For pnpm**, type the following command and press Enter:
+
+```bash
+pnpm -v
+```
+
+This command will show the version of `pnpm` that is installed, like `8.10.0`.
+
+If you haven't installed these tools yet, running these commands will result in a message indicating that the command was not found. In that case, you would need to install them first. Node.js can be installed from its official website or via a package manager like Homebrew, and `pnpm` can be installed via npm (which comes with Node.js) by running `npm install -g pnpm` in the terminal.
+
+## Setup
+
+### Setting up credentials
+
+- **Obtain Your API Key**: Follow the instructions in the [Hume documentation](https://dev.hume.ai/docs/introduction/api-key) to acquire your API key.
+- **Create a `.env` File**: In the project's root directory, create a `.env` file if it doesn't exist. Add your API key:
+
+```sh
+HUME_API_KEY="<YOUR_API_KEY>"
+```
+
+Refer to `.env.example` as a template.
+
+### Install dependencies
+
+Install the required dependencies with pnpm: `pnpm install`
+
+## Usage
+
+### Running the server
+
+Start the Express server by running the `main.ts` file:
+
+`pnpm start`
+
+### Testing the webhook
+
+Use [ngrok](https://ngrok.com/) or a similar tool to expose your local server to the internet:
+
+`ngrok http 5000`
+
+Copy the public URL generated by ngrok and update your webhook configuration in the Hume **Config**:
+
+- **Webhook URL**: `<NGROK_PUBLIC_URL>/hume-webhook`
+- **Events**: Subscribe to `chat_started` and `chat_ended`.
+
+## How It Works
+
+1. **Webhook Endpoint**: The Express server listens for POST requests at `/hume-webhook`.
+2. **Event Processing**:
+   - `chat_started`: Logs session details or triggers workflows.
+   - `chat_ended`: Processes chat data to generate transcripts or perform analytics.
+3. **Custom Logic**: Extend the event handler functions in `main.ts` to integrate with your systems.
+

evi-typescript-webhooks-example/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "hume-evi-typescript-sample-project",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "start": "ts-node src/main.ts"
+  },
+  "dependencies": {
+    "@types/dotenv": "^8.2.3",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "hume": "^0.9.10"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.2.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}