2026-10-03 03:06:55 +05:30

12 KiB

Raw Blame History

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

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

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:

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

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

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)

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

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:

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`

{
  "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):

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

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

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 {{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 sends the button suffix so the final link should be:

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

400 Invalid parameter: Body must use named parameter_name: "customer_name" — positional body params fail on this template.

Broken button URL: If the approved Meta template button URL contains a literal {{1}} prefix (e.g. https://urmiai.com/reports/{{1}}{{1}}), fix it in WhatsApp Manager → Message templates → edit button URL to https://urmiai.com/reports/{{1}} only.

Example

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",
    "report_url": "https://urmiai.com/reports/desi-clans-test/2026-10-03"
  }'

Success response `200 OK`

{
  "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

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

Per-template docs (console session required):

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

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

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

12 KiB Raw Blame History Unescape Escape

Urmiport & Agent WhatsApp APIs

End-to-end flow

Prerequisites (console setup)

1. Create a report group

2. Subscribe to the WhatsApp template

API 1 — Publish Urmiport HTML report

Endpoint

Request body

Validation rules

Example — public report (manual report ID)

Example — password-protected report

Example — auto-generated report ID

Success response 200 OK

Error responses

Public viewing

HTML capabilities

Machine-readable docs

API 2 — Send WhatsApp report notification

Endpoint

Request body

Template details — agent_run_completion

Example

Success response 200 OK

Error responses

Machine-readable docs

Complete integration example

Step 1 — Publish report

Step 2 — Send WhatsApp notification

Quick reference

Console links

12 KiB

Raw Blame History

Success response `200 OK`

Template details — `agent_run_completion`

Success response `200 OK`