Sviluppatori
Tutto quello che fa la console, lo fa anche l’API.
Un’API pubblica versionata, eventi in tempo reale e webhook firmati. Non è uno strato di facciata sopra un prodotto chiuso: la console di amministrazione Konvoice consuma esattamente questi stessi punti di accesso.
Principi
Quattro impegni che contano più dell’elenco dei punti di accesso.
Versionata
/api/v1/ è stabile. Una rottura comporta una nuova versione maggiore, mai una modifica silenziosa. La versione precedente resta servita per almeno dodici mesi.
Tracciabile
Ogni richiesta porta un identificativo di correlazione che ritrovate nei nostri registri e nel vostro registro di audit. Un ticket di assistenza comincia da quel numero.
Idempotente
Ogni scrittura accetta una chiave di idempotenza. Rigiocare una richiesta dopo un timeout di rete non crea un secondo utente né una seconda chiamata.
Separata
Un token appartiene a un’azienda e porta ambiti espliciti. Non può leggere oltre, e un ambito in lettura non diventa mai una scrittura.
REST
Creare un utente con il suo interno.
Una sola richiesta crea la persona, il suo interno, le sue credenziali di apparato e avvia la configurazione del suo telefono.
POST /api/v1/users HTTP/1.1
Host: api.konvoice.io
Authorization: Bearer kv_live_…
Idempotency-Key: 4f1c-9a02-b7
{
"display_name": "Amadou Diallo",
"email": "[email protected]",
"site_id": "site_lyon",
"extension": "203",
"role": "agent",
"devices": [
{ "type": "deskphone", "mac": "805e0c1a2b3c" },
{ "type": "mobile" },
{ "type": "web" }
],
"teams": ["support"]
}
Prima della produzione
Numeri che rispondono male, apposta.
Il peggior ambiente di prova di un’integrazione telefonica è un collega che si chiama venti volte. L’ambiente di prova fornisce numeri il cui comportamento è prevedibile — risposta, mancata risposta, occupato, segreteria, guasto dell’operatore — e le vostre prove smettono di dipendere da qualcuno.
- Scenari deterministici — un numero per esito, sempre lo stesso.
- Webhook veri — firmati, rigiocabili, nello stesso formato della produzione.
- Un identificativo di correlazione su ogni richiesta, che l’assistenza ritrova nei nostri registri.
- Nessuna chiamata fatturata — l’ambiente di prova non consuma niente.
Eventi
Quello che succede, nel momento in cui succede.
Gli eventi sono diffusi tramite webhook firmato e tramite flusso in tempo reale. I due trasportano lo stesso contenuto, con la stessa garanzia di consegna almeno una volta.
| Evento | Quando | Uso comune |
|---|---|---|
call.ringing | Una chiamata comincia a squillare | Mostrare la scheda cliente prima della risposta |
call.answered | Qualcuno ha risposto | Avviare un cronometro, aprire un ticket |
call.ended | La chiamata è finita | Scrivere l’attività nel CRM |
call.missed | Nessuno ha risposto | Creare un’attività di richiamo |
recording.ready | La registrazione è disponibile | Archiviare nel vostro spazio di archiviazione |
transcript.ready | La trascrizione e la sintesi sono prodotte | Alimentare il vostro strumento di analisi |
voicemail.received | Viene lasciato un messaggio vocale | Avvisare una squadra |
device.registered | Un telefono si registra | Sorvegliare il parco |
site.link_lost | Una sede passa in autonomia locale | Avvisare la vostra sorveglianza di rete |
site.link_restored | Il collegamento di una sede è ripristinato | Chiudere l’allarme, controllare la coda di sincronizzazione |
fraud.route_blocked | Una rotta è stata interrotta dal motore antifrode | Svegliare qualcuno |
Webhook
Firmati, marcati con l’ora, rigiocati.
Verificate la firma prima di trattare il contenuto. La marcatura oraria protegge dal rigioco, la chiave di idempotenza protegge dai duplicati quando riproviamo.
- Firma HMAC-SHA256 sul corpo grezzo, con un segreto per punto di consegna.
- Nuovi tentativi con attesa crescente per 24 ore, poi una coda di errori consultabile.
- Rifiutate una marcatura oraria più vecchia di cinque minuti: è un rigioco.
- Rispondete 2xx rapidamente e trattate in secondo piano; tagliamo a 10 secondi.
POST /vostro-endpoint HTTP/1.1
Konvoice-Signature: t=1743158400,
v1=8c1f…d40a
Konvoice-Event-Id: evt_01HZ…
Konvoice-Delivery: 1
{
"type": "call.ended",
"created_at": "2026-03-28T09:20:00Z",
"tenant_id": "ten_8f3c",
"data": {
"call_id": "call_01HZ…",
"direction": "inbound",
"from": "+33478XXXXXX",
"to": "+33472XXXXXX",
"extension": "203",
"duration_s": 214,
"disposition": "answered",
"site_id": "site_lyon",
"handled_locally": true
}
}Le nostre schermate non consumano altro che questa API. È l’unica garanzia seria che resterà completa.
Il giorno in cui le manca qualcosa, si ferma anche la nostra applicazione
Ambiente di prova
Sviluppate senza chiamare clienti veri.
Un ambiente separato, con i propri token, i suoi numeri di prova e una serie di chiamate simulabili su richiesta.
Numeri di prova
Numeri che rispondono con uno scenario prevedibile: risposta, mancata risposta, occupato, messaggio vocale, guasto dell’operatore. Le vostre prove automatiche smettono di dipendere da un collega.
Eventi attivabili
Emettete qualunque evento dell’elenco dalla console, compresa la perdita di collegamento di una sede, per verificare che la vostra integrazione reagisca correttamente.
Registro delle consegne
Ogni webhook inviato, la sua risposta, il suo tempo e i suoi nuovi tentativi. Il rigioco manuale di una consegna si fa con un pulsante.
Domande per sviluppatori
Ci sono limiti di frequenza?
Fornite una specifica OpenAPI?
Si possono controllare le chiamate in tempo reale?
L’API è disponibile su una sede fuori linea?
Un accesso di prova, gratuito.
Diteci cosa volete costruire. Apriamo un ambiente con numeri di prova e restiamo raggiungibili durante tutta la vostra integrazione.
Senza impegno. Nessun numero di carta richiesto.