🎨 Custom API – UI Templates

Ainisa allows you to turn raw API responses into interactive UI cards inside your web chat widget.
This means your assistant can fetch data from any API — and then display it visually using custom templates like product cards, job listings, contact results, payment cards, notifications, invoices etc.

This feature is available for web integrations (Ainisa web chat widgets).

---

🧭 Accessing UI Templates

After creating your Custom API Action, go to your actions list:

1. Open AI Actions for your assistant (from https://ainisa.com/business/agents)
2. Find the API action you want to design
3. Click the three dots (…) menu → choose Set UI Template

---

🧱 Steps to Configure UI Template

On the “Set UI Template” page, you’ll see a split view with API data on the right and your configuration form on the left.

---

1. Get API Results

Send a test request to your API endpoint to fetch real data.
Click Get Results — the API response will appear in a JSON tree viewer.

---

2. Array or Object?

• Enable Is Array if your API returns a list of items (e.g. jobs, products, orders).
• Leave it disabled if your API returns a single object with details.

---

3. Set Data Path

If your array is nested (e.g. inside data or results), you can define its path.

Example:

{
  "current_page": 1,
  "data": [ { "id": 14520, "title": "Sürücü" } ]
}

👉 Data path: data

4. Set Field Keys

After selecting your template type, you’ll need to map the fields in your template to the corresponding keys in your API response.
This is how Ainisa knows which value to display in each section of the UI card.

For example, if your API response looks like this:

{
  "id": 14520,
  "title": "Sürücü",
  "company_name": "Unicomp MMC",
  "city": {
    "title_az": "Bakı"
  },
  "min_salary": 500,
  "max_salary": 800,
  "salary_currency": "AZN",
  "image": "https://example.com/job-image.jpg"
}

Then your field mapping might look like this:

Template Field	Example JSON Key	Type	Description
Job Title Key	title	string	The title or name of the job or item
Company Name Key	company_name	string	The company or brand name
City Key	city.title_az	string	The location or city name
Minimum Salary Key	min_salary	number	Lower end of salary range
Maximum Salary Key	max_salary	number	Upper end of salary range
Currency Key	salary_currency	string	Currency symbol or code
Image Key	image	string	URL of the image to display
Job ID Key	id	number	Unique identifier for the item
View / Apply Link Key	viewLink or applyLink	string	URL for viewing or applying to the item
Salary Undefined Key	salary_undefined	boolean	Marks when salary is not specified

💡 Tip:
Use dot notation (city.title_az) to access nested object fields.
Ainisa automatically validates paths and updates the preview in real time.

When you fill in all keys correctly, the preview card on the right will render your data in the selected template layout — allowing you to instantly verify that the information appears in the right place.

See example inside chat widget: