Orchestrate API

L’API “Orchestrate” innesca il processo di elaborazione dell’input fornito dall’utente, che si traduce nell’esecuzione dei connettori presenti all’interno della journey invocata.

L’input dell’utente è solitamente costituito da una query, in formato testuale o audio, oppure da un evento. Tellya innescherà il riconoscimento e l’interpretazione dell’input attraverso il motore di NLU configurato all’interno della journey invocata.

A seconda che siano presenti altri connettori o configurazioni all’interno della journey (oltre a quello che rappresenta il motore di NLU), Tellya potrebbe elaborare l’input dell’utente prima che venga sottoposto al motore di NLU e/o modificare il risultato fornito dal motore di NLU prima di restituirlo in risposta.

Method

POST: {basePath}/chat/api/v2/orchestrate/{apiKey}

Il request URL completo del metodo POST da invocare (completo di {basePath e {apiKey}) può essere visualizzato all’interno delle impostazioni della journey con cui si vuole interagire (nella sezione “Server integration”).

Path Parameters

Parameters
apiKey	String Obbligatorio Identificativo univoco della journey
cleanResponse	Boolean Default value: false
customResponses	Boolean Default value: false Permette di stabilire se in risposta si desidera ricevere le risposte configurate per il canale “Tellya” (false) oppure quelle definite per un canale “Custom” (true). Nel caso il parametro sia impostato a “true” ma non siano presenti risposte configurate per il canale “Custom” verranno selezionare le risposte configurate per il canale “Default”.
save	Boolean Default value: true Permette di stabilire se salvare l’interazione nella history conversazionale e nelle analitiche (true), oppure no (false). La disabilitazione di tale parametro viene tipicamente utilizzata quando non si vogliono compromettere i dati e le metriche delle interazioni reali con quelle di ambienti di test (nel caso di singola journey che assolve entrambi i compiti).

Request body

Ogni richiesta di Orchestrate deve contenere un input (tipicamente fornito o innescato dall’utente) da far processare al motore di NLU e alla journey Tellya. Sono supportate tre tipologie di input (audio, event, query), ma per ogni interazione ne deve essere utilizzata una soltanto.

Input fields
audio	String Obbligatorio. Formato wav mono codificato in Base64.
event	Object Obbligatorio. Un evento da processare che specifica quale intento o stato attivare.
query	String Obbligatorio. Rappresenta il testo in linguaggio naturale da elaborare, la richiesta dell’utente da ricondurre ad un intento. La lunghezza del testo non deve superare i 256 caratteri.

Input fields

audio

String

Obbligatorio. Formato wav mono codificato in Base64.

event

Object

Obbligatorio. Un evento da processare che specifica quale intento o stato attivare.

query

String

Obbligatorio. Rappresenta il testo in linguaggio naturale da elaborare, la richiesta dell’utente da ricondurre ad un intento. La lunghezza del testo non deve superare i 256 caratteri.

Other fields
audioOutputRequired	Boolean Per definire se ricevere o meno in output anche la risposta audio codificata in Base64.
audioOutputSampleRate	Integer Sample rate in Hertz con cui si desidera ricevere l’output audio. Valore minimo limite: 8000.
context	Object L’insieme dei contesti da attivare prima dell’esecuzione della query (disponibile solo con Dialogflow ES).
lang	String Obbligatorio. La lingua di questa interazione conversazionale.
journeyCode	String Obbligatorio. Parametro da configurare nel chat widget e che indica la journey di default che deve essere chiamata.
queryParametersMap	Object Parametri che si vogliono inserire direttamente quando avviene la chiamata al motore di NLU. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue). Può essere utilizzata solo con le query e audio.
sessionId	String Obbligatorio. Identificativo univoco della sessione a cui viene inviata la query.
userData	Object Informazioni aggiuntive relative alla sessione. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

Context

I contesti consentono di instradare il dialogo e guidare la conversazione nella direzione desiderata.

I contesti di output definiscono l’argomento della conversazione e servono a instradare le successive richieste degli utenti.
I contesti di input rappresentano le condizioni per le quali l’intento può essere innescato.

Il concetto di “contesto” è presente esclusivamente per Dialogflow ES.

Fields
lifespan	Integer Opzionale. Il numero di richieste di conversazionali dopo le quali il contesto scade. Il valore predefinito è 0. Se impostato su 0, il contesto scade immediatamente.
name	String Obbligatorio. L’identificatore univoco del contesto. Può contenere solo caratteri a-zA-Z0-9_-% e può essere lungo al massimo 250 byte.
parameters	Object Opzionale. L’insieme dei parametri associati al contesto. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

Fields

lifespan

Integer

Opzionale. Il numero di richieste di conversazionali dopo le quali il contesto scade. Il valore predefinito è 0. Se impostato su 0, il contesto scade immediatamente.

name

String

Obbligatorio. L’identificatore univoco del contesto. Può contenere solo caratteri a-zA-Z0-9_-% e può essere lungo al massimo 250 byte.

parameters

Object

Opzionale. L’insieme dei parametri associati al contesto. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

Event

Fields
data	Object Opzionale. L’insieme dei parametri associati all’evento. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).
name	String Obbligatorio. L’identificativo univoco dell’evento

Fields

data

Object

Opzionale. L’insieme dei parametri associati all’evento. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

name

String

Obbligatorio. L’identificativo univoco dell’evento

Esempio input audio

JSON representation

JSON representation
`{ "audio": "UklGRiSgAgBXQVZFZm10IBAAAAABAAEAgLsAAAB3AQACABA", "audioOutputRequired": true, "audioOutputSampleRate": 8000, "contexts": [ { "lifespan": 0, "name": "context-name-1", "parameters": { "context-parameter-name-1": "context-parameter-value-1" } } ], "event": null, "lang": "it", "query": null, "journeyCode": null, "sessionId": "144004629999", "userData": { "agentChannel": 6 }, "queryParametersMap": { "parameter_name": "parameter_value" } }`

{  
      "audio": "UklGRiSgAgBXQVZFZm10IBAAAAABAAEAgLsAAAB3AQACABA",
      "audioOutputRequired": true,
      "audioOutputSampleRate": 8000,  
      "contexts": [
        {      
          "lifespan": 0,
          "name": "context-name-1",
          "parameters": {
            "context-parameter-name-1": "context-parameter-value-1"
          }    
        } 
      ],  
      "event": null, 
      "lang": "it",  
      "query": null,  
      "journeyCode": null,
      "sessionId": "144004629999",  
      "userData": {
        "agentChannel": 6
      },
      "queryParametersMap": {
        "parameter_name": "parameter_value"
      }
    }

Esempio event

JSON representation

JSON representation
`{ "audio": null, "contexts": [ { "lifespan": 0, "name": "context-name-1", "parameters": { "context-parameter-name-1": "context-parameter-value-1" } } ], "event": { "data": { "event-parameter-name-1": "event-parameter-value-1" }, "name": "event-name" }, "lang": "it", "query": null, "journeyCode": null, "sessionId": "144004629999", "userData": { "agentChannel": 6 }, "queryParametersMap": { "parameter_name": "parameter_value" } }`

{  
      "audio": null,  
      "contexts": [
        {      
          "lifespan": 0,
          "name": "context-name-1",
          "parameters": {
            "context-parameter-name-1": "context-parameter-value-1"
          }    
        } 
      ],  
      "event": {    
        "data": {      
          "event-parameter-name-1": "event-parameter-value-1"  
        },    
        "name": "event-name"  
      },  
      "lang": "it",  
      "query": null,  
      "journeyCode": null,
      "sessionId": "144004629999",  
      "userData": {
        "agentChannel": 6
      },
      "queryParametersMap": {
        "parameter_name": "parameter_value"
      }
    }

Esempio query

JSON representation

JSON representation
`{ "audio": null, "contexts": [ { "lifespan": 0, "name": "context-name-1", "parameters": { "context-parameter-name-1": "context-parameter-value-1" } } ], "event": null, "lang": "it", "query": "Ciao", "journeyCode": null, "sessionId": "144004629999", "userData": { "agentChannel": 6 }, "queryParametersMap": { "parameter_name": "parameter_value" } }`

{  
      "audio": null,
      "contexts": [
        {      
          "lifespan": 0,
          "name": "context-name-1",
          "parameters": {
            "context-parameter-name-1": "context-parameter-value-1"
          }    
        } 
      ],  
      "event": null,  
      "lang": "it",  
      "query": "Ciao",  
      "journeyCode": null,
      "sessionId": "144004629999",  
      "userData": {
        "agentChannel": 6
      },
      "queryParametersMap": {
        "parameter_name": "parameter_value"
      }
    }

Response

Code	Description
200	OK
404	Not Found
500	Internal Server Error

Response body

Fields
extraResult	String Ulteriori risultati specifici riguardanti i dettagli.
results	Object L’insieme dei risultati relativi all’elaborazione effettuata dal motore di NLU e dall’esecuzione della journey Tellya.
status	String Codice di stato della chiamata.

Fields

extraResult

String

Ulteriori risultati specifici riguardanti i dettagli.

results

Object

L’insieme dei risultati relativi all’elaborazione effettuata dal motore di NLU e dall’esecuzione della journey Tellya.

status

String

Codice di stato della chiamata.

Results

Fields
aiResponse	Object L’insieme dei risultati derivanti dall’elaborazione effettuata dal motore di NLU.
naturalLanguageResponse	Object Risultati dell’elaborazione effettuata dal connettore Natural Language Understanding.
translateResponse_question	Object Risultati dell’elaborazione effettuata dal connettore Translate (input).
translateResponse_answer	Object Risultati dell’elaborazione dal connettore Translate (output).

aiResponse

Fields
id	String Id di chiamata del motore NLU.
idMessage	String Identificativo univoco del messaggio.
lang	String La lingua di questa interazione conversazionale.
result	Object Oggetto che contiene tutte le informazioni restituite dal motore di NLU.
sessionId	String Id assegnato alla conversazione.
timestamp	String Data e ora in cui viene invocato il motore di NLU per risolvere l’interazione conversazionale.

aiResponse.result

Fields
action	String Azione configurata all’interno del motore NLU.
context	Object L’insieme dei contesti che vengono restituiti a seguito dell’esecuzione della query.
fulfillment	Object Oggetto contenente le informazioni della risposta restituita dal motore di NLU.
metadata	Object Oggetto contenente le informazioni recuperate dal motore di NLU a seguito della chiamata.
parameters	Object L’insieme dei parametri che sono stati validati a seguito dell’interazione.
resolvedQuery	String Query imputata al motore NLU.
score	Integer Punteggio assegnato al motore NLU.

context

Fields
lifespan	Integer Il numero di richieste di conversazionali dopo le quali il contesto scade. Il valore predefinito è 0. Se impostato su 0, il contesto scade immediatamente.
name	String L’identificatore univoco del contesto. Può contenere solo caratteri a-zA-Z0-9_-% e può essere lungo al massimo 250 byte.
parameters	Object L’insieme dei parametri associati al contesto. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

Fields

lifespan

Integer

Il numero di richieste di conversazionali dopo le quali il contesto scade. Il valore predefinito è 0. Se impostato su 0, il contesto scade immediatamente.

name

String

L’identificatore univoco del contesto. Può contenere solo caratteri a-zA-Z0-9_-% e può essere lungo al massimo 250 byte.

parameters

Object

L’insieme dei parametri associati al contesto. Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue).

fulfillment

Fields
audioOutput	String Audio in formato wav mono codificato in Base64 della risposta restituita dal motore di NLU.
messages	Object Oggetto che definisce le risposte ricevute dal motore di NLU.

Fields

audioOutput

String

Audio in formato wav mono codificato in Base64 della risposta restituita dal motore di NLU.

messages

Object

Oggetto che definisce le risposte ricevute dal motore di NLU.

metadata

Fields
allRequiredParamsPresent	Boolean Parametro che controlla se tutti i parametri richiesti sono stati recuperati.
endOfConversation	Boolean Parametro che controlla se l’intento scatenato deve terminare la conversazione (disponibile solo con Dialogflow ES).
event	Object Evento scatenato.
flow	Object Nome del flow nel quale si sta svolgendo l’interazione (disponibile solo con Dialogflow CX).
intentId	String Id assegnato all’intento.
intentName	String Nome assegnato all’intento.
isFallbackIntent	Boolean Indica se si tratta di un intento di fallback.
landedPage	Object Pagina di atterraggio a seguito di una transition (disponibile solo con Dialogflow CX).
transitionPage	Object Pagina attraverso la quale è transitata la conversazione (disponibile solo con Dialogflow CX).
transitionRoute	String identificativo della transizione effettuata (disponibile solo con Dialogflow CX).
webhookForSlotFillingUsed	Boolean Se abilitato, il motore di NLU invia una chiamata al webhook ogni volta che viene richiesto un parametro obbligatorio nell’intento (disponibile solo con Dialogflow ES).
webhookTag	String PTag che identifica il webhook utilizzato (disponibile solo con Dialogflow CX).
webhookUsed	Boolean Indica se è stato usato un webhook.

messages

Fields
items	Object Oggetto che contiene il payload di costruzione dell’elemento grafico.
iterable	Boolean Valore che indica se la risposta è di tipo “Dynamic“.
nextTextValue	String Se l’elemento grafico è paginato, indica il testo da mostrare nel campo sul pulsante “Next”.
order	Integer Indica l’ordine con il quale la risposta deve essere mostrata all’utente.
pageSize	Integer Se l’elemento grafico è paginato, indica il numero di elementi da mostrare.
paginated	Boolean Indica se la risposta deve essere paginata.
payload	Object Oggetto MAP utilizzato per gli elementi grafici o i custom payload configurati come risposta.
speech	String Testo in formato SSML renderizzabile dai motori audio compatibili con il protocollo.
text	String Testo in risposta da visualizzare.
type	String Indica la tipologia di risposta (card, list, suggestions, uploadFiles).

item type: card

Fields
body	String Contiene la descrizione della card.
button	Object Definisce il comportamento del pulsante.
image	String Link dell’immagine.
subtitle	String Contiene il sottotitolo della card.
title	String Contiene il titolo della card.

item type: list

Fields
button	Object Definisce il comportamento del pulsante.
image	String Link dell’immagine.
subtitle	String Contiene il sottotitolo della card.
title	String Contiene il titolo della card.

item type: suggestions

Fields
title	String Contiene il titolo della card.
value	String CValore da inviare in chat al click sul pulsante.

Fields

title

String

Contiene il titolo della card.

value

String

CValore da inviare in chat al click sul pulsante.

item type: uploadFile

Fields
disableChat	Boolean Indica se disabilitare la chat fino al caricamento del file.
event	String Evento da richiamare al caricamento del file.
files	Object array Array di oggetti che definisce la tipologia di file da caricare.
file.extensionTypes	String Array Array di stringhe che definiscono il formato di file che può essere caricato.
file.maxSize	Integer Indica la dimensione massima che il file può avere in Mb.
file.title	String Contiene il titolo da mostrare all’utente in chat.

items.button

Fields
type	String Definisce la tipologia di azione da eseguire (Link, value e disable).
url	String Indirizzo url da aprire al click sul pulsante.
value_name	String Testo mostrato sul pulsante.
value	String Valore da inviare in chat al click sul pulsante.

naturalLanguageResponse

Fields
sentiment	Double Valore di “sentiment” (score) restituito dal connettore Natural Language Understading.
magnitude	Double Valore di “magnitude” restituito dal connettore Natural Language Understading.
textAnalyzed	String Testo analizzato dal connettore Natural Language Understanding.
noValues	Boolean Indica se è stato analizzato del testo oppure no.

translateResponse_question

Fields
languageTextAnalyzed	String Lingua risultante dall’analisi del testo.
textAnalyzed	String Testo che è stato analizzato.
overrideRequestLanguage	Boolean Valore configurato all’interno del connettore Translate (opzione “Override Front End language detection”)
languageTextTarget	String Lingua di output.
textResult	String Testo risultante dalla traduzione.

translateResponse_answer

Fields
languageTextAnalyzed	String Lingua risultante dall’analisi del testo.
textAnalyzed	String Testo che è stato analizzato.
overrideRequestLanguage	Boolean Valore configurato all’interno del connettore Translate (opzione “Override Front End language detection”)
languageTextTarget	String Lingua di output.
textResult	String Testo risultante dalla traduzione.

extraResult

Fields
currentJourneyCode	String Codice della journey corrente nel caso si utilizzi il dispatcher.
detectWithInputContext	Boolean Indica se l’intento riconosciuto è vincolato da un contesto di input.
manageByOperator	Boolean Indica se l’operazione é stata passata all’operatore o se é stata gestita autonomamente.
singleResult	Object Oggetto MAP contenente i risultati di azioni.
skipIntent	Boolean Indica se l’intento deve essere saltato.
switchedAgent	Boolean Indica se l’agente è stato switchato a seguito dell’intervento del dispatcher.
topics	List Elenco dei Tag di tipo Topics che sono stati configurati.
trusted	String Definisce se un intento viene definito “trusted” o “untrusted”.
warningList	List Elenco degli errori che non compromettono l’avanzamento della conversazione.

Esempio (Status Code 200)

Dialogflow ES

JSON representation

JSON representation
{ "status": 200, "results": { "aiResponse": { "idMessage": "b79a2c53-8096-4f60-a23a-a9929cfe5cde", "lang": "it", "id": "b4749f07-6b62-4dbd-98bd-8f0add714f45-5fd6c646", "timestamp": "2022-02-18T16:17:03Z, "sessionId": "144004629999", "result": { "resolvedQuery": "Ciao", "action": "provaAction", "score": 1.0, "parameters": {}, "contexts": [ { "lifespan": 99, "name": "context-name", "parameters": {}, } ], "metadata": { "isFallbackIntent": false, "intentName": "Default Welcome Intent", "intentId": "2fcc5f96-27d5-41c9-a676-3841e7defb6d", "flow": null, "landedPage": null, "transitionPage": null, "transitionRoute": null, "event": null, "webhookTag": null, "webhookUsed": false, "webhookForSlotFillingUsed": false, "allRequiredParamsPresent": true, "endOfConversation": false }, "fulfillment": { "audioOutput": null, "messages": [ { "speech": null, "text": "Ciao!", "platform": "PLATFORM_UNSPECIFIED", "order": 0, "iterable": null, "payload": null, } ] } } } }, "extraResult": { "singleResult": {}, "details": { "assistant": null, "skipIntent": false, "detectWithInputContext": false, "trusted": null, "manageByOperator": true, "currentJourneyCode": null, "switchedAgent": false, "warningList": [], "topics": [ "default" ] } } }

{
      "status": 200,
      "results": {
        "aiResponse": {
          "idMessage": "b79a2c53-8096-4f60-a23a-a9929cfe5cde",
          "lang": "it",
          "id": "b4749f07-6b62-4dbd-98bd-8f0add714f45-5fd6c646",
          "timestamp": "2022-02-18T16:17:03Z,
          "sessionId": "144004629999",
          "result": {
            "resolvedQuery": "Ciao",
            "action": "provaAction",
            "score": 1.0,
            "parameters": {},
            "contexts": [
              {
                "lifespan": 99,
                "name": "context-name",
                "parameters": {},
              }
            ],
            "metadata": {
              "isFallbackIntent": false,
              "intentName": "Default Welcome Intent",
              "intentId": "2fcc5f96-27d5-41c9-a676-3841e7defb6d",
              "flow": null,
              "landedPage": null,
              "transitionPage": null,
              "transitionRoute": null,
              "event": null,
              "webhookTag": null,
              "webhookUsed": false,
              "webhookForSlotFillingUsed": false,
              "allRequiredParamsPresent": true,
              "endOfConversation": false
            },
            "fulfillment": {
              "audioOutput": null,
              "messages": [
                {
                  "speech": null,
                  "text": "Ciao!",
                  "platform": "PLATFORM_UNSPECIFIED",
                  "order": 0,
                  "iterable": null,
                  "payload": null,
                }
              ]
            }
          }
        }
      },
      "extraResult": {
        "singleResult": {},
        "details": {
          "assistant": null,
          "skipIntent": false,
          "detectWithInputContext": false,
          "trusted": null,
          "manageByOperator": true,
          "currentJourneyCode": null,
          "switchedAgent": false,
          "warningList": [],
          "topics": [
            "default"
          ]
        }
      }
    }

Dialogflow CX

JSON representation

{
  "status": 200,
  "results": {
    "aiResponse": {
      "idMessage": "b79a2c53-8096-4f60-a23a-a9929cfe5cde",
      "lang": "it",
      "id": "b4749f07-6b62-4dbd-98bd-8f0add714f45-5fd6c646",
      "timestamp": "2022-02-18T16:17:03Z,
      "sessionId": "144004629999",
      "result": {
        "resolvedQuery": "Ciao",
        "score": 1.0,
        "parameters": {},
        "metadata": {
          "isFallbackIntent": false,
          "intentName": "Default Welcome Intent",
          "intentId": "projects/project-name/locations/europe-west1/agents/
5b123456-453b-4ab0-ab5a-1746331f7b96/intents/00000000-0000-0000-0000-000000000000",
          "flow": {
            "dfId":"00000000-0000-0000-0000-000000000000",
            "name":"Default Start Flow"
          },
          "landedPage": {
            "dfId":"projects/project-name/locations/europe-west1/agents/
5b123456-453b-4ab0-ab5a-1746331f7b96/flows/00000000-0000-0000-0000-000000000000/pages/START_PAGE",
            "name":"Start Page"
          },
          "transitionPage":  {
            "dfId":"START_PAGE",
            "name":"Start Page"
          },
          "transitionRoute":  {
            "dfId":"c4de56e8-2990-499a-b35f-19464ca2c28e",
            "name":"Default Welcome Intent"
          },
          "event": null,
          "webhookTag": null,
          "webhookUsed": null,
          "webhookForSlotFillingUsed": null,
          "allRequiredParamsPresent": false,
          "endOfConversation": false
        },
        "fulfillment": {
          "audioOutput": null,
          "messages": [
            {
              "speech": null,
              "text": "Ciao!",
              "platform": "PLATFORM_UNSPECIFIED",
              "order": 0,
              "iterable": false,
              "payload": null,
            }
          ]
        }
      }
    }
  },
  "extraResult": {
    "singleResult": null,
    "details": {
      "assistant": null,
      "skipIntent": false,
      "detectWithInputContext": false,
      "trusted": false,
      "manageByOperator": true,
      "currentJourneyCode": null,
      "switchedAgent": false,
      "warningList": [],
      "topics": [
        "default"
      ]
    }
  }
}