This recipe walks end-to-end:
  1. Create the agent in the dashboard
  2. Ground answers with a knowledge base
  3. Wire HTTP actions to the fintech-api backend for wallet balance, spending/income insights, and transaction status
  4. Deploy the SaaS chat widget
  5. Embed the widget in your Next.js web app
The reference backend lives at fintech-api/ in the Chatropic repo (port 8083). The reference frontend is chatropic-demo-web/. You can swap in your own API URLs, the dashboard setup is the same.

What you are building


Prerequisites

1

Start Postgres

From the Chatropic repo root:
2

Run fintech-api

Verify: curl http://localhost:8083/health, {"status":"ok"}On first boot the API runs migrations and seeds from seed/wallet_seed.json.
3

Demo credentials

4

Chatropic dashboard

Open the playground dashboard (default http://localhost:3000) and sign in to your workspace.

Step 1, Create the agent

1

Create workspace

Sign in and open (or create) a workspace for your fintech product.
2

Set product type

Use Customer Support (or your configured product) so the agent can combine knowledge retrieval with HTTP actions.
3

Open Playground

In Playground, set the display name (for example Wallet Assistant), welcome message, and suggested prompts (see Step 6).

Step 2, Knowledge base setup

Ground policy and UX answers so the agent does not guess when no API call is needed.
1

Open Documents

Documents, choose Text or Files.
2

Add fintech FAQ content

Paste or upload content covering:
  • What Completed vs Failed transaction status means
  • How income vs spending is classified (deposits, exchanges, card top-ups)
  • Supported insight periods (7d, 30d, 90d, 1y)
  • Security: the agent never asks for full card numbers or passwords in chat
  • Escalation: when to offer human support for disputed charges
3

Example FAQ snippet

4

Test retrieval

New test session, ask “What does a failed transaction mean?”, answer should cite your document, not invent policy.

Data sources

Website crawl, file upload, and text paste options.

Step 3, Manage tokens (API authentication)

Wallet endpoints require Authorization: Bearer <jwt>. Configure credentials under Manage tokens.
Best for local Playground testing against the seeded demo user.
1

Obtain a demo JWT

2

Create static token

Manage tokens: new Static token
JWTs expire (default 24h). Refresh the token in Manage tokens when Playground tests start returning 401.
3

Use in action headers

On each HTTP action, add:

Manage tokens

Static vs customer-login credentials.

Step 4, Actions setup

Create four API actions under Available actions: create an API action.

Action summary

Base URL for local dev: http://localhost:8083 Headers (all actions):
Use the header that matches the token you configured in Step 3.

How the agent fills query parameters

Several fintech actions use URL placeholders such as {{period}} or path segments like {{transaction_id}}. The agent never hand-builds the URL, it fills Parameters on the action, and Chatropic substitutes them before the HTTP call.
1

Declare parameters on the action

On each action’s configure page, set Parameters (JSON Schema). Property names must match the placeholders in the URL (period, direction, transaction_id).Use enum for fixed API values (e.g. 7d, 30d, 90d, 1y) so the planner picks valid query values. Mark fields required when the API needs them.
2

Planner picks the action and values

Each turn, the agent reads the user’s message and enabled action descriptions. When a message matches (e.g. “How much did I spend this month?”), it selects get_spending_income_insights and sets action_params, inferring period: "30d" from phrases like “this month” or “last 30 days”.
3

Substitute into the request

Before calling fintech-api, Chatropic replaces {{period}} (and other placeholders) in the URL with resolved values. Literals in the URL, such as include_insights=true: are sent on every call and do not need a parameter.
4

Ask when something is missing

If a required parameter is still empty (e.g. user asks “Why did my payment fail?” without an id), the agent asks one follow-up question (“Which transaction, do you have an id or title?”), remembers the answer across turns, then retries the action.
5

Param mapping (usually skip for this demo)

Param mapping is only needed when API query names differ from your parameter names (e.g. map action period, API time_range). For fintech-api, names match the placeholders, leave Param mapping empty.
Use the action Test panel with sample parameters (e.g. period: "30d") to verify URL substitution before testing in Playground.

4a, get_wallet_overview


4b, get_spending_income_insights

Paste into Parameters on the action configure page:
The agent maps natural language to these values, “this month”, 30d, “last week”, 7d. If the user does not mention a range, the agent defaults to 30d or asks which period they mean.
Add query params for narrower questions:
If the user says “this month” without a exact range, default period to 30d and confirm in the reply.

4c, list_transactions

Both query params are optional for the API; omit direction to return all transactions in the period.
Example: “Show recent deposits”, direction: "income", period: "30d" (default).

4d, get_transaction_status

If the user does not supply an id, the agent typically calls list_transactions first or asks which payment they mean, then calls this action with the resolved transaction_id.
Use Response mapping if you attach a transaction detail widget and want to map $.details.rows into card fields.

Skills

HTTP action fields and test panel.

Action chaining

Chain list, pick, detail flows.

Step 5, Agent instructions & suggested prompts

1

Suggested prompts

Playground or the Content tab on Chat widget: add chips such as:
  • What’s my balance?
  • Spending this month
  • Show income last 7 days
  • Why did my last payment fail?
2

Behavior hints

Add a short Text source to steer behavior:
For insight questions, call get_spending_income_insights with the closest period (7d, 30d, 90d, 1y). For a single payment, call get_transaction_status. Combine API results with knowledge base policy text. Never request passwords or full card numbers in chat.
3

Guardrails

Security settings: block investment advice or out-of-scope topics if needed; add Escalate to human for disputes.

Step 6, Test in Playground

1

New test session

New test session before each test run.
2

Balance

Ask “What’s my USD balance?”, agent calls get_wallet_overview, replies with USD 18.
3

Spending insights

Ask “How much did I spend in the last 30 days?”, get_spending_income_insights with period=30d, spending total 2.00, income 20.00, net 18.
4

Transaction status

Ask “What happened to my failed deposit?”, agent lists or asks which transaction, get_transaction_status for id 3, explains Failed status.
5

Knowledge-only

Ask “What does failed status mean?”, answer from Documents without calling an action.
Check each action’s Test panel to confirm URLs and response bodies, and your API’s server logs for the incoming requests.

Step 7, Deploy the SaaS widget

1

Open SaaS app deploy

SaaS app: configure display name Wallet Assistant, primary color (e.g. #3b52ee), welcome message, and suggested prompts from Step 5.
2

Content & Style

Match your fintech brand in the SaaS app style tab (same widget config as Chat widget).
3

Choose layout

4

Copy embed snippet

Deploy snippets use an API-key embed URL, and widget styling loads from the workspace linked to that publishable key:
Only runtime params stay in the URL: mode, endUser, identity (signed-in users), and session (Playground preview only).
5

Verify

Open side drawer demo (SaaS app) or Open floating launcher demo (Chat widget), send a test message, confirm Chat logs.
Production embed snippets omit a pinned session param so each visitor gets an anonymous thread. For logged-in SaaS users, append endUser and identity dynamically, see SaaS app.

SaaS app

Drawer setup, identity params, and channel keys.

Step 8, Integrate into your web app

Use the chatropic-demo-web Next.js app as the reference host. After a user signs in, register their fintech session with your agent BFF, then mount the SaaS drawer so the assistant can resolve {{end_user_id}} to the correct wallet.
1

Environment variables

In chatropic-demo-web/.env.local:
Or set NEXT_PUBLIC_CHATROPIC_PUBLISHABLE_KEY: the demo app builds https://chatropic.com/embed/key/{publishable-key} and appends mode=drawer, endUser, and identity at runtime.Wire the wallet action to your BFF (one-time):
2

Register agent sessions

After login, POST the user’s fintech id and JWT to your BFF:Client helpers live in src/lib/agent-session-client.ts (registerAgentSession, unregisterAgentSession). The reference app registers on login, wallet refresh, and when ChatropicDrawer mounts.
3

SaaS drawer component

ChatropicDrawer loads the embed iframe with mode=drawer, endUser, and a signed identity JWT:
See src/lib/chatropic-config.ts for URL building and src/app/api/chatropic/identity/route.ts for JWT signing.
4

Mount on dashboard layout

In your authenticated shell (app-shell.tsx), render the drawer when embed env vars are set and a session exists. Add Log out in the sidebar, it calls unregisterAgentSession, clears localStorage, and redirects to /login.
5

End-to-end check

  1. Run fintech-api (:8083), customer-agent (:8000), playground (:3000), and chatropic-demo-web (:3001)
  2. Log in with alex.smith@demo.com / Demo1234!
  3. Open the right-side drawer, ask “What’s my balance?”
  4. In the chatropic-demo-web server logs, confirm the wallet call arrives at http://localhost:3001/api/agent/wallet with X-End-User-Id set to the fintech user UUID (not the demo-... chat session id)
  5. Reply should show USD 18 from fintech-api

Authentication & identity

The same identity pattern in the React Native SDK.

Actions & UI payloads

How structured action payloads render in chat.

Navigation routes

Deeplink to /transactions, /settings, etc. from chat cards.

API reference (fintech-api)

Optional query params for insights: period (7d | 30d | 90d | 1y), direction (income | spending), from, to, include_insights. Seed data: fintech-api/seed/wallet_seed.json

Troubleshooting

Helpdesk recipe

Similar pattern for support FAQ + ticket APIs.

Build your first agent

Dashboard primer if you’re new to Chatropic.