{"id":412,"date":"2020-11-22T22:01:05","date_gmt":"2020-11-22T22:01:05","guid":{"rendered":"https:\/\/docs.tellya.ai\/?page_id=412"},"modified":"2022-10-23T12:57:16","modified_gmt":"2022-10-23T12:57:16","slug":"orchestrate-api","status":"publish","type":"page","link":"https:\/\/docs.tellya.ai\/index.php\/orchestrate-api\/","title":{"rendered":"Orchestrate API"},"content":{"rendered":"\n

L\u2019API \u201cOrchestrate\u201d innesca il processo di elaborazione dell\u2019input fornito dall\u2019utente, che si traduce nell\u2019esecuzione dei connettori presenti all\u2019interno della journey invocata.<\/p>\n\n\n\n

L\u2019input dell\u2019utente \u00e8 solitamente costituito da una query, in formato testuale o audio, oppure da un evento. Tellya innescher\u00e0 il riconoscimento e l’interpretazione dell\u2019input attraverso il motore di NLU configurato all\u2019interno della journey invocata.<\/p>\n\n\n\n

A seconda che siano presenti altri connettori o configurazioni all\u2019interno della journey (oltre a quello che rappresenta il motore di NLU), Tellya potrebbe elaborare l\u2019input dell\u2019utente prima che venga sottoposto al motore di NLU e\/o modificare il risultato fornito dal motore di NLU prima di restituirlo in risposta.<\/p>\n\n\n\n

Method<\/h2>\n\n\n\n

POST\u200b<\/strong>: {basePath}\/chat\/api\u200b\/v2\u200b\/orchestrate\u200b\/{apiKey}<\/p>\n\n\n\n

Il request URL completo del metodo POST da invocare (completo di {basePath e {apiKey}) pu\u00f2 essere visualizzato all\u2019interno delle impostazioni della journey con cui si vuole interagire (nella sezione \u201cServer integration\u201d).<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Path Parameters<\/h3>\n\n\n\n
\n \n \n \n \n \n \n \n \n
Parameters<\/th>\n <\/tr>\n <\/thead>\n
apiKey<\/th>\n \n

String<\/p>\n

Obbligatorio<\/p>\n

Identificativo univoco della journey<\/p>\n <\/td>\n <\/tr>\n

cleanResponse<\/th>\n \n

Boolean<\/p>\n

Default value: false<\/span><\/p>\n <\/td>\n <\/tr>\n

customResponses<\/th>\n \n

Boolean<\/p>\n

Default value: false<\/span><\/p>\n

Permette di stabilire se in risposta si desidera ricevere le risposte <\/a> configurate per il canale \u201cTellya\u201d (false) oppure quelle\n definite per un canale \u201cCustom\u201d (true).\n\n Nel caso il parametro sia impostato a \u201ctrue\u201d ma non siano presenti risposte configurate per il\n canale \u201cCustom\u201d verranno selezionare le risposte configurate per il canale \u201cDefault\u201d.\n <\/p>\n <\/td>\n <\/tr>\n

save<\/th>\n \n

Boolean<\/p>\n

Default value: true<\/span><\/p>\n

Permette di stabilire se salvare l\u2019interazione nella history conversazionale e nelle analitiche\n (true), oppure no (false).\n\n La disabilitazione di tale parametro viene tipicamente utilizzata quando non si vogliono\n compromettere i dati e le metriche delle interazioni reali con quelle di ambienti di test (nel\n caso di singola journey che assolve entrambi i compiti).\n <\/p>\n <\/td>\n <\/tr>\n <\/tbody>\n <\/table>\n<\/div>\n\n\n\n

Request body<\/h3>\n\n\n\n

Ogni richiesta di Orchestrate deve contenere un input (tipicamente fornito o innescato dall\u2019utente) 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.<\/p>\n\n\n\n

\n \n \n \n \n \n \n \n
Input fields<\/th>\n <\/tr>\n <\/thead>\n
audio<\/th>\n \n

String<\/p>\n

Obbligatorio. Formato wav mono codificato in Base64.<\/p>\n <\/td>\n <\/tr>\n

event<\/a><\/th>\n \n

Object<\/p>\n

Obbligatorio. Un evento da processare che specifica quale intento o stato attivare.<\/p>\n <\/td>\n <\/tr>\n

query<\/th>\n \n

String<\/p>\n

Obbligatorio. Rappresenta il testo in linguaggio naturale da elaborare, la richiesta dell’utente\n da ricondurre ad un intento. La lunghezza del testo non deve superare i 256 caratteri.<\/p>\n <\/td>\n <\/tr>\n <\/tbody>\n <\/table>\n<\/div>\n\n\n\n

\n \n \n \n \n \n \n \n \n \n \n \n \n
Other fields<\/th>\n <\/tr>\n <\/thead>\n
audioOutputRequired <\/th>\n \n

Boolean<\/p>\n

Per definire se ricevere o meno in output anche la risposta audio codificata in Base64.<\/p>\n <\/td>\n <\/tr>\n

audioOutputSampleRate<\/th>\n \n

Integer<\/p>\n

Sample rate in Hertz con cui si desidera ricevere l’output audio. Valore minimo limite: 8000.<\/p>\n <\/td>\n <\/tr>\n

context<\/a><\/th>\n \n

Object<\/p>\n

L\u2019insieme dei contesti da attivare prima dell\u2019esecuzione della query (disponibile solo con\n Dialogflow ES).<\/p>\n <\/td>\n <\/tr>\n

lang<\/th>\n \n

String<\/p>\n

Obbligatorio. La lingua di questa interazione conversazionale.<\/p>\n <\/td>\n <\/tr>\n

journeyCode<\/th>\n \n

String<\/p>\n

Obbligatorio. Parametro da configurare nel chat widget e che indica la journey di default che\n deve essere chiamata.<\/p>\n <\/td>\n <\/tr>\n

queryParametersMap<\/th>\n \n

Object<\/p>\n

Parametri che si vogliono inserire direttamente quando avviene la chiamata al motore di NLU.\n Oggetto JSON composto da una raccolta di coppie (MapKey, MapValue). Pu\u00f2 essere utilizzata solo\n con le query e audio.<\/p>\n <\/td>\n <\/tr>\n

sessionId<\/th>\n \n

String<\/p>\n

Obbligatorio. Identificativo univoco della sessione a cui viene inviata la query.<\/p>\n <\/td>\n <\/tr>\n

userData<\/th>\n \n

Object<\/p>\n

Informazioni aggiuntive relative alla sessione. Oggetto JSON composto da una raccolta di coppie\n (MapKey, MapValue).<\/p>\n <\/td>\n <\/tr>\n <\/tbody>\n <\/table>\n<\/div>\n\n\n\n

Context<\/h4>\n\n\n\n

I contesti consentono di instradare il dialogo e guidare la conversazione nella direzione desiderata.<\/p>\n\n\n\n