Casi d'uso

Tutti gli esempi assumono una chiave con lo scope indicato e un piano Pro o Enterprise (vedi Piani e limiti). Sostituisci aa_TUA_CHIAVE_COMPLETA con la tua chiave reale.

1. Sincronizzare i lead verso il tuo CRM

La tua agenzia usa già un CRM (HubSpot, Zoho…) oltre a Nuntius. Invece che noi spingiamo verso il tuo CRM, la tua integrazione estrae i lead nuovi ogni ora con dateFrom:

curl "https://api.nuntius.chat/public/v1/leads?dateFrom=2026-09-01T00:00:00Z" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

import requests

resp = requests.get(
    "https://api.nuntius.chat/public/v1/leads",
    params={"dateFrom": "2026-09-01T00:00:00Z"},
    headers={"X-API-Key": "aa_TUA_CHIAVE_COMPLETA"},
)
for lead in resp.json()["data"]:
    sync_to_my_crm(lead)

Scope: tenant:leads.read.

2. Catturare lead dal tuo sito

Hai una landing page fuori dal widget incorporabile di Nuntius e non vuoi montarci il widget di chat — invia il modulo direttamente all’API:

await fetch("https://api.nuntius.chat/public/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "aa_TUA_CHIAVE_COMPLETA",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerPhone: "+34600111222",
    stageId: "...",
    notes: "Modulo della landing page servizi",
  }),
});

Scope: tenant:leads.manage (oppure tenant:contacts.manage se invii il modulo a /contacts).

3. Mantenere unificato un calendario esterno

Usi già Calendly o Google Calendar come fonte di verità di un altro team — controlla gli slot liberi di Nuntius prima di offrire un orario, e crea l’appuntamento qui in modo che sia riflesso in entrambi i posti:

curl "https://api.nuntius.chat/public/v1/availability?from=2026-09-10&to=2026-09-14" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

slot = pick_a_slot(available_slots)
requests.post(
    "https://api.nuntius.chat/public/v1/appointments",
    json={"userId": slot["userId"], "startsAt": slot["startsAt"], "customerId": customer_id},
    headers={"X-API-Key": "aa_TUA_CHIAVE_COMPLETA"},
)

Scope: tenant:appointments.read (disponibilità) + tenant:appointments.manage (creazione).

4. Sincronizzare i ticket con il tuo helpdesk

Il tuo proprio Zendesk o Freshdesk (diverso da una nostra integrazione Zendesk) riflette in entrambe le direzioni lo stato di ogni ticket:

const res = await fetch("https://api.nuntius.chat/public/v1/tickets?status=open", {
  headers: { "X-API-Key": "aa_TUA_CHIAVE_COMPLETA" },
});
const { data: openTickets } = await res.json();

curl -X PATCH "https://api.nuntius.chat/public/v1/tickets/TICKET_ID" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Scope: tenant:tickets.read (lettura) + tenant:tickets.manage (creazione/aggiornamento/commento).

5. Automazione low-code (Zapier e simili)

Attiva uno Zap quando arriva un lead nuovo (tramite polling periodico a GET /leads, finché non esiste un webhook) e usa come azione “invia un messaggio WhatsApp da un foglio di calcolo”:

curl -X POST "https://api.nuntius.chat/public/v1/conversations/CONVERSATION_ID/messages" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"text": "Il tuo appuntamento è confermato per domani alle 10:00"}'

Scope: tenant:conversations.manage. Ricorda: se il contatto è su WhatsApp e la sua finestra di 24h è chiusa, questa chiamata risponde 409 WHATSAPP_SESSION_WINDOW_CLOSED senza tentare l’invio — usa POST /conversations/start con un template approvato per aprire una nuova conversazione. E in ogni caso, il messaggio inviato non compare all’istante nell’inbox della Piattaforma — vedi la nota in Iniziare con l’API.