MONK Message Format

Abbiamo definito un formato di messaggio personalizzato per lo scambio di messaggi XMPP strutturati e semantici.

Implementazione

Il nostro messaggio personalizzato viene scambiato tramite lo standard XMPP all’interno di <message>, inserendolo all’interno di <body>.

Ogni messaggio deve indicare chi è il destinatario (come da protocollo XMPP) e ciò avviene tramite il to che si trova dentro message.

Ogni messaggio ha un tag <thread> che indica il contesto e la conversazione. Sono separati dall’operatore |$| e i contesti possono essere multipli, ad esempio: <thread>context1|$|context2|$|context3|$|conversation</thread>

Note

Quando il thread non è necessario, per convenzione, viene impostato come il from, ad esempio: <message from="sender@domain" id="uniqueid" type="chat"><thread>sender</thread>...

Sotto un esempio completo:

<message to="recipient@domain" id="uniqueid" type="chat">
    <body/>
    <thread>mytickets|$|myticket_milan</thread>
    <body>
        <!-- here goes our message format -->
    </body>
</message>

Defizione del Formato generico

Il messaggio all’interno del <body> ha un formato di tipo json e presenta questi campi:

  • "version": version number, opzionale, esempio: "version": "1.0"

  • "language": ISO 639-1 language code, esempio: "language": "eng"

  • "creation_date": creation date, formato yyyy-MM-dd’T’HH:mm:ss.SSSSSSS’Z’, esempio: "creation_date": "2024-10-14T17:54:40.8070000Z"

  • "chat_type": chat type, esempio: "chat_type": "chat"

  • "domain": domain, esempio: "domain": "chat"

  • "identifier": message identifier, esempio: "identifier": "0b6685ba-7118-4a1d-84ba-138f328ec54"

  • "type": il tipo di messaggio, esempio: "type": "chat_location"

  • "arguments": il contenuto del messaggio, esempio: "arguments": "{...message content...}"

Il "type" va a definire il tipo di messagio e di conseguenza cambierà gli "arguments" associati a quel messaggio.

Esempio completo di un messaggio XMPP:
 <message to="bob@wfp" id="51c9b72c-f2f1-4e8d-927b-33401065cf0f-211610484933107" type="chat">
    <thread>9e036646-48a9-477d-a165-6feaea487c76</thread>
    <body>{
   "arguments": {
     "text": "Viale Appio Claudio, 249",
     "address": "Viale Appio Claudio, 249",
     "city": "Roma",
     "cityCode": "Città metropolitana di Roma Capitale",
     "country": "Italy",
     "latitude": 41.8531564,
     "longitude": 12.561757,
     "zipCode": "00174",
     "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_location",
   "version": "1.0"
 }</body>
 </message>

Definizione di un Payload generico

L’interfaccia di base degli arguments include alcune caratteristiche comuni: l’oggetto arguments è un JSON esteso dalle definizioni di ciascun tipo di messaggio specifico.

Adam Actions

Le interazioni tra diversi client attraverso il protocollo Adam sono possibili grazie al parametro adamActions.

Puoi arricchire ogni messaggio con i dati di adamActions per eseguire operazioni su altri client, come: abilitare il pulsante per gli allegati, chiudere la conversazione e così via…

Interfaccia

interface IBasePayload {
    adamActions?: IAdamAction[]
}

interface IAdamAction {
    code: string // 'create-conversation-readonly' | 'close-conversation' | 'enable-attachments' | ...
    message?: string
    args: [string, string][]
}

dove:

  • code operation identifier. Esempio: conversation-open, conversation-close, attachment-enable, attachment-disable, ..

  • message descrizione dell’azione da compiere. Messaggio operativo per il debug

  • args hashmap of arguments per arricchire l’action con altri parametri

Tipi di Messaggio

Ogni tipo contiene la propria struttura, opzioni e payload specifici ed è spesso visualizzato con un widget UI specifico nei client che supportano il formato MONK. Qui puoi trovare i dettagli di tutti i tipi di messaggio con il loro payload.

ISO 639-1: https://en.wikipedia.org/wiki/ISO_639-1