urmi-ai/docs/URMIPORT_AND_WHATSAPP_APIS.md

# Urmiport & Agent WhatsApp APIs

This document describes the two APIs used together to **host an HTML report** and **notify a user on WhatsApp** with a link to that report.

| API | Purpose |
|-----|---------|
| **Urmiport — Publish report** | Create or update a hosted HTML report |
| **Agent messages — Send WhatsApp** | Send an approved WhatsApp template with a dynamic View Report button |

**Base URL:** `https://urmiai.com`

**Authentication:** Urmi API key in every request

```http
Authorization: Bearer urmi_live_<your_api_key>
```

Alternate header: `X-Api-Key: urmi_live_<your_api_key>`

Create API keys in the Urmi console: **Develop → API Keys**.

---

## End-to-end flow

```text
1. Console → Agent → Urmiport
   Create a report group (e.g. desi-clans-test)

2. Console → Agent → UrmiAI
   Subscribe to the agent_run_completion template

3. POST /api/v1/urmiport/reports
   Publish HTML for report_group + report_id

4. POST /api/v1/agent/messages/send
   Send WhatsApp message; button links to the hosted report

5. User opens
   https://urmiai.com/reports/{report_group}/{report_id}
```

Typical order: **publish the report first**, then **send the WhatsApp message** so the link is live when the user taps View Report.

---

## Prerequisites (console setup)

### 1. Create a report group

**Console → Agent → Urmiport → New report group**

| Setting | Description |
|---------|-------------|
| **Report group** | URL slug, 3–50 chars, lowercase letters, numbers, hyphens (e.g. `desi-clans-test`) |
| **Default access** | `public` or `password` |
| **Report ID mode** | `auto` — Urmi generates `report_id` when omitted; `manual` — you must send `report_id` in the API |

Hosted URL pattern:

```text
https://urmiai.com/reports/{report_group}/{report_id}
```

### 2. Subscribe to the WhatsApp template

**Console → Agent → UrmiAI**

Subscribe to **`agent_run_completion`** (Meta template: `agent_run_completion_v2`, display name: *Agent Run Success*).

Messages are sent from the Urmi AI WhatsApp Business number on your behalf.

---

## API 1 — Publish Urmiport HTML report

Create or update a hosted HTML report. The public page renders **only your HTML** — no Urmi branding or chrome.

### Endpoint

```http
POST /api/v1/urmiport/reports
Content-Type: application/json
Authorization: Bearer urmi_live_<your_api_key>
```

### Request body

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `report_group` | Yes | string | Report group slug created in Urmiport (e.g. `desi-clans-test`) |
| `body` | Yes | string | Full HTML document or fragment (email-style HTML is supported) |
| `report_id` | Conditional | string | Report postfix. **Required** when the group uses manual ID mode; optional for auto groups |
| `access` | No | string | `public` (default) or `password` |
| `password` | Conditional | string | Required when `access` is `password`, unless the group already has a default password |

### Validation rules

- **report_group:** 3–50 chars, lowercase `a-z`, `0-9`, hyphens; must already exist in your account
- **report_id:** letters, numbers, dots, underscores, hyphens; max 120 chars
- **Upsert:** same `report_group` + `report_id` updates the existing HTML body

### Example — public report (manual report ID)

```bash
curl -X POST 'https://urmiai.com/api/v1/urmiport/reports' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_group": "desi-clans-test",
    "report_id": "desi-clans-demo-v1",
    "access": "public",
    "body": "<html><body><h1>Agent run complete</h1><p>All checks passed.</p></body></html>"
  }'
```

### Example — password-protected report

```bash
curl -X POST 'https://urmiai.com/api/v1/urmiport/reports' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_group": "desi-clans-test",
    "report_id": "run-confidential-001",
    "access": "password",
    "password": "my-secret-pass",
    "body": "<html><body><h1>Confidential report</h1></body></html>"
  }'
```

### Example — auto-generated report ID

When the report group uses **auto** ID mode, omit `report_id`:

```bash
curl -X POST 'https://urmiai.com/api/v1/urmiport/reports' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_group": "acme-agent-runs",
    "access": "public",
    "body": "<html><body><h1>Run complete</h1></body></html>"
  }'
```

Urmi returns a generated `report_id` such as `run-a1b2c3`.

### Success response `200 OK`

```json
{
  "success": true,
  "id": "11926afa-c648-48f2-909e-67434f878232",
  "report_group": "desi-clans-test",
  "report_id": "desi-clans-demo-v1",
  "access": "public",
  "password_protected": false,
  "url": "https://urmiai.com/reports/desi-clans-test/desi-clans-demo-v1",
  "created_at": "2026-10-02T17:13:32.468390Z",
  "updated_at": "2026-10-02T17:13:32.468390Z"
}
```

### Error responses

| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid API key |
| `404` | Report group not found — create it in Console → Agent → Urmiport |
| `422` | Validation error (invalid slug, missing `report_id` for manual groups, missing password, etc.) |

### Public viewing

| Access | Behaviour |
|--------|-----------|
| **Public** | `GET https://urmiai.com/reports/{report_group}/{report_id}` renders HTML directly |
| **Password** | User sees a password gate; after unlock, only your HTML is shown |

Internal metadata endpoint (no auth):

```http
GET /api/v1/urmiport/view/{report_group}/{report_id}
POST /api/v1/urmiport/view/{report_group}/{report_id}/unlock
```

### HTML capabilities

Reports support plain **HTML, CSS, and JavaScript** — including charts, tables, branding, and client-side animations. Complex dashboards (canvas charts, live counters, responsive layouts) are supported.

### Machine-readable docs

```http
GET /api/v1/urmiport/docs
GET /api/v1/urmiport/reports/docs
```

Also available in the console: **Agent → Urmiport** and **Develop → API Explorer**.

---

## API 2 — Send WhatsApp report notification

Send an approved agent WhatsApp template. The template includes a **View Report** button whose URL is built from `report_group` and `report_id`.

### Endpoint

```http
POST /api/v1/agent/messages/send
Content-Type: application/json
Authorization: Bearer urmi_live_<your_api_key>
```

### Request body

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `template` | Yes | string | Subscribed template slug. Use `agent_run_completion` |
| `to` | Yes | string | Recipient WhatsApp number with country code, no `+` (e.g. `919149154337`) |
| `customer_name` | Yes | string | Name inserted into the template body greeting |
| `report_group` | Yes | string | Urmiport report group slug (same as in publish API) |
| `report_id` | No | string | Report postfix. If omitted, Urmi auto-generates one (e.g. `run-a1b2c3`) |

### Template details — `agent_run_completion` → Meta `agent_run_completion_v2`

| Property | Value |
|----------|-------|
| **API slug** | `agent_run_completion` |
| **Meta template name** | `agent_run_completion_v2` |
| **Header** | Agent Run Successful |
| **Body** | Hello {{customer_name}}, your agent run is complete… |
| **Button** | View Report → `https://urmiai.com/reports/{{1}}` |

| Component | Meta format | API field | Example |
|-----------|-------------|-----------|---------|
| Body | **Named** `customer_name` | `customer_name` | `Team Desi Clans` |
| Button URL | Positional `{{1}}` suffix | `report_group` + `report_id` | `desi-clans-test/2026-10-03` |

Urmi builds the button suffix as `{report_group}/{report_id}` from the API request — **not** from any posted URL. The response includes `report_url` for convenience only.

Final link: `https://urmiai.com/reports/desi-clans-test/2026-10-03`

### Example

```bash
curl -X POST 'https://urmiai.com/api/v1/agent/messages/send' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "agent_run_completion",
    "to": "919149154337",
    "customer_name": "Suyash",
    "report_group": "desi-clans-test",
    "report_id": "2026-10-03"
  }'
```

### Success response `200 OK`

```json
{
  "success": true,
  "template": "agent_run_completion",
  "to": "919149154337",
  "customer_name": "Suyash",
  "report_group": "desi-clans-test",
  "report_id": "2026-10-03",
  "report_url": "https://urmiai.com/reports/desi-clans-test/2026-10-03",
  "wa_message_id": "wamid.HBg...",
  "dispatch_id": "00000000-0000-0000-0000-000000000001"
}
```

### Error responses

| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid API key |
| `403` | Template not subscribed — subscribe in Console → Agent → UrmiAI |
| `422` | Invalid phone number, `report_group`, or `report_id` format |
| `502` | Meta WhatsApp API error (template mismatch, WABA issue, etc.) |

### Machine-readable docs

```http
GET /api/v1/agent/messages/docs/send
```

Per-template docs (console session required):

```http
GET /api/v1/agent-templates/agent_run_completion/docs
```

Also available in the console: **Agent → UrmiAI → API docs** and **Develop → API Explorer**.

---

## Complete integration example

Publish a report, then notify the user on WhatsApp with the same `report_group` and `report_id`.

### Step 1 — Publish report

```bash
curl -X POST 'https://urmiai.com/api/v1/urmiport/reports' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_group": "desi-clans-test",
    "report_id": "desi-clans-demo-v1",
    "access": "public",
    "body": "<html><head><style>body{font-family:sans-serif;background:#0b1020;color:#fff;padding:24px}</style></head><body><h1>Desi Clans — Run complete</h1><p>All systems operational.</p></body></html>"
  }'
```

Report URL: `https://urmiai.com/reports/desi-clans-test/desi-clans-demo-v1`

### Step 2 — Send WhatsApp notification

```bash
curl -X POST 'https://urmiai.com/api/v1/agent/messages/send' \
  -H 'Authorization: Bearer urmi_live_<your_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "agent_run_completion",
    "to": "919149154337",
    "customer_name": "Suyash",
    "report_group": "desi-clans-test",
    "report_id": "desi-clans-demo-v1"
  }'
```

The recipient receives a WhatsApp message with a **View Report** button pointing to the hosted report.

---

## Quick reference

| Item | Value |
|------|-------|
| Base URL | `https://urmiai.com` |
| Publish report | `POST /api/v1/urmiport/reports` |
| Send WhatsApp | `POST /api/v1/agent/messages/send` |
| Report URL | `https://urmiai.com/reports/{report_group}/{report_id}` |
| Template slug | `agent_run_completion` |
| Auth header | `Authorization: Bearer urmi_live_<key>` |

---

## Console links

| Task | Location |
|------|----------|
| Create report groups | Console → Agent → Urmiport |
| Subscribe WhatsApp template | Console → Agent → UrmiAI |
| Create API keys | Console → Develop → API Keys |
| Try APIs interactively | Console → Develop → API Explorer |

urmi_live_a9d92e7be1584e24aa361cb09075794a_FWsjx04IW3Z2Enqx4Lg0EybTqCYsa0Dk