Vai al contenuto principale

Articolo aggiornato: 4 febbraio 2022

API CRM Sparkcentral

L'integrazione di Sparkcentral CRM ti consente di estrarre i dati di contatto dei clienti dai CRM o da altre applicazioni aziendali interne in Sparkcentral. Per integrare il tuo CRM con Sparkcentral, devi fornire un endpoint HTTPS per le ricerche. Puoi anche fornire un endpoint HTTPS opzionale per la gestione delle richieste di writback e un endpoint HTTP per Sparkcentral per inviare notifiche dalla nostra applicazione al tuo CRM.

Sicurezza e autenticazione

Quando inviamo o riceviamo dati da Sparkcentral, forniamo due opzioni di autenticazione. Entrambi i meccanismi sono in atto in modo che tu possa assicurarti che la richiesta provenga da Sparkcentral.

Segreto condiviso

Quando scegli il meccanismo segreto condiviso e configuri un URL, ti viene assegnato un segreto. Con il segreto dato, puoi calcolare la firma che ti consente di verificare che la chiamata abbia avuto origine da Sparkcentral. Con questo meccanismo, ogni singola richiesta da Sparkcentral contiene l'intestazione X-Sparkcentral-Signature. Ecco un esempio di richiesta:

Copia

arricciatura -X POST https://sparkcentral-lookup -H 'content-type: application/json' -H 'accetta: applicazione/json' -H 'X-Sparkcentral-Firma: e6f93239a06e46ae9654fc9ad2fb4e1cc4eb213830a0d94e711570c047e43c57' -d '{"email":"fj@example.com"}'

La firma viene generata utilizzando l'algoritmo HMAC-SHA256 con il segreto condiviso e il corpo della richiesta. Usa il tuo segreto per calcolare la firma e confrontarla con la firma data. Sia la chiave segreta che hai ricevuto che la firma sono codificate come stringhe esadecimali. Assicurati di convertire il segreto condiviso dalla sua rappresentazione esadecimale nel formato binario prima di utilizzarlo. La maggior parte delle lingue è dotata di librerie predisposte per verificare questa firma. Ad esempio, ecco come appare in JavaScript:

Copia


const crypto = richiedono ("cripto");
const SparkCentralSecret ="... "; //non condividere!
const ExpectedSignature = request.headers ["X-Sparkcentral-Signature"];
const ActualSignature = cripto
.createHMAC ("sha256 ", buffer.from (SparkCentralSecret," esadecimale"))
.update (richiesta.body," utf-8")
.digest ("hex");
if (ActualSignature! == ExpectedSignature){
                throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
                }
console.log (JSON.parse (request.body) .email);

OAuth

Se i tuoi endpoint supportano OAuth2, puoi configurare le tue credenziali client, un URL token e facoltativamente un ambito in Sparkcentral.

Utilizziamo il flusso di credenziali client OAuth2 per autenticarci con il tuo CRM. L'URL del token è l'endpoint in cui possiamo autenticarci con queste credenziali e recuperare un token di accesso. Per eseguire la ricerca effettiva, la scrittura o le richieste di notifica, utilizziamo il token nell'intestazione di autorizzazione per l'autenticazione.

Cercare

Crea attributi di contatto

  1. In Sparkcentral, vai su Impostazioni amministratore, espandi Area di lavoro agente, seleziona Attributi contatto, quindi seleziona Aggiungi attributo.
  2. Nella casella Modifica attributo, seleziona Gestito da CRM. Il CRM è la fonte di verità per questi attributi. Dopo essere stati importati in Sparkcentral, cambiano solo quando il valore cambia nel CRM.
  3. Identificare gli attributi di ricerca selezionando Usa come attributo di ricerca. Questi vengono utilizzati dal CRM per trovare i dati di un cliente. Ad esempio, se desideri trovare un cliente tramite indirizzo e-mail, crea un attributo chiamato «Email» e designalo come ricerca. Quando la richiesta viene effettuata da Sparkcentral al tuo CRM, i campi di ricerca sono inclusi nel corpo della richiesta.
  4. Creare un alias per l'attributo. Nella casella Identificatore univoco immettere un alias per l'attributo di ricerca. Viene utilizzato per mappare la risposta dal sistema all'attributo.

Configura l'URL di integrazione

Per estrarre i dati dal tuo CRM in Sparkcentral, devi implementare un endpoint POST che accetti una richiesta JSON e restituisca una risposta JSON. La richiesta contiene gli attributi di ricerca e la risposta deve contenere i dati di contatto del tuo CRM

Dopo che l'endpoint è stato implementato, configuralo come URL di ricerca:

  1. Vai alle impostazioni dell'amministratore.

  2. Espandi l'integrazione e le API.

  3. Seleziona CRM.

Gestisci la richiesta

Quando l'endpoint nel sistema è pronto e configurato in Sparkcentral e sono stati identificati uno o più attributi di ricerca, è possibile effettuare una richiesta tramite il pulsante Lookup nella vista conversazione.

Dopo aver eseguito la ricerca nel sistema, passare gli attributi a Sparkcentral come risposta JSON. Le chiavi nell'oggetto attributes corrispondono agli alias precedentemente aggiunti in Sparkcentral. Se nell'oggetto manca un attributo gestito da CRM o se la chiave ha un valore nullo, il suo valore viene eliminato in Sparkcentral. Sparkcentral si aspetta la risposta in questo formato:

Risposta 200 (applicazione/json)

Copia
{
"AutoConfirm": false,
"attributi":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones",
"last_order_number": null
}
}

Conferma i tuoi attributi

Gli attributi CRM restituiti nella risposta devono essere confermati prima di essere salvati in Sparkcentral. Esistono due modi per farlo:

  • Selezionare il pulsante Conferma quando vengono visualizzati gli attributi CRM visualizzati in Sparkcentral dopo la richiesta di ricerca.
  • Aggiungi un campo di conferma automatica alla risposta:

Risposta 200 (applicazione/json)

Copia
{
"AutoConfirm": true,
"attributes":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones"
}
}

Il campo Conferma automatica indica a Sparkcentral di salvare automaticamente gli attributi senza dover utilizzare il pulsante Conferma.

Scrivi indietro

Puoi ricevere una notifica ogni volta che ha avuto luogo una conversazione in Sparkcentral o un agente imposta una conversazione corrente sullo stato in sospeso. Ciò consente di salvare i dettagli della conversazione sul sistema CRM esistente. Altri casi d'uso includono l'attivazione di sondaggi CSAT, la creazione di casi e approfondimenti estesi dei clienti dai profili dei social media.

Configurare l'URL di scrittura

Per inviare i dati da Sparkcentral al tuo CRM, devi implementare un endpoint POST che accetti una richiesta JSON e restituisca una risposta JSON. La richiesta contiene il payload di riscrittura e il codice di stato della risposta rappresenta la capacità dell'utente di analizzare il payload e la capacità del CRM di acquisire i dati

Configurare l'endpoint come URL di riscrittura:

  1. Vai alle impostazioni dell'amministratore.

  2. Espandi l'integrazione e le API.

  3. Seleziona CRM.

Gestisci la richiesta

Quando l'endpoint nel sistema è pronto e configurato in Sparkcentral e si verificano eventi rilevanti all'interno di Sparkcentral, le richieste vengono inviate all'endpoint configurato. Tutti i payload di writback decodificati hanno i seguenti campi:

  • type: Una stringa che definisce il tipo di richiesta di riscrittura in corso di elaborazione. Utilizzato per suggerire la struttura del campo dati.
  • version: Un numero che indica la versione del tipo di richiesta. Utilizzato per contrassegnare le modifiche alla struttura del campo dati.
  • idempotencyKey: una stringa che identifica in modo univoco ogni evento da riscrivere. Serve per garantire che ogni richiesta venga elaborata una sola volta.
  • data: Un oggetto che contiene dati strutturati per il tipo specifico di writback. Ad esempio, un evento di tipo CONVERSATION_RESOLVED ha campi come medium, channel, messaggi*, note, topics, contactProfile*, attributi* e agent, tra gli altri.

* Si applica a tutti i supporti tranne Twitter. La gestione di Twitter, i tweet e le trascrizioni dirette dei messaggi e gli attributi di contatto medio di Twitter (nome Twitter, numero di follower, ecc.), non vengono inviati nel payload, per conformarsi alle politiche di utilizzo dei dati di Twitter.

Eventi CONVERSATION_RESOLVED e CONVERSATION_SET_TO_PENDING

Gli eventi con un tipo di 'CONVERSATION_RESOLVED' o 'CONVERSATION_SET_TO_PENDING' hanno la seguente struttura di dati:

Copia
{
"timestamp":" 2021-04-28T 09:43:26 .635984618Z",
"IDempotencyKey ":" 6ebc6a78-d9e9-48be-b172-51eda40b7af8",
"versione": 1,
"tipo":"" CONVERSATION_RESOLVED,
"dati": {
"conversazione":{
      "id": "0ad42eef-a806-11eb-9642-f1ceb2f21def",
      "createdAt": "2021-04-28T09:42:27.004817183Z",
      "previousStatus": "new",
      "currentStatus": "resolved"
    },
"media":{
      "id": "smooch-whatsapp"
    },
"canale":{
      "id": "0-02534c5ac04-000-261ad914",
      "name": "channelname"
    },
"agente":{
      "id": "11599",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@Hootsuite.com"
    },
"Profilo di contatto":{
      "id": "693ed54b-a426-11eb-9363-cffd945b4b2f",
      "mediumContactProfileId": "bb7b0f8f00cc989b97f0725b",
      "primaryIdentifier": "John Smith",
      "secondaryIdentifier": "+32439487192",
      "pictureUrl": null
    }
", Stato Motivo aggiornato": "5fd023f6-2e66-11eb-be07-092841b0717d - Risposta Non richiesta",
"StatuUpdateCommento": "Non una domanda",
"stato aggiornato al":" 2021-04-28T 09:43:26 .532948586Z ",
"messaggi": [
{
        "id": "0ad20c0d-a806-11eb-9642-f799d0e531de",
        "direction": "INBOUND",
        "text": "Figuur"
      },
{
        "id": "10664516-a806-11eb-9642-fbd9d431bd78",
        "direction": "OUTBOUND",
        "text": "dsghkjsdgmhlknsdmglhkjmsdlgkhjmsdgkljhlmdkgjh"
      }
],
"Attributi di contatto": [
{
        "attribute": "smooch-whatsapp-profile-name",
        "value": "John Smith",
        "source": "MEDIUM"
      },
{
        "attribute": "smooch-whatsapp-phone-number",
        "value": "+32471263345",
        "source": "MEDIUM"
      }
{
        "attribute": "email",
        "value": "john.smith@Hootsuite.com",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "first_name",
        "value": "John",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "last_name",
        "value": "Smith",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "company",
        "value": "Hootsuite",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "spark-language",
        "value": "nl",
        "source": "CRM_CONFIRMED"
      }
],
"note": [],
"argomenti": []
}
}

Riprova a scrivere

Se la richiesta di riscrittura è scaduta o l'endpoint restituisce un codice di stato non riuscito (2XX), Sparkcentral riprova con backoff esponenziali. La richiesta viene inviata nuovamente con un ritardo di 1, 2, 4, 8, 16 e 32 ore dopo ogni nuovo tentativo (per un totale di 6 richieste), a condizione che la richiesta non abbia esito positivo. Se la richiesta non è ancora riuscita dopo 6 richieste, memorizziamo i dettagli della richiesta fallita per riferimento futuro. Si consiglia di controllare regolarmente i log degli endpoint per assicurarsi che le richieste di riscrittura vengano elaborate correttamente la prima volta. Per distinguere tra eventi unici, a ogni richiesta viene assegnata una chiave di idempotenza.

chiave di idempotenza

Le richieste di ripensamento di Sparkcentral utilizzano una chiave Idempotency, che consente all'endpoint di scrittura di garantire che elabori ogni richiesta una volta. Questa chiave aiuta quando le richieste vengono inviate più volte durante la pianificazione del nuovo tentativo, in modo che l'endpoint possa gestire le richieste in modo idempotente. La chiave è unica per richiesta.

Notifica

Configura l'URL di notifica

Quando invii gli attributi dei contatti gestiti dal CRM, Sparkcentral esegue alcune convalide sulla risposta. Per vedere gli errori di convalida, abbiamo fornito un modo per inviare notifiche da Sparkcentral al tuo sistema. È necessario fornire un endpoint POST che accetti un corpo di richiesta JSON. Configurare un URL di notifica nella stessa schermata in cui è stato configurato un URL di ricerca:

  1. Vai alle impostazioni dell'amministratore.

  2. Espandi l'integrazione e le API.

  3. Seleziona CRM.

Gestisci la richiesta

Quando si verificano errori di convalida, Sparkcentral invia una richiesta all'URL di notifica configurato. Una richiesta è simile alla seguente:

Copia
{
"timestamp": "2019-01-30T15:49:10.630397Z",
"version": 1,
"eventType": "DATA_IMPORT_ERROR",
"messages": [
"testMessage1 key:testKey1 value:testValue1",
"testMessage2 key:testKey2 value:testValue2"
]
}

La richiesta contiene questi due campi:

  • Tipo di evento
  • messages — una serie di messaggi di errore espliciti

Di seguito sono riportati i tipi di eventi che possono essere inviati da Sparkcentral.

tipi di evento
Tipo di evento Descrizione
DATA_IMPORT_ERROR Si è verificato un errore durante l'estrazione dei dati dal CRM a Sparkcentral.

La risposta a questa richiesta può essere un 204. Sparkcentral non si aspetta nulla nel corpo di risposta.

Altre azioni

Aggiorna

Il pulsante Aggiorna in Conversation View recupera nuovamente gli attributi gestiti dal CRM. Poiché questi attributi sono stati precedentemente confermati, la fase di conferma non è necessaria.

Scollega

Il pulsante Scollega in Conversation View rimuove gli attributi gestiti da CRM da Sparkcentral.

Confermare

Il pulsante Conferma memorizza le informazioni convalidate associate dal CRM nel database di Sparkcentral.

Chiaro

Il pulsante Cancella reimposta i dati estratti dall'endpoint di ricerca.

 

Non riesci a trovare quello che stai cercando? Siamo qui per aiutarti