Per usare l’API Chat negli account Support+Chat e negli account Chat di fase 4 , devi generare un token di accesso OAuth per autenticare le richieste API. L’autenticazione di base non è supportata. Tuttavia, la prima generazione di un token può creare confusione, quindi questo tutorial fornisce esempi dettagliati su come generare un token manualmente. Al termine, dovresti avere un token che puoi usare nelle richieste API di Chat per leggere e scrivere dati.

Se stai creando un’applicazione, dovresti incorporare la funzionalità di generazione di token nell’app per automatizzare il processo.

Esistono due modi per creare un token di accesso per l’API Chat: un modo più rapido e conveniente per testare gli ambienti (usando il flusso di concessione "implicito") e un modo più lungo e più formale per gli ambienti di produzione (usando la concessione "Codice di autorizzazione" flusso). Questo tutorial copre entrambi.

Condizioni

Questo tutorial è destinato agli account Chat integrati a cui sono state applicate tutte le modifiche a cui si fa riferimento nell’articolo precedente. Attualmente è in fase di implementazione graduale, quindi alcuni account potrebbero richiederlo prima di altri. Se non sei sicuro che il tuo account abbia ricevuto tutte le modifiche, non esitare a contattare il nostro team di assistenza che può confermare per te.

Nota: Un effetto collaterale delle modifiche all’account è che i token OAuth dovranno essere ricreati. Se completi questo tutorial prima che le modifiche abbiano raggiunto il tuo account, dovrai ripetere i passaggi in seguito.

Procedura

Il flusso di concessione "implicita" OAuth prevede i passaggi seguenti:

  1. Crea il client API OAuth
  2. Completa il flusso di concessione implicita OAuth per ottenere il token usando le informazioni del passaggio 1

Crea il client API OAuth

Prima di tutto, abbiamo bisogno di un client API. Vai a Zendesk Chat > Account > API e SDK e fai clic sul pulsante Aggiungi client API . Inserisci un nome per il cliente e l’azienda di tua scelta e per l’URL di reindirizzamentohttp://localhost:8080. Dovrebbe assomigliare a questo:

Fai clic su Crea client API per completare la configurazione. Ti verrà mostrato un popup con l’ID client e il segreto. Molto importante: Il segreto del client viene mostrato una sola volta, quindi prendine nota per un uso successivo. Il codice dovrebbe avere il seguente aspetto:

Ora che il nostro client API è pronto, prendi nota dell’ID client e del Segreto client prima di fare clic su OK. Ora siamo pronti per completare il flusso di concessione OAuth.

Completa il flusso di concessione implicita OAuth per ottenere il token

Questo approccio usa il flusso di concessione "implicito" OAuth. Un approccio alternativo consiste nell'usare il flusso di concessione del "Codice di autorizzazione" OAuth (illustrato nella sezione successiva). Se lo si fa manualmente, questo approccio prevede meno passaggi ed è più conveniente rispetto al flusso di concessione del codice di autorizzazione mostrato in seguito.

1. Segui il passaggio "Creazione del client API OAuth" qui sopra

2. Raccogli queste informazioni dal client OAuth

  • ID cliente: CLIENT_ID
  • Il tuo sottodominio Zendesk

3. Formatta l’URL seguente con il tuo CLIENT_ID e SUBDOMAIN, incollalo in una nuova scheda del browser e premi Invio.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

NOTE:

  • Se il client Chat OAuth ha un solo valore URL di reindirizzamento, l’invio di un valore redirect_uri è facoltativo. Per impostazione predefinita, il sistema utilizzerà il valore URL di reindirizzamento univoco del client OAuth.
  • Se il client OAuth ha più di un valore URL di reindirizzamento, è necessario passare un valore redirect_uri. Se viene passato un valore redirect_uri, deve essere codificato in URL. Nell’esempio precedente, il parametro di reindirizzamento facoltativo sarebbe: redirect_uri=http%3A%2F%2Flocalhost%3A8080

4. Verrà effettuata la chiamata, che potrebbe chiederti di accedere e di selezionare “Consenti” per generare il token.

Se la chiamata riesce, il campo dell’indirizzo del browser conterrà il nuovo token OAuth (restituito come valore access_token).

Nonostante l’apparente messaggio di errore visualizzato nella finestra principale del browser, se nel campo URL del browser viene restituito “access_token”, ha funzionato.

Ecco una demo del workflow:

 

Un modo alternativo e più lungo per generare il token

Questi passaggi creano un token proprio come la sezione precedente, ma illustra il flusso di concessione OAuth "Codice di autorizzazione". Prendi nota dei dettagli del client OAuth, che verranno usati di seguito.

Verranno usati i segnaposto al posto dei dati reali. Ricorda che il segreto del tuo client OAuth deve essere trattato con la massima sicurezza in quanto è essenzialmente una password nel tuo account Chat.

  • ID cliente: CLIENT_ID
  • Segreto client: CLIENT_SECRET
  • URI reindirizzamento: http://localhost:8080
  • Sottodominio: il tuo sottodominio Zendesk; ad esempio, se il tuo account è su niall.zendesk.com, questo valore è niall
  • Codice di autorizzazione: non ancora disponibile

1. Prepara il primo URL

Qui creeremo un URL per richiedere un codice di autorizzazione. Dovrai andare a https://{subdomain}.zendesk.com/oauth2/chat/authorizations/newe aggiungi alcuni parametri di query per trasmettere alcune delle informazioni di cui sopra. Questa volta abbiamo bisogno di:

  • response_type: sarà sempre così code
  • redirect_uri: dove verremo reindirizzati dopo aver concesso l’accesso,http://localhost:8080 per il nostro tutorial
  • client_id: specifico per te, come annotato in precedenza
  • scope: sceglieremo quale accesso avrà questo tokenread e write
    • Includi anche l’ambito “chat” se usi il token rispetto all’API Chat Conversations.
  • subdomain: il tuo sottodominio Zendesk

Mettendo insieme questo e la codifica URL otterrai un URL finale simile al seguente:

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

con CLIENT_ID e SUBDOMAIN essendo l’unica differenza per il tuo URL.

2. Prepara la chiamata cURL

Prima di visitare effettivamente quell’URL, creiamo la chiamata cURL che verrà eseguita dopo. Questa volta avremo bisogno di quanto segue:

  • grant_type: sarà sempre così authorization_code
  • code: otterremo dopo che avremo consentito l’accesso dall’URL
  • client_id: il tuo ID cliente
  • client_secret: il segreto del client
  • redirect_uri: come l'ultimo passaggio - http://localhost:8080
  • scope: come l'ultimo passaggio - read e write

Quando mettiamo insieme tutto ciò, otteniamo un comando che dovrebbe assomigliare a:

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Ricorda: dovresti già averlo CLIENT_ID e CLIENT_SECRET ora, ma non lo abbiamo AUTH_CODE ancora.

3. Ottieni il codice di autorizzazione

Ora vai all’URL che abbiamo generato nel passaggio 1. Vedrai una pagina come questa:

Fai clic su Consenti per concedere l’accesso e verrai reindirizzato all’URL di reindirizzamento. Sembrerà una pagina interrotta, ma l’importante è cercare nell’URL per vedere qual è il codice di autorizzazione, ovvero tutto ciò che segue ?code=

Copia il codice e preparati per il passaggio finale. Il codice di autorizzazione è valido solo per un breve periodo. Se attendi più di qualche minuto, potrebbe essere necessario ripetere il passaggio precedente per ottenere un nuovo valore di codice.

4. Effettua la chiamata cURL per ottenere il token

Facendo riferimento alla nostra chiamata cURL che abbiamo creato nel passaggio 2, che assomiglia a questo

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

sostituireAUTH_CODE con il codice del passaggio 3 ed esegui il comando da un’applicazione terminale. Riceverai una risposta sotto forma di oggetto JSON come questo:

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. Prova il nuovo token

È sempre una buona idea provare le cose per confermare che hanno funzionato come previsto, quindi possiamo farlo ora. La chiamata più facile da effettuare è una semplice GET a /api/v2/chatsper vedere le informazioni del tuo account:

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

sostituzione TOKEN con quello recuperato nel passaggio 4. 

Ulteriori informazioni

Client_type riservato

Le sezioni precedenti illustrano il tipo di concessione "Implicito" e il tipo di concessione "Codice di autorizzazione". L’API Chat supporta anche il tipo di concessione riservata usando le credenziali client. Questo è descritto più dettagliatamente nella documentazione di riferimento in Tipi di sovvenzioni riservate.

Per le chiamate API usate da amministratori e agenti per attività quali i report delle metriche, potrebbe essere preferibile ottenere un token OAuth con il tipo di concessione riservata. Dovrai impostare il client_type come "riservato". Per impostazione predefinita, questo valore è impostato su "public". Questo può essere fatto solo tramite l’API e può essere ottenuto come segue:

1. Ottieni l’ID client

Per prima cosa, abbiamo bisogno dell’ID del tuo nuovo cliente. Puoi ottenerlo usando il tuo nuovo token, con la chiamata seguente:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

che ti mostrerà tutti i tuoi clienti. Puoi averne solo uno, ma se ne hai molti dovresti scegliere quello che vuoi aggiornare e annotarne l’ID.

2. Aggiorna client_type

Ora che disponi dell’ID del client, puoi eseguire la seguente chiamata cURL per aggiornare il file client_type proprietà:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

Al termine, il token può essere usato per gli endpoint con limitazioni.

Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.

Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.

Powered by Zendesk