whatsapp fixes
This commit is contained in:
parent
ff01efe4bb
commit
248acba741
5 changed files with 425 additions and 38 deletions
365
docs/URMIPORT_AND_WHATSAPP_APIS.md
Normal file
365
docs/URMIPORT_AND_WHATSAPP_APIS.md
Normal file
|
|
@ -0,0 +1,365 @@
|
|||
# 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`** (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`) |
|
||||
| `report_url` | No | string | Full hosted report URL override. Auto-built as `https://urmiai.com/reports/{report_group}/{report_id}` when omitted |
|
||||
|
||||
### Template details — `agent_run_completion`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Slug** | `agent_run_completion` |
|
||||
| **Meta template name** | `agent_run_completion` |
|
||||
| **Header** | Agent Run Complete |
|
||||
| **Body** | Hello {{1}}, your agent run is complete… |
|
||||
| **Button** | View Report → `https://urmiai.com/reports/{{1}}` |
|
||||
|
||||
The Meta template uses **positional** variables (not named):
|
||||
|
||||
| Variable | Maps to API field | Example |
|
||||
|----------|-------------------|---------|
|
||||
| `{{1}}` (body) | `customer_name` | `Suyash` |
|
||||
| `{{1}}` (button) | `report_group`/`report_id` path suffix | `desi-clans-test/2026-10-03` |
|
||||
|
||||
Urmi sends the button suffix `desi-clans-test/2026-10-03` so the final link is:
|
||||
|
||||
`https://urmiai.com/reports/desi-clans-test/2026-10-03`
|
||||
|
||||
> **Common bug:** If body parameters are sent as named (`parameter_name`) instead of positional, Meta leaves `{{1}}` literal in the URL, producing broken links like `https://urmiai.com/reports/%7B%7B1%7D%7Ddesi-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": "desi-clans-demo-v1"
|
||||
}'
|
||||
```
|
||||
|
||||
### 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue