# AskAvatar Webhook Integration Guide

This document outlines how external applications, bots, donation platforms, or custom scripts can communicate with AskAvatar via HTTP Webhook.

---

## 1. Overview & Architecture

AskAvatar runs an embedded local HTTP server while the application is active. This allows third-party tools (such as Streamlabs/StreamElements webhooks, Ko-fi relays, Patreon bots, Discord bots, Shopify/merch stores, or custom developer scripts) to send events directly to AskAvatar on the local machine.

When a webhook event is received:
1. AskAvatar validates the event payload.
2. The event is evaluated against the user's active **Thresholds** (minimum amounts, enabled/disabled categories).
3. If valid, it triggers:
   - **Simultaneous Media Animations** (if configured for that trigger type), or
   - **Avatar Speech & Alert Queue** (AI persona voice response, TTS, enter/exit animations, and sound effects).

---

## 2. Endpoint Details

- **URL:** `http://127.0.0.1:48080/webhook`
- **HTTP Method:** `POST`
- **Request Headers:**
  - `Content-Type: application/json`
- **Response:**
  - Status `200 OK`
  - Body: `{"ok": true}`

> **Note:** The webhook server listens strictly on `127.0.0.1` (localhost) for security. If receiving webhooks from an external cloud service (like Stripe or PayPal), run a local relay bot or tunnel (e.g. ngrok/Cloudflare Tunnel) pointing to port `48080`.

---

## 3. Payload Schema

Send a JSON object with any of the following fields:

| Field Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `type` | `string` | **Yes** | The trigger event identifier (case-insensitive). See full list below. |
| `user` | `string` | Optional | Display name of the viewer/donor. *(Aliases: `name`, `username`)*. Defaults to `"Someone"` if omitted. |
| `amount` | `number` \| `string` | Optional | Numerical amount or value. *(Aliases: `value`, `bits`, `viewers`, `count`, `total`)*. Currency symbols and commas are automatically stripped (e.g., `"$10.00"` or `10`). |
| `message` | `string` | Optional | Viewer's message/comment to be displayed and spoken by the avatar. |
| `currency` | `string` | Optional | ISO currency code (e.g., `"USD"`, `"GBP"`, `"EUR"`). |

---

## 4. Supported Event Types (`type`)

AskAvatar recognizes the following values for the `type` field:

### Universal / Platform-Agnostic
- **Donation / Tip:** `"tip"`, `"donation"`
- **Subscription:** `"sub"`, `"subscription"`, `"resub"`
- **Gifted Subscription:** `"gift"`, `"mysterygift"`, `"gifted sub"`
- **Follower:** `"follow"`, `"follower"`
- **Raid:** `"raid"` *(amount taken from `viewers`, `raiders`, or `amount`)*
- **Twitch Bits / Cheers:** `"bits"`, `"cheer"`
- **YouTube Superchat:** `"superchat"`
- **YouTube Membership:** `"member"`, `"membership"`
- **Merchandise Purchase:** `"merch"`

### Kick-Specific
- `"kick-sub"`
- `"kick-gift"`
- `"kick-raid"`

### TikTok-Specific
- `"tiktok-gift"`
- `"tiktok-follow"`
- `"tiktok-share"`
- `"tiktok-like"`

---

## 5. Sample Payloads

### A. Tip / Donation
```json
{
  "type": "tip",
  "user": "PixelArtisan",
  "amount": 10.00,
  "currency": "USD",
  "message": "Awesome stream! Keep up the great work!"
}
```

### B. Tier 1 Subscription / Resub
```json
{
  "type": "sub",
  "user": "StarGazer",
  "message": "6 months and going strong!"
}
```

### C. Gifted Subscriptions
```json
{
  "type": "gift",
  "user": "GenerousGamer",
  "amount": 5,
  "message": "Enjoy the subs everyone!"
}
```

### D. Stream Raid
```json
{
  "type": "raid",
  "user": "RetroGamer",
  "viewers": 85
}
```

### E. Twitch Bits / Cheer
```json
{
  "type": "bits",
  "user": "CryptoKnight",
  "amount": 500,
  "message": "Cheer500! Let's go!"
}
```

---

## 6. Code Integration Examples

### cURL (Command Line / Terminal)
```bash
curl -X POST http://127.0.0.1:48080/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "donation",
    "user": "CommanderKeen",
    "amount": 25.00,
    "currency": "USD",
    "message": "Here is some support for the stream!"
  }'
```

### JavaScript / Node.js (`fetch`)
```javascript
const eventData = {
  type: 'tip',
  user: 'CyberSamurai',
  amount: 15.50,
  currency: 'USD',
  message: 'Love the avatar reactions!'
};

fetch('http://127.0.0.1:48080/webhook', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(eventData)
})
  .then(res => res.json())
  .then(data => console.log('AskAvatar response:', data))
  .catch(err => console.error('Error triggering AskAvatar:', err));
```

### Python (`requests`)
```python
import requests

payload = {
    "type": "raid",
    "user": "NeonValkyrie",
    "viewers": 120
}

response = requests.post("http://127.0.0.1:48080/webhook", json=payload)
print(response.json())
```