API Sparkcentral Virtual Agent

Gli agenti virtuali Sparkcentral consentono alle aziende di aggiungere bot alla piattaforma come se fossero veri agenti. Possono rispondere ai messaggi in arrivo, risolvere conversazioni, applicare argomenti e impostare attributi di contatto. Invece di limitare le piattaforme bot che possono essere integrate, viene fornita un'API generica che è possibile utilizzare per integrarsi con qualsiasi piattaforma.

Per integrare la tua piattaforma bot preferita con Sparkcentral, dovrai fornire un endpoint HTTPS. Sparkcentral chiama questo endpoint ogni volta che una conversazione viene assegnata al tuo agente virtuale e ogni volta che il contatto invia un nuovo messaggio. Se utilizzi una piattaforma bot sincrona, puoi rispondere immediatamente a questa richiesta con la risposta. Se utilizzi una piattaforma bot asincrona, puoi anche inviare una richiesta POST a Sparkcentral per inviare una risposta a una conversazione.

Due tipi di agenti virtuali

Inception

Un agente virtuale inception rileva automaticamente le conversazioni private che iniziano nei canali a cui ha accesso. Se un agente virtuale inception ha bisogno di un agente umano, inserirà la conversazione nella nuova coda in modo che qualsiasi agente possa rispondere. L'agente virtuale di inizio può anche risolvere una conversazione se non è necessaria alcuna assistenza umana.

Poiché un agente virtuale inception rileva automaticamente le conversazioni nel canale a cui ha accesso, non è possibile creare più agenti virtuali inception che hanno accesso allo stesso canale.

Delegazione

Un agente virtuale di delega non rileva automaticamente le conversazioni. Invece, un agente umano può dare una conversazione a un agente virtuale di delega in qualsiasi momento della conversazione. A questo punto l'agente virtuale di delega subirà il sopravvento. La regola di consegna determina cosa dovrebbe accadere se un agente virtuale di delega ha bisogno di un agente umano. Se è selezionato «Nuova coda», la conversazione si sposta nella Nuova coda per essere ritirata da qualsiasi agente. Se è selezionato «agente precedente», l'agente virtuale di delega assegna la conversazione al precedente agente umano.

Più agenti virtuali di delega possono avere accesso allo stesso canale. Un agente umano deve selezionare specificamente l'agente virtuale per prendere il controllo della conversazione.

Aggiunta di un agente virtuale

Per aggiungere un agente virtuale:

1. Vai a Impostazioni di amministrazione, espandi Agenti virtuali, seleziona Agenti virtuali personalizzati, quindi seleziona Aggiungi agente virtuale personalizzato.
2. Immettere un nome per l'agente virtuale. Questo nome apparirà in Sparkcentral come «{Name}VA».
3. Specificare se si desidera che l'agente virtuale venga attivato come agente Inception o come agente Delegazione.
4. L'URL Webhook deve essere fornito per inviare correttamente le informazioni di conversazione all'agente virtuale (per ulteriori informazioni, vedere la sezione Webhook).
5. Compila i campi rimanenti a tuo piacimento, incluse le regole di consegna che desideri aggiungere.
6. Selezionare Salva.
7. Scorri verso il basso fino alla sezione Accesso ai canali e usa i comandi per selezionare un canale o canali a cui è possibile accedere a questo agente virtuale.

Agente virtuale di timeout

È possibile configurare due tipi di regole di contatto per gli agenti virtuali:

• Timeout Virtual Agent - Determina quando si verificherà una consegna se l'agente virtuale smette di rispondere per qualsiasi motivo. Il massimo è di 60 minuti.
• Contatto di timeout - Determina quando si verificherà una consegna se il contatto (utente) smette di rispondere. Il massimo è di 60 minuti.

Gestione degli errori

Se la connessione dell'agente virtuale si verifica un errore o se il contatto viene interrotta, è possibile effettuare le seguenti operazioni:

• Contrassegna la conversazione come Nuova o Risolta
• Applica automaticamente un argomento
• Se la conversazione è contrassegnata come Risolta, invia automaticamente una risposta standard al cliente

Modifica o eliminazione di un agente virtuale

Per modificare un agente virtuale, nella pagina Agenti virtuali personalizzati selezionare l'icona Modifica. Per eliminare un agente virtuale, seleziona l'icona Cestino.

Visualizza il segreto per un agente virtuale

Nella pagina Custom Virtual Agent, selezionare l'icona Modifica accanto all'agente virtuale. È possibile visualizzare o copiare il segreto condiviso generato per questo agente virtuale nella pagina Modifica agente virtuale personalizzato. Per ulteriori informazioni, consulta la sezione Protezione dei webhook.

Webhook

Quando una conversazione viene assegnata all'agente virtuale registrato nella sezione precedente, Sparkcentral ti invia un evento tramite l'URL configurato.

Vengono inviati tre eventi importanti:

• CONVERSATION_STARTED
• CONVERSATION_DELEGATO
• INBOUND_MESSAGE_RECEIVED

Campi comuni

Tutti gli eventi hanno alcuni campi comuni:

• type: Una stringa che definisce il tipo di evento si è verificato (attualmente CONVERSATION_STARTED o INBOUND_MESSAGE_RECEIVED). Nuovi eventi possono essere aggiunti in futuro. Evitare di rispondere con un errore a valori sconosciuti, ma ignorali. A seconda di questo tipo, la struttura dei dati sarà diversa.
• version: Un numero che indica la versione del tipo di richiesta. Attualmente, la versione è sempre 1. Le versioni verranno utilizzate in futuro per introdurre modifiche non compatibili con le versioni precedenti.
• iDempotencyKey: una stringa che identifica in modo univoco ogni evento. Quando si verifica un timeout durante l'invio dell'evento (o riceviamo una risposta di errore), riproveremo l'evento. Questa chiave può aiutarti a garantire che una richiesta venga elaborata una sola volta.
• timestamp: il timestamp quando abbiamo inviato la richiesta. Questo viene utilizzato per contrastare possibili attacchi di replay.
• data: oggetto che contiene dati strutturati per il tipo specifico. Ad esempio, un evento di tipo INBOUND_MESSAGE_RECEIVED contiene campi come ConversationId e message. I campi potrebbero essere aggiunti in futuro.

CONVERSATION_STARTED

L'evento CONVERSATION_STARTED viene inviato quando una conversazione viene assegnata all'agente virtuale Inception. Riceverai messaggi e sarai in grado di rispondere ai messaggi solo se la conversazione viene assegnata all'agente virtuale Inception.

Come parte di questo evento, ricevi informazioni aggiuntive sul profilo di contatto che cerca di contattarti, sul canale su cui ti stanno contattando e sugli attributi dei contatti. Gli attributi di contatto includono informazioni specifiche di medie dimensioni, informazioni aggiunte manualmente prima e informazioni provenienti dalle precedenti ricerche CRM. Notare che Inception Virtual Agent riceverà l'evento CONVERSATION_STARTED prima che venga eseguita qualsiasi ricerca CRM configurata e pertanto l'evento non includerà nuove informazioni dal CRM.

Dopo l'evento CONVERSATION_STARTED, riceverai un evento INBOUND_MESSAGE_RECEIVED per ogni messaggio inviato dal contatto, a partire dall'inizio della conversazione.

{
"iDempotencyKey":" 933d877e-a13f-4958-93a4-d5d4941bf624", 
"versione ": 1, 
"tipo":" CONVERSATION_STARTED", 
 "timestamp":" 2019-01-17T 16:46:51 .908736Z", 
"dati ": {
"conversationId":" 0-01d90bc1b13-000-9a9ca0d8", 
 "media":{ "id": "fb" }, 
"canale":{
"id": "0-019a0b43ad3-000-471aa28a",
"name": "Sparkcentral support channel"
}, 
 "Profilo di contatto":{
"id": "0-01835f0fec3-000-0a6c390a",
"mediumContactProfileId": "975734236828364800",
"primaryIdentifier": "jan_spark",
"secondaryIdentifier": "Jan Spark",
"pictureUrl": "http://image.com/sticky/default_profile_images/default_profile_normal.png"
}, 
"Attributi di contatto": [
 { "attribute": "company", "value": "Sparkcentral", "source": "AGENT" }, 
{
"attribute": "fb-profile-image",
"value": "https://image.com/sticky/default_profile_images/default_profile_normal.png",
"source": "MEDIUM"
}, 
{
"attribute": "fb-verified",
"value": "Not Verified",
"source": "MEDIUM"
}, 
{
"attribute": "fb-account-created",
"value": "March 19, 2018",
"source": "MEDIUM"
}, 
{
"attribute": "fb-handle-name",
"value": "jan_spark",
"source": "MEDIUM"
}, 
{ "attribute": "fb-name", "value": "Jan Spark", "source": "MEDIUM" }, 
 {
"attribute": "spark-url",
"value": "http://www.sparkcentral.com",
"source": "AGENT"
}
]
}
}

CONVERSATION_DELEGATO

L'evento CONVERSATION_DELEGATED viene inviato quando viene assegnata una conversazione all'agente virtuale Delegation. Come l'evento CONVERSATION_STARTED, contiene informazioni aggiuntive sul profilo di contatto che tenta di contattarti, sul canale su cui ti stanno contattando e sugli attributi dei contatti.

Dopo l'evento CONVERSATION_DELEGATED, riceverai un evento INBOUND_MESSAGE_RECEIVED per ogni messaggio inviato dal contatto, a partire da quando la conversazione viene assegnata all'agente virtuale. A differenza dell'evento CONVERSATION_STARTED, l'evento CONVERSATION_DELEGATED spesso non viene seguito immediatamente da un INBOUND_MESSAGE_RECEIVED. Invece, si prevede che l'agente virtuale porrà la prima domanda al contatto. Dopo aver ricevuto un evento CONVERSATION_DELEGATED, hai 2 minuti per porre questa prima domanda. Consulta i requisiti per ulteriori dettagli.

{
"timestamp":" 2019-03-28T 14:29:56 .727041Z", 
"IdempotencyKey ":" 8fa424c3-a88b-4f02-bd38-4e292a27597b", 
"versione": 1, 
 "tipo":" CONVERSATION_DELEGATED", 
"dati": {
"ConversationID":" 0-01f20ec5e10-000-860d4dde", 
"media ":{ "id": "fb" }, 
"canale":{
"id": "0-01e25845518-000-19087686",
"name": "JansDevFbChannel4"
}, 
"ContactProfile ":{
"id": "0-01f116a7f9c-000-b5d375aa",
"mediumContactProfileId": "cd067e88519aa063b15e9944",
"primaryIdentifier": "Anonymous",
"secondaryIdentifier": "Young Parrot",
"pictureUrl": null
}, 
"Attributi di contatto": [
{
"attribute": "fb-page-title",
"value": "In-Web Messaging Demo",
"source": "MEDIUM"
}, 
{
"attribute": "fb-page-url",
"value": "https://messenger-demoapp-dev/#JansDevSmoochChannel4",
"source": "MEDIUM"
}, 
{
"attribute": "fb-browser-language",
"value": "en-US",
"source": "MEDIUM"
}, 
{
"attribute": "fb-domain",
"value": "messenger-demoapp-dev",
"source": "MEDIUM"
}, 
{
"attribute": "fb-sdk-version",
"value": "1.14.2",
"source": "MEDIUM"
}
]
}
}

INBOUND_MESSAGE_RECEIVED

Dopo che la conversazione è stata assegnata all'agente virtuale e dopo aver ricevuto un evento CONVERSATION_STARTED o CONVERSATION_DELEGATED, inizierai a ricevere eventi INBOUND_MESSAGE_RECEIVED. Questi eventi si verificano ogni volta che il contatto invia un messaggio. Si noti che inviamo gli argomenti di conversazione con ogni evento INBOUND_MESSAGE_RECEUTED.

{
"idempotenza/chiave":" cc75552a-1a78-11e9-855e-6d1e71016abf", 
"versione ": 1, 
"tipo":" INBOUND_MESSAGE_RECEIVED", 
 "timestamp":" 2019-01-17T 16:56:16 .108626Z", 
"dati ": {
"ID conversazione":"" 0-01d90bc1b13-000-9a9ca0d8, 
 "message":{
"messageId": "cc75552a-1a78-11e9-855e-6d1e71016abf",
"text": "Hello",
"payload":"payload"
}, 
"Argomenti di conversazione": [
 "Argomento 1", 
"Argomento 2"
], 
"canale": {
"id": "0-019a0b43ad3-000-471aa28a",
"name": "Sparkcentral support channel"
}, 
"Profilo di contatto":{
"id": "0-01835f0fec3-000-0a6c390a",
"mediumContactProfileId": "975734236828364800",
"primaryIdentifier": "jan_spark",
"secondaryIdentifier": "Jan Spark",
"pictureUrl": "http://image.com/sticky/default_profile_images/default_profile_normal.png"
}, 
"medio": {
"id": "facebook"
}
}
} 

RISPOSTA

La tua risposta al webhook dovrebbe essere di 200 OK. Nel corpo, è possibile restituire la risposta che si desidera inviare al contatto:

{
"sendMessage":{ "text": "Hi! How can I help you?", "attachment": "funny_cat.gif" }, 
"applica Argomenti": [" Prenotazione" alberghiera], 
"ApplicaTags": ["Felice"], 
 "Imposta attributi di contatto":{ "account_number": "19758293529351" }, 
"completo":" "
"HANDOVER Applica note di conversazione": [{"text": "A note"}]
} 

• SendMessage: (Facoltativo) Il messaggio che si desidera inviare al contatto. È possibile inviare solo testo, solo un allegato o entrambi contemporaneamente. Se vuoi inviare un allegato, devi prima caricarlo, quindi ti consigliamo di utilizzare il flusso asincrono.
• ApplyTopics: (Facoltativo) L'elenco degli argomenti che si desidera applicare alla conversazione (l'intento o l'azione che il Virtual Agent ha abbinato). Gli argomenti che non esistono in Sparkcentral verranno ignorati.
• ApplyTags: l'elenco dei tag che si desidera applicare al messaggio dal contatto. I tag che non esistono in Sparkcentral verranno ignorati. È possibile utilizzare ApplyTags solo in risposta a un INBOUND_MESSAGE_RECEUTED. È anche possibile contrassegnare un messaggio specifico specificando il MessageID. In tal caso puoi rispondere usando" ApplyTags": [{"messageId": "cc75552a-1a78-11e9-855e-6d1e71016abf", "tag": "Happy"}].
• setContactAttributes: gli attributi che si desidera impostare su un contatto. L'oggetto è una mappa tra l'alias della definizione dell'attributo e il valore da impostare.
• completo. (Facoltativo) Può trattarsi di HANDOVER se si desidera dare la conversazione a un altro agente o RISOLTO se si desidera risolvere la conversazione. Quando passi HANDOVER, la regola di consegna configurata nelle impostazioni determina cosa accadrà dopo. Se la regola di consegna è «Nessuno», la conversazione viene inserita nella nuova coda senza un proprietario. Qualsiasi agente umano può riprendere la conversazione. Se la regola è stata impostata su «Agente precedente», la conversazione verrà assegnata al precedente agente umano. Se non c'era un agente precedente, la conversazione viene inserita nella nuova coda senza un proprietario.
• ApplyConversationNotes: (Facoltativo): note che devono essere aggiunte alla conversazione negli audit trail.

Se si sta effettuando l'integrazione con una piattaforma bot asincrona, è possibile restituire un corpo JSON vuoto {} e inviare questo messaggio utilizzando una richiesta di POST. Si consiglia inoltre di utilizzare l'API REST quando si desidera inviare un allegato. È possibile rispondere con {}, caricare un allegato utilizzando una richiesta PUT e quindi inviare l'allegato utilizzando una richiesta di POST.

Protezione dei webhook

Durante la configurazione di un agente virtuale, hai ricevuto una chiave segreta che puoi utilizzare per verificare se una richiesta di webhook in arrivo proviene realmente da Sparkcentral senza modifiche. Nelle intestazioni delle richieste di ogni chiamata webhook c'è X-Sparkcentral-Signature, che contiene una firma HMAC-SHA256 basata sul corpo della richiesta. Sia la chiave segreta che hai ricevuto che la firma sono codificate come stringhe esadecimali. La maggior parte delle lingue è dotata di librerie predisposte per verificare questa firma. Ecco alcuni esempi di codice per verificarlo in Node.js:

const SparkCentralSecret ="... "; //non condividere! 
const expectedSignature = request.headers ["X-Sparkcentral-Signature"]; 
const ActualSignature = crypto 
.createHMac ("sha256", buffer.from (SparkCentral Secret," hex")) 
.update (request.body," utf-8") 
.digest ("hex "); 
if (Signature effettive! == Firma prevista){
throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
}

if (
moment (JSON.parse (request.body) .timestamp) .isBefore (
moment () .subtract (5," minuti")
)
){
throw new createError.Unauthorized("Request too old");
}

Requisiti

Per offrire una buona esperienza al cliente, al webhook vengono imposti alcuni requisiti non funzionali. Quando viene inviato un webhook, hai 10 secondi per rispondere con un 200 OK. Se si verifica un timeout, riproveremo 3 volte utilizzando un backoff esponenziale (fino a 2 secondi). Se i guasti persistono durante i tentativi, la conversazione assegnata verrà consegnata a un agente umano inserendola nella Nuova coda.

Quando il contatto invia un messaggio tramite Sparkcentral, per impostazione predefinita ci aspettiamo che l'agente virtuale risponda a quel messaggio entro 5 minuti (utilizzando la risposta alla chiamata webhook o l'API REST). È possibile configurare il timeout nella schermata delle impostazioni per l'agente virtuale (Timeout Virtual Agent). Se l'agente virtuale non risponde al contatto, per impostazione predefinita la conversazione viene inserita nella Nuova coda affinché un agente umano venga ripresa. Questo può essere configurato anche in Impostazioni. Se preferisci, puoi risolvere automaticamente la conversazione e inviare un messaggio al contatto (ad esempio" Riprova tra poco"). L'agente virtuale potrebbe anche decidere di restituire immediatamente il controllo inviando RESOLVENT o HANDOVER nel campo completo.

Analogamente dopo un evento CONVERSATION_DELEGATED, l'agente virtuale ha 5 minuti per porre una domanda al contatto per impostazione predefinita. Se l'agente virtuale non riesce a farlo, la conversazione viene restituita al precedente proprietario della conversazione o inserita nella Nuova coda, a seconda della regola di consegna.

Autorizzazione

Se desideri inviare le risposte in modo asincrono o manipolare la conversazione nel codice di evasione, devi chiamare l'API REST dell'agente virtuale. L'API dell'agente virtuale utilizza il flusso di concessione credenziali client della specifica Oauth 2.0 per l'autenticazione e l'autorizzazione client.

Ai client vengono forniti un client_id e client_secret per autenticarsi con il server di autorizzazione di Sparkcentral e un access_token da utilizzare per l'autorizzazione delle richieste API. Access_token deve essere utilizzato in un'intestazione di autorizzazione, ma facoltativamente può essere passato come parametro stringa di query (vedere i dettagli richiesta/risposta nelle sezioni seguenti). Quando il token access_token scade, l'API restituisce un 401 non autorizzato. Il client può automatizzarlo generando un nuovo token di accesso e riproducendo la richiesta non riuscita con il nuovo token di accesso come documentato nella sezione seguente. Questo è lo stesso client_id e client_secret che potresti aver ricevuto per Proactive Messaging API o Realtime Reporting API.

Gli utenti di Sparkcentral con diritti di amministratore possono generare chiavi API in Impostazioni espandendo le &API di integrazione e selezionando Rest API Keys.

Concessione credenziali cliente

Recupera un access_token per effettuare richieste API autorizzate. Quando l'access_token scade, usa questo endpoint per generare un nuovo token.

RICHIESTA

Copia

$ curl -X POST https://public-api.sparkcentral.com/oauth2/token -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials& client_id=your_client_id_here& client_secret=your_client_secret_here &scope=client-read'

OR

$ curl -X POST https://public-api-eu.sparkcentral.com/oauth2/token -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials& client_id=your_client_id_here& client_secret=your_client_secret_here &scope=client-read'

RISPOSTA

{ “token_type”: “bearer”, “access_token”: “a1b2c3d4e5f6”, “expires_in”: 43200 }

La maggior parte delle piattaforme dispone di un supporto immediato per OAuth2. Ad esempio, in Node.js utilizzando axios-oauth-client è possibile eseguire le seguenti operazioni:

const axios = require ('axios'); 
const oauth = require ('axios-oauth-client'); 
const TokenProvider = require ('axios-token-interceptor'); 
const restClient = axios.create ({ baseURL: 'https://public-api.sparkcentral.com' }); //o public-api-eu.sparkcentral.com in EU 
const getClientCredentials = oauth.client ( axios,{
url: 'https://public-api.sparkcentral.com/oauth2/token',
grant_type: 'client_credentials',
client_id: process.env.SPARKCENTRAL_CLIENT_ID,
client_secret: process.env.SPARKCENTRAL_CLIENT_SECRET,
scope: 'client-read'
}); 
restClient.interceptors.request.use (oauth.interceptor (TokenProvider, getClientCredentials)); 

API Virtual Agent

Conversazioni

POST /virtual-agent/conversazioni/{conversationId}

Ciò consente di manipolare la conversazione nello stesso modo in cui si risponde a una richiesta di webhook. Puoi inviare una risposta, aggiungere un argomento e/o trasmettere la conversazione. Ogni proprietà nel corpo è facoltativa. Se vuoi solo inviare un messaggio, puoi inviare {"sendMessage": {"text": "Ciao! "}}. Se si desidera applicare un argomento e completare, ma non inviare un messaggio, è possibile, ad esempio, inviarlo {"applyTopics":["Spam"], "complete": "RESOLVED"}.

Si noti che solo gli argomenti che corrispondono esattamente a un argomento della piattaforma verranno applicati alla conversazione (senza distinzione tra maiuscole e minuscole). Gli argomenti non esistenti vengono ignorati. Al momento, non si verificherà alcuna corrispondenza fuzzy e gli errori tipografici comporteranno un argomento inesistente.

Lo stesso vale per i tag. Solo i tag che corrispondono esattamente a un tag nella piattaforma verranno applicati a un messaggio specifico (senza distinzione tra maiuscole e minuscole). I tag non esistenti vengono ignorati. Si noti che è obbligatorio specificare il MessageID quando si utilizza l'API REST. MessageID fa parte di ogni evento INBOUND_MESSAGE_RECEIVED.

Se si desidera inviare un allegato, è necessario prima caricare l'allegato in una chiamata separata (PUT /virtual-agent/conversations/{conversationId} /attachments/{filename}), quindi utilizzare il nome del file quando si invia il message ({"sendMessage": {"allegato":" "}}).

Se il contatto ha già un valore salvato per la definizione dell'attributo con un particolare alias, l'aggiornamento verrà ignorato. Se una qualsiasi delle definizioni degli attributi è configurata come valori di ricerca CRM, viene eseguita una ricerca CRM dopo l'impostazione degli attributi. Per ottenere prestazioni ottimali, si consiglia di impostare gli attributi di contatto insieme alla risposta per indicare che la conversazione è stata completata. Si noti che l'agente virtuale non riceverà i nuovi attributi dalla risposta CRM fino alla ricezione del prossimo evento CONVERSATION_STARTED o CONVERSATION_DELEGATED per una conversazione con un contatto.

URI di esempio

POST /Virtual-agent/Conversations/ConversationID

Parametri URI

ID conversazione

string (richiesto)

ID conversazione. Viene inviato come parte del payload webhook

Richiesta

Intestazioni

Copia

Tipo di contenuto: application/json 
Autorizzazione:< token portatore>

Corpo

Copia

{
"sendMessage":{
"text": " <message>",
"attachment": "<filename>"
}, 
"applica Argomenti": [
 "<argomento>"
], 
"applyTags": [
 {
"messageId": " <messageId>",
"tag": " <tag>"
}
], 
"Applica note di conversazione": [
{
"text": "A note"
}
], 
"Imposta attributi di contatto ":{
"<attribute_alias>": " <attribute_value>"
}, 
"complete"": CONSEGNA o RISOLTO" 
}

Schema

Copia

{
"$schema":" http://json-schema.org/draft-07/schema #", 
"title":" Una rappresentazione di cosa fare con una conversazione", 
"tipo":" oggetto",
 "richiesto": [],
" proprietà": {
 "sendMessage": {
"type":" object ",
" richiesto": ["testo"], 
"properties": {
"text": {
"type": "string"
}
},
" description":" Il messaggio che vuoi per inviare",
},
" ApplyTopics": {
 "tipo":" array",
 " elementi":{
"type": "string"
},
" descrizione": "Gli argomenti che vuoi applicare a una conversazione. "
},
" applyTags": {
 "tipo":" array",
" oggetti ": {
"type":" object", 
"richiesto": ["tag"," MessageID "],
" proprietà": {
"tag ":{
"type": "string"
},
" MessageID":{
"type": "string"
} 
}
},
" descrizione":" Gli argomenti che tu voglio candidarsi a una conversazione. "
},
" setContactAttributes": {
 "tipo" :" oggetto",
" PropertyNames":{
"pattern": "^[a-zA-Z0-9_]+$"
}, 
"Proprietà aggiuntive": true,
" descrizione" :" gli attributi che si desidera impostare su un contatto. "
},
" completo":{
"type": "string",
"description": "Finish a conversation by handing it off to a human agent or by marking the conversation resolved",
"enum": ["HANDOVER", "RESOLVED"]
} 
}
}

Risposta 200

I comandi sono accettati per l'esecuzione.

 

Intestazioni

Tipo di contenuto: application/json

 

Corpo

{}

Risposta 400

Corpo

La richiesta è malformata.

Risposta 401

Corpo

Non autorizzato: quando si utilizza un token di accesso non valido o scaduto.

Risposta 404

Corpo

L'ID conversazione non esiste o non è più assegnato all'agente virtuale.

allegati

PUT /virtual-agent/conversazioni/{conversationId} /allegati/{filename}

Ciò consente di caricare un allegato che puoi inviare in una conversazione. È necessario prima caricare l'allegato, quindi inviare un messaggio con testo e allegato. Ad esempio, se carichi un allegato su /virtual-agent/conversations//attachments/cat.jpg, puoi inviare tale allegato inviando {"sendMessage": {"text ":" Questo è un gatto! "," allegato":" cat.jpg"}} a /virtual-agent/conversations/. Il nome del file deve essere univoco all'interno di una conversazione ed è visibile al contatto se scarica il tuo allegato.

L'intestazione Content-Type deve contenere il tipo mime-type corretto dell'allegato (ad esempio 'image/jpeg'). L'intestazione Content-Length dovrebbe contenere la dimensione dell'allegato in byte. Gli allegati devono essere inferiori a 10 megabyte per evitare errori.

URI di esempio

PUT /Virtual-agent/conversations/conversationID/allegati/nomefile

Parametri URI

ID conversazione

string (richiesto)

ID conversazione. Viene inviato come parte del payload webhook

 

nome del file

string (richiesto)

Nome file dell'allegato. Il nome del file può contenere solo lettere maiuscole e minuscole, numeri, "-", "_" e ".".

Richiesta

Intestazioni

Autorizzazione:< gettone portatore>

<Content-Type: tipo MIME dell'attacco>

Content-Length:< dimensione dell'attacco in byte>

 

Corpo

dati binari

Risposta 200

L'allegato è caricato e pronto per l'uso nella conversazione. Nota: dopo aver caricato l'allegato su Sparkcentral, devi comunque inviarlo specificamente al contatto.

 

Intestazioni

Tipo di contenuto: application/json

 

Corpo

{}

Risposta 400

Corpo

La richiesta è malformata. Ciò può accadere perché il nome del file contiene un carattere non valido o perché il tipo di allegato non può essere inviato al supporto.

Risposta 401

Corpo

Non autorizzato: quando si utilizza un token di accesso non valido o scaduto.

Risposta 404

Corpo

L'ID conversazione non esiste o non è più assegnato all'agente virtuale.