Formattare i messaggi

Questa pagina spiega come le app Google Chat possono formattare il testo per inviare messaggi che contengono uno dei seguenti elementi:

• RTF che contiene link ipertestuali o @menzioni di uno o tutti gli utenti in uno spazio di Chat.
• Testo visualizzato in un'interfaccia della scheda, incluso il testo del paragrafo o il testo dell'interfaccia utente visualizzato accanto a un'icona, ad esempio un pulsante.

Formattare un messaggio

Chat ti consente di aggiungere la formattazione di base a un messaggio, tra cui grassetto, corsivo e barrato. La formattazione del testo nei messaggi è diversa da quella dei messaggi con schede perché i messaggi vengono formattati con la stessa sintassi utilizzata dagli utenti di Chat.

Per i messaggi inviati o recuperati utilizzando l'API Chat, puoi utilizzare la sintassi Markdown standard (MARKUP_SYNTAX_MARKDOWN) o la sintassi di markup di Chat (MARKUP_SYNTAX_CHAT). Puoi configurare una sintassi di markup predefinita a livello di app nella console Google Cloud (consulta Configura l'API Google Chat):

• Markdown: sintassi Markdown standard (MARKUP_SYNTAX_MARKDOWN), basata sulla specifica CommonMark con estensioni aggiuntive. Le app di Chat appena create utilizzano per impostazione predefinita il formato Markdown.
• Chat: sintassi di markup di Chat (MARKUP_SYNTAX_CHAT). Le app di Chat esistenti utilizzano per impostazione predefinita Chat per preservare la compatibilità con le versioni precedenti.

Puoi anche specificare markup_syntax su singole richieste API Chat per eseguire l'override del valore predefinito a livello di app. Quando markup_syntax non è specificato in una richiesta API, il markup viene impostato in base a come chiami l'API Chat:

• App di Chat configurate:utilizza la sintassi di markup salvata nella pagina di configurazione dell'API Chat.
• Progetti cloud non configurati (senza configurazione): se il tuo progetto cloud chiama l'API Chat senza una configurazione dell'app Chat salvata, le richieste vengono impostate per impostazione predefinita su MARKUP_SYNTAX_MARKDOWN.
• Webhook in arrivo:il valore predefinito è MARKUP_SYNTAX_CHAT. Consulta Invia messaggi utilizzando i webhook in arrivo.

Per formattare i messaggi, utilizza la seguente sintassi:

Ad esempio, considera il seguente JSON:

    {
      "text": "Your pizza delivery *has arrived*!\nThank you for using _Cymbal Pizza!_"
    }

Questo messaggio di testo formattato mostra quanto segue in uno spazio di Chat:

Visualizza la formattazione del testo inviata in un messaggio

Quando un utente invia un messaggio, il corpo del messaggio in testo normale si trova nel campo text. Alcune formattazioni applicate al messaggio utilizzando la sintassi Markdown si trovano nel campo text. La formattazione aggiuntiva si trova nel campo di solo output formattedText, tra cui:

• Sintassi Markdown aggiuntiva per il testo
• Menzioni degli utenti
• Link ipertestuali personalizzati
• Emoji personalizzate

Ad esempio, considera il seguente testo inviato da un utente:

Se il messaggio è stato formattato utilizzando il menu Formato nell'interfaccia utente di Chat, il campo text contiene solo il testo, mentre il campo formattedText contiene i markup, il testo e il link ipertestuale. L'esempio seguente mostra la bozza di un messaggio con una parola con link ipertestuale, elementi in un elenco e una parola in grassetto:

Il messaggio viene ricevuto nel seguente formato:

    {
      "text": "I can meet there at:\nNoon\n3 pm\n5 pm\nWhat time works for you?",
      "formattedText": "I can meet <http://example.com|there> at:\n* Noon\n* 3 pm\n* 5 pm\nWhat time works for *you*?",
    }

Link di formato

Se includi un URL di link semplice nel testo del messaggio, ad esempio http://www.example.com/, Google Chat lo utilizza come testo del link e lo collega automaticamente all'URL specificato.

Per fornire un testo del link alternativo per il tuo link, utilizza la seguente sintassi:

• Per i messaggi API configurati con Markdown, utilizza la sintassi standard dei link Markdown:

  Esempio di sintassi	Testo visualizzato in Google Chat
  [Example website](https://example.com)	Example website

• Per i messaggi di testo normale standard, utilizza la sintassi con la barra verticale:

  Esempio di sintassi	Testo visualizzato in Google Chat
  <https://example.com|Example website>	Example website

  La barra verticale e il testo del link sono facoltativi, quindi <https://example.com> e https://example.com sono equivalenti.

Utilizza le emoji personalizzate in un messaggio

Le app di Chat possono inviare messaggi con emoji personalizzate per personalizzare i messaggi. Le emoji personalizzate sono disponibili solo per le organizzazioni Google Workspace e l'amministratore deve attivarle per l'organizzazione. Per saperne di più, consulta Informazioni sulle emoji personalizzate in Google Chat e Gestisci le autorizzazioni per le emoji personalizzate.

Per creare messaggi con emoji personalizzate, la tua app deve utilizzare l'autenticazione utente. Le emoji personalizzate non sono supportate nei messaggi creati come webhook o nei messaggi creati con l'autenticazione dell'app.

Per aggiungere emoji personalizzate al testo di un messaggio, specifica name o emoji_name della risorsa customEmoji:

{
    "text": "Hello <customEmojis/CUSTOM_EMOJI_ID>."
}

Per utilizzare questo esempio, sostituisci CUSTOM_EMOJI_ID con l'ID dell'emoji personalizzata. Puoi trovare questo ID nel campo name o emoji_name della risorsa customEmoji.

Se la tua app invia messaggi utilizzando la sintassi Markdown, puoi specificare le emoji personalizzate nel formato dei tag HTML utilizzando l'ID delle emoji personalizzate:

{
  "text": "Hello <chat-emoji data-custom-emoji=\"customEmojis/CUSTOM_EMOJI_ID\">."
}

In alternativa, puoi specificare il nome dell'emoji personalizzata:

{
  "text": "Hello <chat-emoji data-emoji-name=\"CUSTOM_EMOJI_NAME\">."
}

Per utilizzare questi esempi, sostituisci CUSTOM_EMOJI_ID con l'ID dell'emoji personalizzata e CUSTOM_EMOJI_NAME con il nome dello shortcode dell'emoji personalizzata.

Menziona gli utenti in un messaggio

Le app di Chat possono inviare messaggi che @menzionano uno o tutti gli utenti in uno spazio di Chat. Le app di Chat possono anche menzionare gli utenti che non hanno partecipato allo spazio o che sono membri di uno spazio in modalità di importazione.

I messaggi silenziosi non supportano la menzione degli utenti. L'inserimento di una menzione in un messaggio silenzioso restituisce un errore.

@menzionare utenti specifici

Per menzionare un utente specifico con @, aggiungi <users/{user}> al messaggio, dove {user} è l'ID dell'utente. Ad esempio, considera il seguente messaggio in cui 123456789012345678901 rappresenta l'ID dell'utente Mahan S.:

{
    "text": "A customer has reported an issue. Assigning ticket #942 to <users/123456789012345678901>."
}

Se la tua app invia messaggi utilizzando la sintassi Markdown, utilizza il formato del tag HTML chat-user per specificare l'ID utente:

{
  "text": "Assigning ticket #942 to <chat-user data-user=\"users/123456789012345678901\">."
}

In alternativa, specifica l'indirizzo email:

{
  "text": "Assigning ticket #942 to <chat-user data-email=\"mahan@example.com\">."
}

Il messaggio viene visualizzato come segue:

Puoi specificare il valore users/{user} nei seguenti modi:

• Se l'app Google Chat risponde a un messaggio inviato dall'utente, puoi utilizzare il campo message.sender.name dell'evento di interazione MESSAGE.

• Se la tua app Google Chat sta creando un messaggio di testo asincrono, puoi specificare il valore di users/{user} nei seguenti modi:

  • Utilizza il campo name della risorsa User di Google Chat, ad esempio users/123456789012345678901.
  • Utilizza l'indirizzo email dell'utente come alias per il valore {user}. Ad esempio, se l'indirizzo email è mahan@example.com, puoi specificare l'utente come users/mahan@example.com. Per utilizzare un alias email, l'app Google Chat deve eseguire l'autenticazione come utente.

• Se utilizzi l'API People, puoi anche utilizzare il metodo people.get per identificare l'ID utente.

@menzionare tutti gli utenti

Per creare un messaggio che @menzioni tutti i partecipanti di uno spazio, sostituisci {user} con all. L'esempio JSON seguente menziona tutti gli utenti in un messaggio:

{
    "text": "Important message for <users/all>: Code freeze starts at midnight tonight!"
}

Se la tua app invia messaggi utilizzando la sintassi Markdown, specifica la menzione utilizzando il formato del tag HTML chat-user:

{
  "text": "Important message for <chat-user data-user=\"users/all\">: Code freeze starts at midnight tonight!"
}

Aggiungi citazioni a un messaggio

Le app di Chat possono includere citazioni nei messaggi per fornire agli utenti informazioni dettagliate sulla fonte. Puoi fornire le fonti in due modi:

• Citazioni in linea: aggiungi schede interattive che vengono visualizzate quando gli utenti passano il puntatore su parti specifiche del testo del messaggio.
• Fonti a piè di pagina: visualizza un elenco di fonti nella parte inferiore del messaggio come link a piè di pagina.

Le citazioni sono supportate solo quando il campo markupSyntax del messaggio è impostato su MARKUP_SYNTAX_MARKDOWN. Questa funzionalità è supportata solo tramite la creazione asincrona di messaggi utilizzando l'API Chat.

Per aggiungere citazioni in linea a un messaggio:

1. Fornisci le fonti nell'elenco citations del messaggio elements, assegnando un id univoco a ogni oggetto Citation.
2. Nel testo del messaggio, racchiudi il testo che vuoi citare utilizzando il formato del tag HTML chat-citation: <chat-citation data-id="{id}">{text}</chat-citation>. Assicurati che {id} corrisponda all'ID definito in elements. Le citazioni senza riferimento (quelle senza un tag corrispondente) vengono ignorate.

{
  "text": "This is a <chat-citation data-id=\"cite_1\">cited</chat-citation> text.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citations": [
      {
        "id": "cite_1",
        "citedSources": [
          {
            "title": "Example Source",
            "uri": "https://example.com"
          }
        ]
      }
    ]
  }
}

Per aggiungere fonti a piè di pagina a un messaggio, fornisci le fonti nell'elenco citedSources del messaggio elements. Tutte le fonti fornite qui vengono visualizzate automaticamente sotto il messaggio come link nel piè di pagina e non richiedono tag incorporati nel testo del messaggio.

{
  "text": "This is a message with a footer source.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citedSources": [
      {
        "title": "Example Source",
        "uri": "https://example.com"
      }
    ]
  }
}

Formattare il testo visualizzato nelle schede

All'interno delle schede, la maggior parte dei campi di testo supporta la formattazione di base del testo utilizzando un piccolo sottoinsieme di tag HTML. La formattazione del testo nei messaggi con schede è diversa da quella dei messaggi di testo, perché i messaggi di testo vengono formattati con la stessa sintassi utilizzata dagli utenti di Chat.

Utilizza lo Strumento per la creazione di schede per progettare e visualizzare in anteprima i messaggi e le interfacce utente per le app di Chat:

Formatta il testo del paragrafo

I tag supportati e il loro scopo sono riportati nella tabella seguente:

Per definire elenchi e blocchi di codice, utilizza i seguenti tag:

This is a code block.

Markdown

Quando la sintassi Markdown è attiva, puoi utilizzare la seguente sintassi:

Aggiungi icone al testo

Per visualizzare le icone accanto al testo in una scheda, puoi utilizzare i widget DecoratedText e ButtonList.

Le sezioni seguenti spiegano come utilizzare le icone integrate, le icone di Google Material o le icone personalizzate nel testo o nei pulsanti decorati.

Utilizza le icone di Chat

Per utilizzare un'icona integrata disponibile in Chat, specifica una delle seguenti opzioni:

La tabella seguente elenca le icone integrate disponibili per i messaggi con schede:

Di seguito è riportato un esempio di scheda con un'icona email:

Utilizza le icone Material di Google

Puoi utilizzare le icone Material di Google per scegliere tra oltre 2500 opzioni di icone e personalizzare lo spessore, il riempimento e l'intensità delle icone.

Di seguito è riportato un esempio di scheda con un'icona Material di Google:

Utilizza icone personalizzate

Per aggiungere un'icona personalizzata, includi il campo iconUrl e specifica l'URL corrispondente dell'icona.

Di seguito è riportato un esempio di icona personalizzata: