Integration Overview

Simpli services sit alongside your existing helpdesk — they don't replace it. Your helpdesk (Zendesk, Freshdesk, Intercom, etc.) remains the system of record. Simpli adds AI capabilities via REST APIs.

Architecture

┌─────────────┐     webhook/API      ┌──────────────┐     REST API      ┌─────────────────┐
│  Helpdesk   │  ──────────────────► │  Middleware   │ ────────────────► │ Simpli Services  │
│  (Zendesk)  │ ◄────────────────── │  (your code)  │ ◄──────────────── │ Triage, Reply... │
└─────────────┘   update tickets     └──────────────┘    AI results      └─────────────────┘

Your helpdesk sends events to a small middleware layer you control. That middleware normalizes the data into Simpli's domain models and calls the relevant Simpli APIs. Results flow back through the middleware to update tickets, tags, and fields in your helpdesk.

Two approaches

Webhook-driven (recommended)

Your helpdesk fires webhooks on events — ticket created, message added, ticket solved. Your middleware receives these, calls Simpli APIs, and pushes results back via the helpdesk API.

This is the best approach for real-time workflows like auto-triage and draft reply generation.

Polling-based

A scheduled job pulls new or updated tickets from your helpdesk API, calls Simpli APIs, and pushes results back. Simpler to set up but less real-time — suitable for batch operations like QA scoring or sentiment trend analysis.

Service-to-helpdesk feature mapping

Middleware skeleton

A minimal FastAPI middleware that receives a webhook, normalizes the payload, and calls Triage and Sentiment capabilities:

from fastapi import FastAPI, Request
import httpx

app = FastAPI()
TRIAGE_URL = "http://localhost:8001"
SENTIMENT_URL = "http://localhost:8003"

@app.post("/webhook/ticket-created")
async def on_ticket_created(request: Request):
    payload = await request.json()

    # Normalize to Simpli format
    subject = payload.get("subject") or payload.get("title", "")
    body = payload.get("body") or payload.get("description", "")
    customer_id = str(payload.get("customer_id", payload.get("requester_id", "")))

    async with httpx.AsyncClient() as client:
        # Classify the ticket
        classification = (await client.post(f"{TRIAGE_URL}/classify", json={
            "subject": subject,
            "body": body,
        })).json()

        # Analyze sentiment
        sentiment = (await client.post(f"{SENTIMENT_URL}/analyze", json={
            "customer_id": customer_id,
            "text": f"{subject}\n{body}",
        })).json()

    return {
        "classification": classification,
        "sentiment": sentiment,
    }

This is intentionally minimal. See the Generic Webhook guide for a production-ready version with error handling, signature verification, and result callbacks.

Supported platforms

• Zendesk — Full guide
• Freshdesk — Full guide
• Intercom — Full guide
• Salesforce Service Cloud — Full guide
• HubSpot Service Hub — Full guide
• Generic Webhook — For any other platform

Authentication

Simpli services don't include built-in authentication. In production, place them behind an API gateway or reverse proxy that handles auth. See security best practices for details.