Per consentire un'analisi rapida dei metadati dei record CRM, gli SDK web e mobile della piattaforma CCAI e l'API Apps (Chat) possono inviare dati ai campi personalizzati del CRM.
La mappatura dei campi personalizzati consente di mappare le chiavi dei dati dei clienti personalizzati della piattaforma CCAI (UI del portale: Etichetta campo dati personalizzato) ai campi o alle proprietà del CRM in modo che i valori mappati vengano scritti automaticamente nel record CRM appropriato.
Le chiavi dei dati personalizzati possono essere fornite da:
SDK web e mobile di CCAI Platform o
API Apps (chat) utilizzando l'endpoint Invia dati personalizzati in una chat.
Esempio di API SDK per dispositivi mobili
Le sezioni seguenti descrivono un esempio specifico per l'SDK per dispositivi mobili.
Dati dall'SDK al server
{
custom_data: { # same format with previous custom data from SDK
data_name: {
value: value,
type: string,
label: "Data Name",
},
device: { # example
value: "iOS",
type: "string",
label: "Device Type"}
}
}
Dati dal server all'adattatore CRM
{
key: {
crm_field: "crm custom field name",
type: "text", # text / checkbox ...,
value: "value"
},
device: { # example
crm_field: "device",
type: "text",
value: "iOS"
}
}
Endpoint API
È possibile accedere alla mappatura dei campi personalizzati del CRM utilizzando un'API. Sono disponibili i seguenti endpoint:
Recupera tutti i campi: HTTP POST o GET:
/crm_custom_fieldsAggiorna o elimina un campo specifico: HTTP PUT o DELETE
/crm_custom_fields/:id
Esempio di API Apps (chat) (senza SDK)
I clienti che utilizzano direttamente l'API Apps (senza gli SDK web o mobile della piattaforma CCAI) possono comunque utilizzare la mappatura dei campi personalizzati per le interazioni di chat inviando dati personalizzati per una sessione di chat esistente.
- Endpoint:
POST /apps/api/v1/chats/:id/custom_data
Corpo della richiesta (non protetto/non firmato)
{
"signed": false,
"data": {
"orderId": {
"label": "Order ID",
"value": "12345"
},
"customerTier": {
"label": "Customer Tier",
"value": "gold"
}
}
}
Corpo della richiesta (JWT protetto/firmato)
{
"signed": true,
"signed_data": "<JWT>"
}
Forma del payload JWT (esempio)
{
"custom_data": {
"orderId": { "label": "Order ID", "value": "12345" },
"customerTier": { "label": "Customer Tier", "value": "gold" }
},
"exp": 1734567890,
"iat": 1734560000
}
Applica la mappatura dei campi personalizzati ai payload dell'API Apps
Nel portale della piattaforma CCAI, imposta Etichetta campo dati personalizzato (chiave dati personalizzata) sulla chiave di primo livello nell'oggetto data del payload dell'API Apps (ad esempio, orderId o customerTier) e mappala al campo o alla proprietà CRM selezionati.
Di seguito sono riportati due esempi:
- Mappe per chiave:
orderId,customerTier - Non esegue la mappatura in base all'etichetta nidificata:
"label": "Order ID"è un testo visualizzato e non viene utilizzato per la mappatura.
Chiavi riservate (flag del cliente)
Potresti visualizzare chiavi riservate come:
reserved_verified_customerreserved_bad_actorreserved_repeat_customer
Queste chiavi vengono utilizzate principalmente per il comportamento dei flag dei clienti. Per evitare confusione, non mappare le chiavi reserved_* come campi personalizzati del CRM, a meno che tu non abbia un'esigenza di reporting specifica. Preferisci la mappatura di chiavi specifiche dell'attività (come orderId, customerTier e così via) per la mappatura dei campi personalizzati del CRM.
Passaggi per configurare la mappatura dei campi CRM personalizzati
Crea il campo personalizzato e i valori nel tuo CRM.
Assegna i nuovi valori ai contatti nel tuo CRM.
Configura l'impostazione nel portale della piattaforma CCAI.
Prova.
Configurazione di Zendesk
Le sezioni seguenti descrivono la procedura per configurare le mappature dei campi per il CRM Zendesk.
Crea un campo personalizzato per Utente (Contatto)
Accedi a Zendesk come amministratore.
Fai clic su per accedere alle opzioni di amministrazione.
Seleziona Campi utente.
Seleziona il tipo di campo che vuoi creare.

Aggiungi un titolo e un nome per il campo nella visualizzazione di un agente.
Il campo Chiave campo viene compilato automaticamente.
Fai clic su Crea campo.
Ora puoi vedere questo nuovo campo nell'elenco Campi attivi e questo nuovo campo viene visualizzato nella colonna a sinistra quando visualizzi un utente.

Crea un campo personalizzato per Ticket
Accedi a Zendesk come amministratore.
Fai clic sull'icona per accedere alle opzioni di amministrazione.
Seleziona Campi ticket.
Fai clic sul pulsante Aggiungi campo personalizzato.
Seleziona un tipo di campo che vuoi creare facendo clic su Seleziona.
Aggiungi un titolo del campo. Il titolo del campo verrà visualizzato nella visualizzazione dell'agente.
Ti consigliamo di utilizzare lo stesso valore di crm_field dell'API.

Fai clic sul pulsante Aggiungi campo.
Ora puoi vedere questo nuovo campo nell'elenco Campi attivi e questo nuovo campo viene visualizzato nella colonna a sinistra quando visualizzi un ticket.
Configurazione di Salesforce
Vai a Configurazione.
Seleziona Object Manager (Gestore oggetti).
Scegli l'oggetto a cui vuoi aggiungere i campi personalizzati (Case o CCAI Platform Session).
Fai clic su Fields & Relationships (Campi e relazioni).
Fai clic su New (Nuovo).
Seleziona Testo come tipo di dati.
In Etichetta campo, inserisci un nome per il campo.
In Length (Lunghezza), inserisci 255.
Il Nome campo dovrebbe essere compilato automaticamente dopo aver inserito l'Etichetta campo.

Puoi lasciare le altre variabili al loro valore predefinito.
Fai clic su Avanti.
Seleziona la casella Visibile per tutti i profili che accedono all'oggetto (richiesta o sessione della piattaforma CCAI).
Fai clic su Avanti.
Fai clic su Salva.
In questo modo tornerai alla visualizzazione Fields & Relationships (Campi e relazioni). Trova il campo appena creato e prendi nota del Nome campo.

Il Nome campo è quello che inserirai in Etichetta campo CRM nella pagina di mappatura dei campi personalizzati della piattaforma CCAI.
L'esempio seguente mostra l'aspetto di un nuovo campo quando viene configurato e utilizzato correttamente nell'oggetto richiesta:

Configurazione di Kustomer
Per informazioni dettagliate sulla configurazione dei campi personalizzati, consulta il Centro assistenza Kustomer.
Configurazione di CCAI Platform
Le sezioni seguenti descrivono le modifiche necessarie nel portale della piattaforma CCAI per configurare la mappatura dei campi del CRM Kustomer:
Nel portale della piattaforma CCAI, vai a Impostazioni > Gestione delle operazioni.
Vai alla sezione Mappatura dei campi personalizzati del CRM e fai clic su Visualizza tutto.
Fai clic sul link + Aggiungi mappatura dei campi CRM.
Titolo della mappatura dei campi: nome della piattaforma CCAI per questa mappatura dei campi personalizzati utilizzata nel portale della piattaforma CCAI.
Etichetta campo CRM: etichetta all'interno del CRM del campo CRM a cui stai eseguendo la mappatura.
Etichetta del campo di dati personalizzato: l'etichetta del campo di dati personalizzato da cui esegui la mappatura.
Esempi di SDK:
data_name,device(dacustom_data object)Esempi di API Apps (Chat):
orderId,customerTier(dall'oggetto dati della richiesta dell'API Apps).
Fai clic su Salva.