=============================================
A high-fidelity Freshworks Platform v3 reference app demonstrating multi-provider authentication. It consolidates e-commerce data (BigCommerce) and payment history (PayPal) into the Freshdesk ticket sidebar.
Consolidates disparate data points into a single sidebar pane. Agents can view BigCommerce customer profiles and PayPal transaction statuses without switching tabs, reducing Average Handle Time (AHT).
Automatically retrieves the last 3 orders associated with the ticket requester's email. Displays order status, total value, and fulfillment updates in real-time.
Integrates with the PayPal Transaction Search API to fetch payment details within a 31-day window, allowing agents to verify refund requests or payment failures instantly.
Demonstrates a robust auth-switch capability:
-
OAuth 2.0 Authorization Code for BigCommerce (User-delegated).
-
OAuth 2.0 Client Credentials for PayPal (System-to-system).
This app serves as a blueprint for managing multiple distinct authentication lifecycles within a single serverless environment.
-
Flow: Handled natively by the Platform via
oauth_config.json. -
Engineering Rationale: Leverages platform-managed token rotation and encryption for store-level data access.
-
Flow: Manual server-side token exchange using Client ID/Secret.
-
Engineering Rationale: Demonstrates dynamic token generation for services requiring system-to-system authentication rather than user-delegated access.
| Functionality | Platform Module | Path | Engineering Rationale |
|---|---|---|---|
| Data Orchestration | Serverless (SMI) | server/server.js |
Aggregates data from two disparate APIs in a single async operation to reduce frontend overhead. |
| API Abstraction | Request Templates | config/requests.json |
Centralizes endpoint definitions; uses dynamic context injection for store hashes and tokens. |
| Automated Context | Event Handlers | server/server.js |
Uses onTicketCreate to pre-fetch customer history, reducing perceived latency for the agent. |
| Sidebar Injection | App Locations | manifest.json |
Embeds real-time purchase context directly into the agent's primary workflow. |
Plaintext
.
├── app/ # Frontend Assets (Crayons UI)
│ ├── index.html # App View Container
│ ├── scripts/app.js # Interface API & SMI Invocation
│ └── styles/style.css # Sidebar-specific UI overrides
├── config/ # Configuration & Auth
│ ├── iparams.json # Secure Credential Definitions
│ └── oauth_config.json # BigCommerce OAuth Scopes & Endpoints
├── server/ # Serverless Logic
│ └── server.js # Multi-OAuth Orchestration & Event Handlers
├── manifest.json # App Capabilities & Module Definitions
└── requests.json # Declarative API Request Templates
-
Store Hash: Locate in your URL:
store-{hash}.mybigcommerce.com. -
Scopes: Ensure your API Account has
read-onlyaccess to Customers, Orders, and Store Information.
-
Create an app in the PayPal Developer Dashboard.
-
Retrieve Client ID and Secret. Note: Transaction Search is limited to 31-day windows.
-
Clone & Install:
Bash
fdk run -
OAuth Handshake: Complete the BigCommerce OAuth flow in the installation settings page.
-
Local Test: Open a ticket in Freshdesk and append
?dev=trueto the URL.
| Error | Cause | Resolution |
|---|---|---|
| 403 Forbidden | Missing BigCommerce Scopes | Update API Account to include read-only Customer/Order scopes. |
| 404 openresty | Incorrect Store Hash | Verify the bigcommerce_store_hash in your iparams. |
| PayPal Range Error | Date window > 31 days | Adjust the start_date in requests.json to be within 31 days of end_date. |