API Syrus Chat · v1

Autenticazione

Bearer token con API key generata dalla dashboard /dashboard/api-keys.

curl https://chat.syrus.biz/api/v1/leads \
  -H "Authorization: Bearer syk_xxxxxxxxxxxxxxxxxxxxxx"

Ogni API key ha scopes. Un endpoint ritorna 403 insufficient_scope se manca lo scope richiesto.

• leads:read — GET leads
• conversations:read — GET conversations
• webhooks:manage — CRUD webhooks

Rate limits

100 richieste/minuto per API key. Il limite è per singola chiave (non per IP); 2 client con chiavi diverse hanno limiti indipendenti.

Superato il limite: 429 Too Many Requests con header Retry-After.

Endpoints v1

Estratti dal url_map + docstring. Aggiorna al runtime.

Esempi

GET /api/v1/leads?chatbot_slug=<slug>&since=<iso>&page=1&per_page=50

curl "https://chat.syrus.biz/api/v1/leads?since=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer syk_..."

GET /api/v1/leads/<id>

{
  "id": "uuid",
  "email": "mario@acme.it",
  "phone": "+390612345678",
  "qualified": true,
  "qualification_score": 95,
  "conversation": {"id": "uuid", "messages": [...]}
}

POST /api/v1/webhooks

curl -X POST https://chat.syrus.biz/api/v1/webhooks \
  -H "Authorization: Bearer syk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot_id": "uuid",
    "url": "https://crm.tuo.tld/webhook",
    "events": ["lead_qualified"]
  }'

La response include secret visibile UNA SOLA VOLTA: usalo per verificare la signature HMAC dei payload.

Webhook events

Syrus Chat invia HTTP POST firmati verso il tuo endpoint per eventi configurati.

lead_qualified payload:

{
  "event": "lead_qualified",
  "timestamp": "2026-04-19T12:34:56Z",
  "chatbot": {"id": "uuid", "slug": "demo-bot"},
  "lead": {
    "id": "uuid", "name": "Mario Rossi",
    "email": "mario@acme.it", "phone": "+390612345678",
    "message": "...", "qualification_score": 95,
    "source_url": "https://client.tld/contatti",
    "utm_source": null, "utm_campaign": null
  },
  "conversation": {
    "id": "uuid", "message_count": 8, "qualification_score": 95
  }
}

Headers rilevanti

• X-Syrus-Event: lead_qualified
• X-Syrus-Signature-256: sha256=<hex> — HMAC SHA-256 del body raw col secret
• X-Syrus-Timestamp: 1714123456 — epoch seconds, verifica <5min per replay protection
• X-Syrus-Delivery-Id: <uuid> — utile per idempotenza lato tuo
• X-Syrus-Attempt: 1 — il numero di tentativo (1→5 con backoff 30s/2m/10m/1h/6h)

→ Vedi esempi di verifica firma in Python/Node/PHP

Errors