Usare Call

API e webhook di Call per sviluppatori: chiavi, ambiti, eventi

Panoramica pratica dell'API REST di Call: chiavi API e ambiti, limiti di frequenza, gestione degli errori, webhook firmati e la pagina Sviluppatori per gli endpoint.

La redazione di Call · Pubblicato · Lettura di 6 min

Prima o poi un sistema telefonico deve parlare con qualcos'altro: un CRM che dovrebbe mostrare una chiamata appena finisce, uno strumento di fatturazione che vuole sapere chi ha chiamato, uno script che avvia una chiamata quando viene inviato un modulo. Call ha un'API REST e webhook in uscita proprio per questo. Questa guida spiega come si combinano i pezzi, cosa chiedere prima di scrivere codice e gli errori che più spesso costano un pomeriggio a uno sviluppatore.

Uno sviluppatore controlla un'integrazione su un portatile accanto a un telefono fisso
Immagine illustrativa

Se il tuo obiettivo è solo spostare contatti in blocco, leggi prima Importare i contatti nel CRM di un team telefonico; un'importazione è spesso più semplice di un'integrazione.

Da dove partire: il riferimento e la pagina Sviluppatori

Ci sono due posti da conoscere. Il Riferimento API si trova in Impostazioni e anche nel menu Risorse della home page. Si può leggere senza accedere, cosa comoda quando stai definendo un lavoro per un cliente. La pagina Sviluppatori, anch'essa in Impostazioni, riguarda la tua area di lavoro: mostra gli identificativi della tua organizzazione e degli agenti, i tuoi endpoint webhook e un elenco in sola lettura delle tue chiavi.

Cosa ti offre ciascun posto

  • Inizia da quiURL di base e convenzioni, autenticazione con una tabella degli ambiti ed errori con i codici di stato.
  • EndpointLa scheda di ogni endpoint indica ambito, parametri, corpo della richiesta, risposta ed errori, con richieste pronte da copiare in curl, JavaScript e Python.
  • RicercaPremi / per andare a Cerca endpoint e filtrare per metodo, percorso, ambito o descrizione.
  • OpenAPI JSONScarica l'intera specifica in un unico file per i tuoi strumenti.
  • ID agente / APIL'ID e lo slug della tua organizzazione, la modalità dell'API (Ambiente di prova o Dal vivo) e l'ID dell'agente IA che scegli, ognuno con un pulsante Copia.
  • WebhookI tuoi endpoint, gli eventi che riceve ciascuno, l'ultimo stato HTTP ed eventuali consegne non riuscite.

Leggi le sezioni sui limiti di frequenza e sui webhook in uscita prima di andare in produzione, non dopo. Descrivono comportamenti che in un test veloce è facile non notare.

Chiavi API e ambiti

Ogni richiesta porta una chiave nell'intestazione Authorization come bearer token. Le chiavi non si creano nell'app: le emette l'operatore della tua area di lavoro, che ti dice quali ambiti hanno. La chiave completa viene mostrata una sola volta, al momento dell'emissione, e poi ne compaiono solo i primi caratteri, quindi salvala subito nel tuo archivio di segreti.

AmbitoCosa consente
readLeggere contatti, chiamate, code, membri del team, report e la lista dei numeri da non chiamare.
writeCreare e aggiornare contatti, registrare gli esiti delle chiamate, aggiungere numeri alla lista dei numeri da non chiamare.
callsAvviare e terminare chiamate.
adminGestire i webhook; può anche chiamare tutti gli altri endpoint.

Chiedi l'insieme più piccolo che basta per il lavoro. Uno script di report ha bisogno solo di read; un pulsante click-to-call ha bisogno di calls. Se una richiesta restituisce un 403 con il codice insufficient_scope, alla chiave manca l'ambito indicato sulla scheda di quell'endpoint.

Ambiente di prova e produzione

Le chiavi possono essere emesse per un ambiente di prova, che usa un simulatore e non fa chiamate reali, oppure per l'uso reale. Considera il prefisso di una chiave solo come un'etichetta: una chiave etichettata come test lavora sugli stessi dati e sulla stessa connessione telefonica di una chiave reale, quindi non affidarti al prefisso per tenere gli esperimenti lontani dai clienti veri. Usa la modalità dell'API indicata nella pagina Sviluppatori per sapere dove ti trovi.

Avviare chiamate tramite l'API

Gli endpoint pubblici coprono le basi: un controllo di stato, l'elenco delle chiamate, la lettura di una chiamata, l'avvio di una chiamata, la chiusura, la gestione dei webhook e la chat con un agente IA. Una chiamata in uscita avviata tramite l'API passa lo stesso controllo di conformità di una chiamata fatta dalla postazione, quindi un numero presente nella lista dei numeri da non chiamare o fuori dagli orari consentiti viene rifiutato, esattamente come per un operatore. Scrivi il codice in modo da gestire quel rifiuto come un esito normale, non come un bug.

Questo conta per la progettazione. Non scrivere un ciclo che ritenta una chiamata rifiutata finché non passa. Leggi il motivo, registralo e vai avanti. Per le regole alla base di questi rifiuti leggi Il controllo degli orari di chiamata in Call e La lista dei numeri da non chiamare in Call.

Limiti di frequenza ed errori

Ogni chiave ha un proprio limite di richieste al minuto, fissato al momento dell'emissione; il valore predefinito è 120. Quando una chiave esaurisce il minuto, l'API risponde 429 con il codice rate_limited e indica quanto aspettare nell'intestazione X-RateLimit-Reset. Aspetta quel tempo, poi riprendi. Un client educato rallenta da solo prima di sbattere contro il muro.

Gestire una richiesta non riuscita

  1. Leggi lo statoÈ un errore del client che puoi correggere, o un errore del server che vale la pena ritentare?
  2. Leggi il codiceDecidi in base al codice, mai in base al testo del messaggio.
  3. RallentaPer il 429 attendi l'intestazione di reset; per gli errori del server ritenta alcune volte con intervalli crescenti.
  4. Registra i dettagliConserva endpoint, codice e orario, così l'assistenza può ricostruire cosa è successo.
  5. Fermati sui rifiutiUn rifiuto di conformità è una decisione, non un inconveniente; non ritentare in ciclo.

Webhook: ricevere gli eventi

Invece di chiedere continuamente all'API se è successo qualcosa, lascia che sia Call ad avvisarti. Nella pagina Sviluppatori premi Aggiungi endpoint, inserisci un indirizzo https pubblico e seleziona gli eventi che ti interessano; se non ne selezioni nessuno, li ricevi tutti. Il segreto di firma viene mostrato una sola volta, quando aggiungi l'endpoint. Copialo in quel momento. Se lo perdi, elimina l'endpoint e aggiungilo di nuovo per ottenerne uno nuovo.

Ogni consegna è firmata. L'intestazione della firma contiene un HMAC-SHA256 del timestamp e del corpo uniti da un punto, calcolato con il tuo segreto di firma, e un'intestazione separata contiene il timestamp. Ricalcolalo dal tuo lato e confrontalo prima di fidarti del contenuto. Il riferimento API include codice di esempio in Node.js e Python, e rifiutare i timestamp vecchi ti protegge dalle richieste riprodotte.

Un ricevitore di webhook buono e uno scadente

BuonoScadente
FirmaVerificata a ogni richiestaAccettata senza controlli
Risposta2xx entro pochi secondi, lavoro messo in coda per dopoElaborazione lenta prima di rispondere
DuplicatiRicevere due volte lo stesso evento non crea problemiCrea due record
ErroriAvvisa quando le consegne non riesconoSilenzio finché qualcuno non se ne accorge

Il tuo endpoint deve rispondere con uno stato 2xx entro 10 secondi. Una consegna non riuscita viene ritentata, fino a sei tentativi in tutto, e un endpoint che fallisce 50 volte di fila viene disattivato. Ogni riga della pagina Sviluppatori mostra l'ultimo stato HTTP e quante consegne non sono riuscite, e Invia prova invia un evento di prova firmato, così vedi cosa risponde il tuo server.

Una checklist per il passaggio in produzione

Prima di attivare un'integrazione

  • Sai quali ambiti ha la chiave, e non ne ha più del necessario
  • La chiave è salvata in un archivio di segreti, non nel codice sorgente
  • Le firme dei webhook vengono verificate e i timestamp vecchi rifiutati
  • Il ricevitore risponde in fretta e gestisce gli eventi duplicati
  • Le risposte di limite di frequenza e di rifiuto sono gestite senza cicli di ritentativi serrati
  • Hai fatto test in ambiente di prova e premuto Invia prova sull'endpoint
  • C'è una persona designata a ricevere un avviso se le consegne iniziano a fallire

Farlo in Call

In Call apri Impostazioni, poi Riferimento API per studiare gli endpoint, e Impostazioni, poi Sviluppatori per copiare l'ID della tua organizzazione, controllare le chiavi e aggiungere un webhook. Proprietari, amministratori e responsabili possono aggiungere, provare ed eliminare gli endpoint; tutti gli altri vedono l'elenco. Se usi anche le funzioni degli agenti IA, l'ID agente nella stessa pagina serve per l'endpoint di chat. Per la parte vocale del prodotto leggi Configurare un agente IA in Call.

Domande frequenti

Come ottengo una chiave API?

Le chiavi vengono emesse dall'operatore della tua area di lavoro; non si possono creare nell'app. Chiedine una e indica quali ambiti le servono. La chiave completa viene mostrata una sola volta, al momento dell'emissione.

Cosa significa una risposta 429?

La chiave ha esaurito le richieste del minuto in corso. Attendi il numero di secondi indicato nell'intestazione X-RateLimit-Reset, poi riprova, e distribuisci il lavoro in blocco su un periodo più lungo.

Come verifico che un webhook provenga davvero da Call?

Calcola un HMAC-SHA256 del timestamp e del corpo con il tuo segreto di firma e confrontalo con l'intestazione della firma. Il riferimento API mostra esempi in Node.js e Python.

Posso inviare webhook a un server di sviluppo locale?

Non direttamente. Gli endpoint devono essere indirizzi https pubblici, quindi usa uno strumento di tunneling che esponga il tuo server locale su uno di essi.

Perché la mia chiamata API per avviare una telefonata è stata rifiutata?

Le chiamate avviate tramite l'API passano lo stesso controllo di conformità delle chiamate fatte dalla postazione. Un numero presente nella lista dei numeri da non chiamare o fuori dagli orari di chiamata viene rifiutato.

Chi può vedere e modificare i webhook?

Tutti possono leggere l'elenco, ma solo proprietari, amministratori e responsabili possono aggiungere, provare o eliminare gli endpoint.

Apri il Riferimento API di Call e aggiungi un endpoint webhook

Nella console demo puoi provare le chiamate in arrivo in simulazione.

Guide correlate