Pricepally ecommerce agent

This recipe walks end-to-end:

Run the pricepally-api reference backend
Create the agent in the dashboard
Ground answers with a knowledge base (delivery, payments, seasons)
Wire a Skill for search products, add to cart, and track order status
Deploy the Mobile app profile and embed in React Native

The reference backend lives at pricepally-api/ in the Chatropic repo (port 8084). The reference mobile shell is examples/react-native-demo/. Swap in your own API base URL, the dashboard action setup is the same.

What you are building

User intent	Agent behavior
”Do you have ginger?”	Calls `search_products` with `q=ginger`
”Add onions to my cart”	Resolves product id, calls `add_to_cart`
”Where is order 00A49291044D1?”	Calls `get_order_status` with `order_id`
Delivery / payment FAQ	Answers from Documents (no action)

API reference (pricepally-api)

All protected routes require Authorization: Bearer <jwt> from POST /api/auth/login.

Capability	Method	Endpoint	Notes
Login	POST	`/api/auth/login`	Returns JWT + user
Search / list products	GET	`/api/products?q={{query}}`	Optional `q` filters by product name (case-insensitive). Omit `q` to return the full catalog.
Track order status	GET	`/api/orders?order_id={{order_id}}`	Optional `order_id` filters to one order. Omit to list all orders for the user.
Add to cart	POST	`/api/cart/items`	JSON body. Use `Accept: application/json` for Chatropic actions. Mobile app uses SSE.
Live cart (mobile)	GET	`/api/cart/stream`	SSE, used by the RN cart tab, not typical for HTTP actions

Agent BFF routes (signed-in users)

When each shopper has their own JWT, point Chatropic actions at /api/agent/* instead of calling protected routes with a shared token. The BFF validates a static service token, reads X-End-User-Id, looks up that user’s Pricepally JWT from the session store, and proxies the request.

Capability	Method	BFF endpoint
Search products	GET	`/api/agent/products?q={{query}}`
Add to cart	POST	`/api/agent/cart/items`
Order status	GET	`/api/agent/orders?order_id={{order_id}}`
Register session	POST	`/api/agent/session`: called by your app after login (`{ userId, token }`)
Clear session	DELETE	`/api/agent/session`: called on logout (`{ userId }`)

BFF headers (on every agent action):

Authorization: Bearer {{token.pricepally_bff}}
X-End-User-Id: {{end_user_id}}

There is no separate /api/products/search route. Product search is implemented as GET /api/products with the q query parameter. Order lookup uses GET /api/orders with order_id: there is no GET /api/orders/:id path segment.

Prerequisites

Start Postgres

From the Chatropic repo root:

docker compose up -d postgres

Run pricepally-api

cd pricepally-api
cp .env.example .env
go mod tidy
go run ./cmd/server

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

Demo credentials

Field	Value
Email	`ada@pricepally.demo`
Password	`Demo1234!`
Catalog	Ugu, Onions, Ginger, Okro (Naira prices)
Orders	4 seeded orders (Delivered / Processing)

Obtain a JWT for action testing

curl -s -X POST http://localhost:8084/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@pricepally.demo","password":"Demo1234!"}'

Copy token from the response, use it when testing actions in the dashboard.

Chatropic dashboard

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

Step 1, Create the agent

Create workspace

Set product type

Use Customer Support so the agent can combine knowledge retrieval with HTTP actions.

Open Playground

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

Step 2, Knowledge base setup

Ground delivery, payment, and policy answers so the agent does not invent storefront rules.

Add FAQ documents

Documents: paste or upload content such as:

## Delivery
Orders are delivered to Lagos and Abuja metro areas. Processing orders ship within 2 business days.

## Payments
We accept card payments and bank transfer via Paystack at checkout.

## Seasonal produce
Items marked "In Season" are freshest this week. "Off Season" items may have limited stock or higher prices.

Smoke test retrieval

New test session, ask “What payment methods do you accept?”, answer should cite your document.

Step 3, Authentication for actions

pricepally-api protects catalog, cart, and order routes with JWT. Pick one pattern:

Pattern	Best for
Demo static JWT	Playground only, one shared demo user
Agent BFF	Signed-in mobile or web app, recommended for production demos
Customer login token	OAuth-style sign-in inside chat (no app session store)

Demo (static JWT)
Agent BFF (signed-in app)
Customer login (OAuth)

curl -s -X POST http://localhost:8084/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@pricepally.demo","password":"Demo1234!"}'

Save static token

Manage tokens: new Static token

Field	Value
Name	`pricepally_demo_jwt`
Value	Paste the `token` from login

Use in action headers

On each HTTP action:

Authorization: Bearer {{token.pricepally_demo_jwt}}

Point actions at /api/products, /api/cart/items, /api/orders (not /api/agent/*).

Recommended for examples/react-native-demo and any app where users sign in before chatting. The app stores each user’s Pricepally JWT server-side; Chatropic calls the BFF with a static service token plus {{end_user_id}}.

Set the BFF secret on pricepally-api

In pricepally-api/.env:

CHATROPIC_AGENT_BFF_TOKEN=pricepally-demo-bff-secret

Restart go run ./cmd/server after changing env.

Create the static BFF token in Chatropic

Manage tokens: new Static token

Field	Value
Name	`pricepally_bff`
Secret	Same value as `CHATROPIC_AGENT_BFF_TOKEN` in `pricepally-api/.env`

Point actions at the BFF

HTTP actions call /api/agent/*, not /api/products directly. Use the same headers on every action:

Authorization: Bearer {{token.pricepally_bff}}
X-End-User-Id: {{end_user_id}}

Action	BFF URL (local)
`search_products`	`http://localhost:8084/api/agent/products?q={{query}}`
`add_to_cart`	`http://localhost:8084/api/agent/cart/items`
`get_order_status`	`http://localhost:8084/api/agent/orders?order_id={{order_id}}`

On a physical device, replace localhost with your machine’s LAN IP (same as EXPO_PUBLIC_PRICEPALLY_API_URL).

When the user signs in to your app, POST their Pricepally user id and JWT to the session route:

await fetch(`${PRICEPALLY_API_URL}/api/agent/session`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userId: session.user.id,
    token: session.token,
  }),
});

The reference RN app does this in lib/agent-session.ts: called on login, app restore, and cleared on logout.

Pass endUserId to the mobile SDK

Mount the chat widget with the signed-in user’s id so {{end_user_id}} resolves to the Pricepally user UUID (not the anonymous chat session id):

<ChatWidgetLauncher
  tenantId={tenantId}
  agentUrl={agentUrl}
  endUserId={user.id}
  ...
/>

See examples/react-native-demo/App.tsx.

The in-memory session store in pricepally-api is for local development only. Production should use Redis or your session database keyed by userId.

Alternative when users sign in inside chat via OAuth instead of your app shell. Configure Customer login in Manage tokens so Authorization: Bearer {{token.pricepally_session}} maps to the shopper’s JWT after they complete the OAuth flow.See the fintech SaaS recipe, OAuth tab for the same dashboard pattern. pricepally-api does not ship an OAuth server today, use the Agent BFF tab for the RN demo.

Manage tokens

Static vs customer-login tokens.

Step 4, Skill setup

Create one skill per feature under Agent settings → Skills → New skill. Each skill covers a single capability and auto-creates the linked HTTP action when saved.

What is a Skill?

A Skill is a playbook that tells the agent when to activate and how to carry out one feature, including the API call to make. When you save a skill with a webhook step, Chatropic creates (or updates) the linked HTTP action automatically. See the Skills guide for the full editor reference. Create the three skills below in sequence. For each one:

Open Agent settings → Skills, then New skill.
Paste the description prompt into the Describe your skill field.
Review the generated When to use, Steps, and webhook URL/headers. Edit inline if needed.
Click Save skill. The linked action appears under Available actions.

For the Demo static JWT pattern, replace {{token.pricepally_bff}} with {{token.pricepally_demo_jwt}} and use the direct API URLs (/api/products, /api/cart/items, /api/orders) instead of /api/agent/*.

4a, Search products skill

Prompt to paste:

When a shopper asks what produce is available, in season, or asks for the price of an item, search the Pricepally catalog. Call GET http://localhost:8084/api/agent/products?q={{query}} with headers Authorization: Bearer {{token.pricepally_bff}} and X-End-User-Id: {{end_user_id}}. Summarize results by name, price range in Naira, and season status. If no results, say so and suggest refining the search.

Webhook the skill should generate:

Field	Value
Method	GET
URL	`http://localhost:8084/api/agent/products?q={{query}}`
Headers	`Authorization: Bearer {{token.pricepally_bff}}`, `X-End-User-Id: {{end_user_id}}`

Sample response:

{
  "items": [
    {
      "id": "3",
      "category": "",
      "name": "Ginger",
      "image": "https://www.pricepally.com/...",
      "price": "₦1,629 - ₦688,379"
    }
  ]
}

4b, Add to cart skill

Prompt to paste:

When a shopper asks to add an item to their cart, add it using the Pricepally API. If the product_id is not already known, first search for the product to resolve it. Then call POST http://localhost:8084/api/agent/cart/items with headers Authorization: Bearer {{token.pricepally_bff}}, X-End-User-Id: {{end_user_id}}, Content-Type: application/json, and Accept: application/json. Send body {"product_id":"{{product_id}}","quantity":{{quantity}}}. Default quantity to 1 if not specified. Confirm the updated cart subtotal in Naira.

Webhook the skill should generate:

Field	Value
Method	POST
URL	`http://localhost:8084/api/agent/cart/items`
Headers	`Authorization: Bearer {{token.pricepally_bff}}`, `X-End-User-Id: {{end_user_id}}`, `Content-Type: application/json`, `Accept: application/json`
Body	`{"product_id":"{{product_id}}","quantity":{{quantity}}}`

Accept: application/json is required. The mobile app uses Accept: text/event-stream for live cart sync; the agent action needs a normal JSON response.

Sample response:

{
  "items": [
    {
      "id": "1",
      "name": "Onions - Red",
      "description": "Medium Bag (5kg)",
      "price": 4890,
      "quantity": 2,
      "imageUrl": "https://www.pricepally.com/..."
    }
  ],
  "subtotal": 12659
}

4c, Order status skill

Prompt to paste:

When a shopper asks where their order is or provides an order reference, look up the delivery status. Call GET http://localhost:8084/api/agent/orders?order_id={{order_id}} with headers Authorization: Bearer {{token.pricepally_bff}} and X-End-User-Id: {{end_user_id}}. Report the status, order date, and main product. If the user asks to see all their orders without a reference, omit the order_id parameter.

Webhook the skill should generate:

Field	Value
Method	GET
URL	`http://localhost:8084/api/agent/orders?order_id={{order_id}}`
Headers	`Authorization: Bearer {{token.pricepally_bff}}`, `X-End-User-Id: {{end_user_id}}`

Sample response:

{
  "orders": [
    {
      "id": "3",
      "orderId": "00A49291044D1",
      "status": "Delivered",
      "orderDate": "Monday, July 17, 2023",
      "orderTime": "9:14 am",
      "mainProduct": {
        "name": "Onions - Red",
        "description": "Medium Bag (5kg)",
        "price": 4890,
        "quantity": 1,
        "imageUrl": "https://www.pricepally.com/..."
      },
      "additionalItemsCount": 0
    }
  ]
}

Validate auto-created actions

After saving all three skills, confirm each linked action is wired correctly:

Open Available actions → click each action (search_products, add_to_cart, get_order_status)
Verify the URL, method, and headers match the tables above
Use the action Test panel with sample parameters (query: "ginger", order_id: "00A49291044D1")
Use each action’s Test panel to check resolved URLs and response bodies

Skills

Create and manage skills under Agent settings.

Action chaining

Search → add to cart chain reference.

Step 5, Agent instructions

In AI (or Agent settings), add system guidance:

You are the Pricepally shopping assistant. For product questions, call search_products.
To add items, resolve product_id first if needed, then call add_to_cart.
For order tracking, call get_order_status with the order reference the user provides.
Answer delivery and payment questions from the knowledge base. Prices are in Nigerian Naira (₦).

Guardrails: block requests for card numbers or passwords in chat; use Escalate to human for delivery disputes.

Step 6, Suggested prompts

Suggested prompts on the Content tab:

Prompt
Do you have ginger?
Add onions to my cart
Track my order 00A49291044D1
What’s in season this week?
Show my recent orders

Step 7, Test in Playground

Product search

Ask “Do you have ugu?”, search_products with q=ugu, agent lists Ugu with price range.

Add to cart

Ask “Add ginger to my cart”, search then add_to_cart with product_id: "3", confirms updated subtotal.

Order status

Ask “Where is order 00B77120355E2?”, get_order_status, explains Processing status and main item.

FAQ without action

Ask “How do I pay?”, answer from Documents, no HTTP call.

Check each action’s Test panel for resolved URLs and response bodies, and your API’s server logs for the incoming requests.

Step 8, React Native embed

The repo includes a Pricepally-skinned demo that uses the same API for login, products, cart SSE, and orders.

Configure env

cd examples/react-native-demo
cp .env.example .env

EXPO_PUBLIC_CHATROPIC_TENANT_ID=your-tenant-id
EXPO_PUBLIC_AGENT_URL=http://127.0.0.1:8000
EXPO_PUBLIC_PRICEPALLY_API_URL=http://127.0.0.1:8084

Run services

Service	Port
`customer-agent`	8000
`pricepally-api`	8084

npx expo start --ios

Deploy mobile profile

Mobile app, configure style and content, Deploy, toggle Live.

Use demo credentials ada@pricepally.demo / Demo1234! in the app shell, then open the chat launcher. Cart tab stays in sync via GET /api/cart/stream SSE.

React Native deploy

Mobile app profile and tenant id.

React Native SDK

ChatWidgetLauncher, storage, and identity props.

Quick curl reference

# Login
TOKEN=$(curl -s -X POST http://localhost:8084/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@pricepally.demo","password":"Demo1234!"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')

# Search products
curl -s "http://localhost:8084/api/products?q=ginger" \
  -H "Authorization: Bearer $TOKEN"

# Add to cart (JSON, for agents)
curl -s -X POST http://localhost:8084/api/cart/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"product_id":"3","quantity":1}'

# Order status
curl -s "http://localhost:8084/api/orders?order_id=00A49291044D1" \
  -H "Authorization: Bearer $TOKEN"

# Agent BFF (after POST /api/agent/session)
BFF=pricepally-demo-bff-secret
curl -s "http://localhost:8084/api/agent/products?q=ginger" \
  -H "Authorization: Bearer $BFF" \
  -H "X-End-User-Id: <user-uuid-from-login>"

Troubleshooting

Symptom	Fix
Agent says “not signed in” but user is logged in	Confirm `registerAgentSession` ran after login and `endUserId={user.id}` is passed to the SDK. Re-open chat after login.
BFF returns “No active session for this user”	`POST /api/agent/session` failed, check `pricepally-api` is running and `userId` matches the JWT `sub`.
BFF returns “Invalid agent service token”	`pricepally_bff` token in Chatropic must match `CHATROPIC_AGENT_BFF_TOKEN` in `pricepally-api/.env`.
Actions hit wrong user	`{{end_user_id}}` must be the Pricepally user UUID, not the chat `demo-...` session id, pass `endUserId` from your auth state.

Backend README: pricepally-api/README.md in the Chatropic repo
Catalog & product FAQ, generic catalog patterns
Fintech SaaS agent, JWT + customer-login token patterns

Quick Start

Agent Management

Actions

Settings & Guardrails

Deploy

Analytics & Monitoring

Pricepally ecommerce agent

What you are building

API reference (pricepally-api)

Agent BFF routes (signed-in users)

Prerequisites

Step 1, Create the agent

Step 2, Knowledge base setup

Step 3, Authentication for actions

Manage tokens

Step 4, Skill setup

What is a Skill?

4a, Search products skill

4b, Add to cart skill

4c, Order status skill

Validate auto-created actions

Skills

Action chaining

Step 5, Agent instructions

Step 6, Suggested prompts

Step 7, Test in Playground

Step 8, React Native embed

React Native deploy

React Native SDK

Quick curl reference

Troubleshooting

​What you are building

​API reference (pricepally-api)

​Agent BFF routes (signed-in users)

​Prerequisites

​Step 1, Create the agent

​Step 2, Knowledge base setup

​Step 3, Authentication for actions

Manage tokens

​Step 4, Skill setup

​What is a Skill?

​4a, Search products skill

​4b, Add to cart skill

​4c, Order status skill

​Validate auto-created actions

Skills

Action chaining

​Step 5, Agent instructions

​Step 6, Suggested prompts

​Step 7, Test in Playground

​Step 8, React Native embed

React Native deploy

React Native SDK

​Quick curl reference

​Troubleshooting

​Related

What you are building

API reference (pricepally-api)

Agent BFF routes (signed-in users)

Prerequisites

Step 1, Create the agent

Step 2, Knowledge base setup

Step 3, Authentication for actions

Step 4, Skill setup

What is a Skill?

4a, Search products skill

4b, Add to cart skill

4c, Order status skill

Validate auto-created actions

Step 5, Agent instructions

Step 6, Suggested prompts

Step 7, Test in Playground

Step 8, React Native embed

Quick curl reference

Troubleshooting

Related