Messaggio Dinamico
------------------

``chat_dynamic`` è di gran lunga il tipo di messaggio più complesso e flessibile nel formato monk.
Può essere utilizzato per inviare un messaggio che chiede al destinatario di allegare un video, 
un contatto, una posizione, di scegliere un intervallo di date, 
o di selezionare una o più opzioni in un elenco, e molte altre opzioni.

L'uso principale è per i bot, che possono utilizzare questo tipo di messaggio 
per richiedere e ottenere informazioni specifiche e "vincolate" dall'utente.

I client che lo supportano completamente adatteranno automaticamente la loro 
interfaccia utente e mostreranno i widget / campi di input corretti per 
permettere all'utente di rispondere alla richiesta ``chat_dynamic``.

Può incorporare altri tipi di messaggi, in particolare ``chat_text``, ``chat_html`` 
e ``chat_image`` in vari punti, ad esempio come "etichette" dei pulsanti o come messaggi 
che il client dovrebbe inviare automaticamente quando viene scelta l'opzione relativa.

Questo è il formato generale di un payload di "richiesta" ``chat_dynamic``:

.. code-block:: typescript
   :caption: request chat_dynamic payload format
   :name: request-chat-dynamic-payload

   {
     content: Content[]
     layout: {
       location: 'in' | 'out'
       selectionMode: 'none' | 'button' | 'multiple' | 'input'
       orientation: 'auto' | 'vertical' | 'horizontal'
     }
     inputData: {
       // A questo livello può essere presente solo uno dei due parametri, interaction o choice
       interaction: Interaction
       choice: {
         modeBeforeSubmit: 'none' | 'inputBlock' | 'inputHide' | 'autocomplete'
         visibilityAfterSubmit: 'none' | 'block' | 'hide'
         maxSelectable: int
         minSelectable: int
         submit: Content[]
         list: Choice[]
       }
     }
   }

Il messaggio di risposta a un dinamico generalmente presenta l'array di string `selectedChoices` a cui
interno presenta tutti i commands associati alle scelte selezionate dall'utente.
Questo è il formato generale di un payload di "risposta" ``chat_dynamic`` payload:

.. code-block:: typescript
   :caption: response chat_dynamic payload format
   :name: response-chat-dynamic-payload

   {
     selectedChoices: string[]
     content: Content[]
   }

L'oggetto ``layout`` definisce il messaggio dell'interfaccia utente e fornisce i seguenti parametri:
    - **location**: serve per mostrare il contenuto all'interno ``in`` o all'esterno ``out`` della bubble di chat.
    - **selectionMode**: serve per capire il tipo di selezione: ``none`` nessuna, ``button`` singola scelta, ``multiple`` risposta multipla, ``input`` azione specifica.
    - **orientation**: serve per gestire la disposizione dei pulsanti (qualora fossero presenti): di default è ``auto``, oppure possono essere ``vertical`` o ``horizontal``.

Gli oggetti Choice_, Content_ e Interaction_ sono spiegati nelle sezioni sotto.
Sono vincolati alla richiesta del messaggio e dipendono dal parametro ``selectionMode``:

Se il valore di ``selectionMode`` è:
  - **input**: ``inputData`` ha ``interaction``, mai la ``choice``, e il tipo di interaction non può mai essere ``send_message`` perché quello è presente solo con selection mode button.
  - **button**: ``inputData`` ha la ``choice``, mai ``interaction``.
  - **multiple**: ``inputData`` ha la ``choice``, mai ``interaction``; in questa modalità la ``choice`` presenta anche il pulsante ``submit`` per l'invio e i due parametri di configurazione ``maxSelectable`` e ``minSelectable`` per gestire il numero di risposte selezionabili.
  - **none**: non è presente ``inputData``.

Content
^^^^^^^

Come detto in precedenza, ``chat_dynamic`` può incorporare gli altri tipi di 
messaggi il tutto tramite l'oggetto ``Content``.
Il formato dell'oggetto è lo stesso del formato payload del tipo di messaggio, 
con l'aggiunta del valore type (che normalmente si troverebbe al di fuori di ``arguments``).

.. code-block:: typescript
   :caption: ``Content`` format

   {
     // uno degli altri tipi di messaggi personalizzati
     type: string
     // tutti gli arguments presenti nel tipo di messaggio utilizzato
     arguments.param1: ...
     arguments.param2: ...
   }

Per esempio, il ``Content`` per un :doc:`Messaggio Immagine <../chat_image>` è:

.. code-block:: json
   :caption: chat_image ``Content``

   {
     "type": "chat_image",
     "filename": "image.png",
     "url": "https://xmpp-svil.monksoftware.it/api/v1/attachments/pictures/image.png",
     "thumbUrl": "https://xmpp-svil.monksoftware.it/api/v1/attachments/pictures/thumb_image.png",
     "caption": "Caption dell'immagine"
   }


Choice
^^^^^^

Ogni ``Choice`` è una possibile opzione "selezionabile" di un ``chat_dynamic`` message.
A seconda del ``selectionMode``, è possibile selezionare più di una opzione.
I parametri presenti nella choice sono i seguenti:

  - **modeBeforeSubmit**: serve a definire lo stato del campo inputText quando viene visualizzato questo messaggio:

    - ``none`` il campo inputText resta invariato.
    - ``inputBlock``: disabilita il campo di inserimento testo e l’invio dei messaggi.
    - ``inputHide``: nasconde il campo di inserimento testo.
    - ``autocomplete``: mantiene il campo inputText abilitato, ma limita l'inserimento alle sole opzioni disponibili nella lista ``list``, impedendo l’inserimento di valori arbitrari.

  - **visibilityAfterSubmit**: serve a definire l'azione da compiere una volta soddisfatta la choice: ``none`` non fa nulla, per cui si possono selezionare nuovamente i pulsanti; ``block`` disabilita i pulsanti; ``hide`` nasconde i pulsanti.
  - **maxSelectable**: indica il numero massimo di scelte possibili (è presente solo per selectionMode multiple).
  - **minSelectable**: indica il numero minimo di scelte possibili (è presente solo per selectionMode multiple).
  - **submit**: il pulsante per l'invio delle opzioni scelte (è presente solo per selectionMode multiple).
  - **list**: la lista dei pulsanti.

.. code-block:: typescript
   :caption: ``Choice`` format

    {
      // la chiave che identifica la scelta, sarà inviata
      // all'interno delle "selectedChoices" in risposta al messaggio dinamico
      command: string
      // La scelta mostrata all'utente: non necessariamente testo,
      // potrebbe essere un'immagine, un video, un audio, o in generale
      // qualsiasi altro messaggio personalizzato incorporabile, e persino
      // una combinazione di questi (es. immagine + html)
      content: Content
      // L'interazione da eseguire se questa scelta viene selezionata dall'utente
      interaction: Interaction
    }


.. _interaction:

Interaction
^^^^^^^^^^^

Le Interactions descrivono come il client dovrebbe ottenere una risposta dall'utente. 
Alcune interazioni sono automatiche e non richiedono alcun input da parte dell'utente, 
mentre altre richiedono che il client mostri un widget specifico all'utente 
per scegliere un valore. Il formato generale di una ``Interaction`` è il seguente:

.. code-block:: typescript
   :caption: ``Interaction`` format

   {
     // Tipologia di interaction
     type: InteractionType
     // Messaggi da inviare una volta completata l'interazione
     content: Content[]
     // opzioni aggiuntive su come acquisire e formattare l'input dell'utente
     // ogni tipo di interazione ha il proprio set di opzioni possibili (opzionale)
     options: InteractionOption
   }

Ogni tipo di interazione ha il proprio set di opzioni: ad esempio, 
un'interazione ``input_date`` può avere delle opzioni per limitare l'intervallo delle date consentite.

Tutti i tipi di interazione e i relativi set di opzioni sono dettagliati nei seguenti documenti:

.. toctree::
   :titlesonly:
   :glob:

   interactions/*


Esempio
^^^^^^^

Ora che abbiamo tutti i pezzi, possiamo esaminare un esempio completo di ``chat_dynamic``. 
In questo esempio, viene chiesto all'utente di inviare la propria patente di guida, 
scattando una foto o caricando un PDF.

.. literalinclude:: examples/driver_license.xml
   :language: xml


Esempi Aggiuntivi
^^^^^^^^^^^^^^^^^

Il messaggio ``chat_dynamic`` è complesso, sotto ci sono esempi aggiuntivi così da vedere tutte le
possibilità offerte da questo tipo di messaggio:

.. toctree::
   :maxdepth: 1
   :glob:

   examples/*