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:

request chat_dynamic payload format

{
  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:

response chat_dynamic payload format

{
  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).

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 Messaggio Immagine è:

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.

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

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:

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:

• input_date interaction
• insert_location interaction
• insert_text interaction
• open_url interaction
• send_message interaction
• start_call interaction
• start_chat interaction
• take_audio interaction
• take_document interaction
• take_image interaction
• take_video interaction

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.

 <message to="bob@wfp" id="51c9b72c-f2f1-4e8d-927b-33401065cf0f-211610484933107" type="chat">
    <thread>9e036646-48a9-477d-a165-6feaea487c76</thread>
    <body>{
       "arguments": {
            "content": [
              {
                "type": "chat_text",
                "text": "Please attach your driver's license, either take a picture or upload a PDF file."
              },
              {
                "type": "chat_text",
                "text": "You can also listen to these audio instructions."
              },
              {
                "type": "chat_audio",
                "url": "https://mysite.com/audio_instructions_license_upload.mp3",
                "filename": "audio_instructins_license_upload.mp3"
              }
            ],
            "layout": {
              "location": "in",
              "selectionMode": "button",
              "orientation": "vertical"
            },
            "inputData": {
              "choice": {
                "visibilityAfterSubmit": "none",
                "list": [
                  {
                    "command": "license_picture",
                    "content": [
                      {
                        "type": "chat_text",
                        "text": "Take a picture"
                      }
                    ],
                    "interaction": {
                      "type": "take_image",
                      "options": {
                          "acceptedFormat": ["png", "jpg"]
                      }
                    }
                  },
                  {
                    "command": "license_pdf",
                    "content": [
                      {
                        "type": "chat_text",
                        "text": "Upload PDF"
                      }
                    ],
                    "interaction": {
                      "type": "take_document",
                      "options": {
                          "acceptedFormat": ["pdf"]
                      }
                    }
                  }
                ]
              }
            }
           "data": {
             "apiVersion": 3,
             "appVersion": "0.0.1",
             "os": "android",
             "token": "token",
             "useChatDynamic": true
           }
         },
         "chat_type": "chat",
         "creation_date": "2024-10-14T17:54:40.8070000Z",
         "domain": "chat",
         "identifier": "0b6685ba-7118-4a1d-84ba-138f328ec54e-211610540337024",
         "language": "eng",
         "type": "chat_dynamic",
         "version": "1.0"
       } 
    </body>
 </message>

Esempi Aggiuntivi

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

• Appuntamento dal dentista
• Richiesta Documento
• Eventi Aziendali