שליחת הודעות באמצעות Google Chat API

במדריך הזה מוסבר איך משתמשים ב-method create() במשאב Message של Google Chat API כדי לבצע כל אחת מהפעולות הבאות:

  • שליחת הודעות שמכילות טקסט, כרטיסים וווידג'טים אינטראקטיביים.
  • לשלוח הודעות באופן פרטי למשתמש ספציפי ב-Chat.
  • להתחיל שרשור הודעות או לענות לו.
  • נותנים שם להודעה, כדי שתוכלו לציין אותה בבקשות אחרות ל-Chat API.

גודל ההודעה המקסימלי (כולל טקסט או כרטיסים) הוא 32,000 בייטים. כדי לשלוח הודעה שחורגת מהגודל הזה, אפליקציית Chat צריכה לשלוח כמה הודעות במקום זאת.

בנוסף לקריאה ל-Chat API כדי ליצור הודעות, אפליקציות ל-Chat יכולות ליצור ולשלוח הודעות בתגובה לאינטראקציות של משתמשים, למשל פרסום הודעת פתיחה אחרי שמשתמש מוסיף את אפליקציית Chat למרחב משותף. כשעונים לאינטראקציות, אפליקציות Chat יכולות להשתמש בסוגים אחרים של תכונות להעברת הודעות, כולל תיבות דו-שיח אינטראקטיביות וממשקים לתצוגה מקדימה של קישורים. כדי לענות למשתמש, אפליקציית Chat מחזירה את ההודעה באופן סינכרוני, בלי להפעיל את Chat API. במאמר קבלת אינטראקציות ותגובה להן באמצעות אפליקציית Google Chat מוסבר איך לשלוח הודעות בתגובה לאינטראקציות.

איך מערכת Chat מציגה ומשייכת הודעות שנוצרו באמצעות Chat API

אפשר לקרוא ל-method create() באמצעות אימות אפליקציות ואימות משתמש. שיוך ההודעה ל-Chat משתנה בהתאם לסוג האימות שבו אתם משתמשים.

כשאתם מבצעים אימות כאפליקציית Chat, אפליקציית Chat שולחת את ההודעה.

קריאה ל-method create() עם אימות אפליקציה.
איור 1: באימות באפליקציה, אפליקציית Chat שולחת את ההודעה. כדי לציין שהשולח הוא לא אדם, ב-Chat יופיע הסמל App לצד השם שלו.

כשאתם מבצעים אימות כמשתמשים, אפליקציית Chat שולחת את ההודעה בשם המשתמש. Chat גם משייך את אפליקציית Chat להודעה על ידי הצגת השם שלה.

קריאה ל-method()‏ create עם אימות משתמש.
איור 2: כשהמשתמשים מבצעים אימות, הם שולחים את ההודעה וב-Chat מוצג שם האפליקציה לצד שם המשתמש.

סוג האימות קובע גם אילו ממשקים ותכונות של הודעות אפשר לכלול בהודעה. באמצעות אימות האפליקציה, אפליקציות Chat יכולות לשלוח הודעות שמכילות טקסט עשיר, ממשקים מבוססי כרטיסים וווידג'טים אינטראקטיביים. משתמשי Chat יכולים לשלוח רק טקסט בהודעות שלהם, ולכן אפשר לכלול טקסט רק כשיוצרים הודעות באמצעות אימות משתמשים. למידע נוסף על התכונות של העברת הודעות ב-Chat API, תוכלו לקרוא את הסקירה הכללית על הודעות ב-Google Chat.

במדריך הזה מוסבר איך משתמשים בכל אחד מסוגי האימות כדי לשלוח הודעות באמצעות Chat API.

דרישות מוקדמות

Node.js

Python

Java

Apps Script

שליחת הודעה כאפליקציית Chat

בקטע הזה מוסבר איך לשלוח הודעות שמכילות טקסט, כרטיסים וווידג'טים של אביזרים אינטראקטיביים באמצעות אימות אפליקציות.

הודעה שנשלחה עם אימות באפליקציה
איור 4. אפליקציית Chat שולחת הודעה עם טקסט, כרטיס ולחצן של אביזרים.

כדי לקרוא לשיטה CreateMessage() באמצעות אימות אפליקציה, צריך לציין את השדות הבאים בבקשה:

  • chat.bot היקף ההרשאה.
  • המשאב Space שבו רוצים לפרסם את ההודעה. אפליקציית Chat צריכה להיות חברה במרחב המשותף.
  • המשאב Message שיוצרים. כדי להגדיר את תוכן ההודעה, אפשר לכלול טקסט עשיר (text), ממשק כרטיס אחד או יותר (cardsV2) או את שניהם.

אפשר לכלול גם את הפרטים הבאים:

הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכולה לשלוח הודעה שפורסמה כאפליקציית Chat, שמכילה טקסט, כרטיס ולחצן שניתן ללחוץ עליו בתחתית ההודעה:

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text: '👋🌎 Hello world! I created this message by calling ' +
            'the Chat API\'s `messages.create()` method.',
      cardsV2 : [{ card: {
        header: {
          title: 'About this message',
          imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
        },
        sections: [{
          header: 'Contents',
          widgets: [{ textParagraph: {
              text: '🔡 <b>Text</b> which can include ' +
                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
            }}, { textParagraph: {
              text: '🖼️ A <b>card</b> to display visual elements' +
                    'and request information such as text 🔤, ' +
                    'dates and times 📅, and selections ☑️.'
            }}, { textParagraph: {
              text: '👉🔘 An <b>accessory widget</b> which adds ' +
                    'a button to the bottom of a message.'
            }}
          ]}, {
            header: "What's next",
            collapsible: true,
            widgets: [{ textParagraph: {
                text: "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
              }}, { textParagraph: {
                text: "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                      "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                      "the message."
              }
            }]
          }
        ]
      }}],
      accessoryWidgets: [{ buttonList: { buttons: [{
        text: 'View documentation',
        icon: { materialIcon: { name: 'link' }},
        onClick: { openLink: {
          url: 'https://developers.google.com/workspace/chat/create-messages'
        }}
      }]}}]
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                                        "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                                        "the message."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java
import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                "the message."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with app credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    text: '👋🌎 Hello world! I created this message by calling ' +
          'the Chat API\'s `messages.create()` method.',
    cardsV2 : [{ card: {
      header: {
        title: 'About this message',
        imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
      },
      sections: [{
        header: 'Contents',
        widgets: [{ textParagraph: {
            text: '🔡 <b>Text</b> which can include ' +
                  'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
          }}, { textParagraph: {
            text: '🖼️ A <b>card</b> to display visual elements' +
                  'and request information such as text 🔤, ' +
                  'dates and times 📅, and selections ☑️.'
          }}, { textParagraph: {
            text: '👉🔘 An <b>accessory widget</b> which adds ' +
                  'a button to the bottom of a message.'
          }}
        ]}, {
          header: "What's next",
          collapsible: true,
          widgets: [{ textParagraph: {
              text: "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
            }}, { textParagraph: {
              text: "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                    "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                    "the message."
            }
          }]
        }
      ]
    }}],
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: 'View documentation',
      icon: { materialIcon: { name: 'link' }},
      onClick: { openLink: {
        url: 'https://developers.google.com/workspace/chat/create-messages'
      }}
    }]}}]
  };
  const parameters = {};

  // Make the request
  const response = Chat.Spaces.Messages.create(
    message, parent, parameters, getHeaderWithAppCredentials()
  );

  // Handle the response
  console.log(response);
}

כדי להריץ את הדוגמה הזו, מחליפים את SPACE_NAME במזהה שמופיע בשדה name של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.

הוספת ווידג'טים אינטראקטיביים בתחתית הודעה

בדוגמת הקוד הראשונה במדריך הזה, בהודעה באפליקציית Chat מוצג לחצן שניתן ללחוץ עליו בתחתית ההודעה, שנקרא ווידג'ט נלווה. ווידג'טים נלווים מופיעים אחרי טקסט או כרטיסים בהודעה. אתם יכולים להשתמש בווידג'טים האלה כדי לעודד את המשתמשים לבצע פעולות שונות שקשורות להודעה, כולל:

  • לדרג את הדיוק או את מידת שביעות הרצון מההודעה.
  • מדווחים על בעיה בהודעה או באפליקציית Chat.
  • פתיחת קישור לתוכן קשור, כמו מסמכי עזרה.
  • אפשר לסגור או להשהות הודעות דומות מאפליקציית Chat למשך פרק זמן מסוים.

כדי להוסיף ווידג'טים של אביזרים, צריך לכלול את השדה accessoryWidgets[] בגוף הבקשה ולציין ווידג'ט אחד או יותר שרוצים לכלול.

בתמונה הבאה מוצגת אפליקציית Chat שמצורפת הודעת טקסט עם ווידג'טים של אביזרים, כדי שהמשתמשים יוכלו לדרג את חוויית השימוש שלהם באפליקציית Chat.

ווידג&#39;ט של אביזר.
איור 5: הודעה באפליקציית Chat עם ווידג'טים של טקסט ואביזרים.

בהמשך מוצג גוף הבקשה ליצירת הודעת טקסט עם שני לחצני אביזרים. כשמשתמש לוחץ על לחצן, הפונקציה המתאימה (למשל doUpvote) מעבדת את האינטראקציה:

{
  text: "Rate your experience with this Chat app.",
  accessoryWidgets: [{ buttonList: { buttons: [{
    icon: { material_icon: {
      name: "thumb_up"
    }},
    color: { red: 0, blue: 255, green: 0 },
    onClick: { action: {
      function: "doUpvote"
    }}
  }, {
    icon: { material_icon: {
      name: "thumb_down"
    }},
    color: { red: 0, blue: 255, green: 0 },
    onClick: { action: {
      function: "doDownvote"
    }}
  }]}}]
}

שליחת הודעה באופן פרטי

באפליקציות צ'אט אפשר לשלוח הודעות באופן פרטי, כך שהן יהיו גלויה רק למשתמש ספציפי במרחב המשותף. כשמשתמשים באפליקציית Chat שולחים הודעה פרטית, מופיע בה תווית שמציינת שההודעה גלויה רק להם.

כדי לשלוח הודעה פרטית באמצעות Chat API, אתם צריכים לציין את השדה privateMessageViewer בגוף הבקשה. כדי לציין את המשתמש, מגדירים את הערך למשאב User שמייצג את המשתמש ב-Chat. אפשר גם להשתמש בשדה name של המשאב User, כפי שמתואר בדוגמה הבאה:

{
  text: "Hello private world!",
  privateMessageViewer: {
    name: "users/USER_ID"
  }
}

כדי להשתמש בדוגמה הזו, מחליפים את USER_ID במזהה ייחודי של המשתמש, כמו 12345678987654321 או hao@cymbalgroup.com. מידע נוסף על ציון משתמשים זמין במאמר זיהוי וציון משתמשים ב-Google Chat.

כדי לשלוח הודעה באופן פרטי, אסור לכלול בבקשה את הפרטים הבאים:

שליחת הודעת טקסט בשם משתמש

בקטע הזה מוסבר איך שולחים הודעות מטעם משתמש באמצעות אימות משתמש. כשההודעה מאומתת על ידי המשתמש, תוכן ההודעה יכול להכיל רק טקסט, וצריך להשמיט ממנה תכונות של העברת הודעות שזמינות רק לאפליקציות צ'אט, כולל ממשקי כרטיסים וווידג'טים אינטראקטיביים.

שליחת הודעה עם אימות משתמש
איור 3. אפליקציית Chat שולחת הודעת טקסט בשם המשתמש.

כדי להפעיל את ה-method CreateMessage() באמצעות אימות משתמש, צריך לציין את השדות הבאים בבקשה:

  • היקף הרשאה שתומך באימות משתמשים בשיטה הזו. בדוגמה הבאה נעשה שימוש בהיקף chat.messages.create.
  • המשאב Space שבו רוצים לפרסם את ההודעה. המשתמש המאומת חייב להיות חבר במרחב המשותף.
  • המשאב Message שיוצרים. כדי להגדיר את תוכן ההודעה, צריך לכלול את השדה text.

אפשר לכלול גם את הפרטים הבאים:

הקוד הבא מראה דוגמה לאופן שבו אפליקציית Chat יכולה לשלוח הודעת טקסט במרחב משותף מסוים בשם משתמש מאומת:

Node.js

chat/client-libraries/cloud/create-message-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text: '👋🌎 Hello world!' +
            'Text messages can contain things like:\n\n' +
            '* Hyperlinks 🔗\n' +
            '* Emojis 😄🎉\n' +
            '* Mentions of other Chat users `@` \n\n' +
            'For details, see the ' +
            '<https://developers.google.com/workspace/chat/format-messages' +
            '|Chat API developer documentation>.'
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world!' +
                    'Text messages can contain things like:\n\n' +
                    '* Hyperlinks 🔗\n' +
                    '* Emojis 😄🎉\n' +
                    '* Mentions of other Chat users `@` \n\n' +
                    'For details, see the ' +
                    '<https://developers.google.com/workspace/chat/format-messages' +
                    '|Chat API developer documentation>.'
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world!" +
                    "Text messages can contain things like:\n\n" +
                    "* Hyperlinks 🔗\n" +
                    "* Emojis 😄🎉\n" +
                    "* Mentions of other Chat users `@` \n\n" +
                    "For details, see the " +
                    "<https://developers.google.com/workspace/chat/format-messages" +
                    "|Chat API developer documentation>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/Advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    text: '👋🌎 Hello world!' +
          'Text messages can contain things like:\n\n' +
          '* Hyperlinks 🔗\n' +
          '* Emojis 😄🎉\n' +
          '* Mentions of other Chat users `@` \n\n' +
          'For details, see the ' +
          '<https://developers.google.com/workspace/chat/format-messages' +
          '|Chat API developer documentation>.'
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

כדי להריץ את הדוגמה הזו, מחליפים את SPACE_NAME במזהה שמופיע בשדה name של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.

התחלת שרשור או מענה לשרשור

במרחבים משותפים שמחולקים לשרשורים, תוכלו לציין אם הודעה חדשה תתחיל שרשור או תשיב לשרשור קיים.

כברירת מחדל, הודעות שיוצרים באמצעות Chat API מתחילות שרשור חדש. כדי שתוכלו לזהות את השרשור ולהשיב לו מאוחר יותר, תוכלו לציין מפתח שרשור בבקשה:

  • מציינים את השדה thread.threadKey בגוף הבקשה.
  • כדי להבין מה יקרה אם המפתח כבר קיים, מציינים את פרמטר השאילתה messageReplyOption.

כדי ליצור הודעה שתהיה תשובה לשרשור קיים:

  • לכלול את השדה thread בגוף הבקשה. אם מגדירים את הפרמטר, אפשר לציין את הערך של threadKey שיצרתם. אחרת, צריך להשתמש בname של השרשור.
  • מציינים את פרמטר השאילתה messageReplyOption.

הקוד הבא מראה דוגמה לאופן שבו אפליקציית Chat יכולה לשלוח הודעת טקסט שמתחילה או עונה לשרשור נתון שמזוהה באמצעות מפתח של מרחבים משותפים מסוימים, בשם משתמש מאומת:

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {createClientWithUserCredentials} from './authentication-utils.js';
const {MessageReplyOption} = require('@google-apps/chat').protos.google.chat.v1.CreateMessageRequest;

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption: MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/Advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with thread key
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = 'REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD';
  const message = {
    text: 'Hello with user credential!',
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: 'THREAD_KEY'
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageReplyOption: messageReplyOption
  });

  // Handle the response
  console.log(response);
}

כדי להריץ את הדוגמה הזו, מחליפים את הפרטים הבאים:

  • THREAD_KEY: מפתח של שיחה קיימת במרחב המשותף, או שם ייחודי לשיחה חדשה.
  • SPACE_NAME: המזהה מהשדה name של המרחב המשותף. כדי לאתר אותו, אפשר לשלוח קריאה ל-method ListSpaces() או לכתובת ה-URL של המרחב המשותף.

איך נותנים שם להודעה

כדי לאחזר או לציין הודעה בקריאות עתידיות ל-API, אפשר לתת לה שם על ידי הגדרת השדה messageId בבקשה. מתן שם להודעה מאפשר לכם לציין את ההודעה בלי לאחסן את המזהה שהמערכת הקצתה משם המשאב של ההודעה (שמיוצג בשדה name).

לדוגמה, כדי לאחזר הודעה באמצעות השיטה get(), משתמשים בשם המשאב כדי לציין איזו הודעה לאחזר. שם המשאב מוגדר בפורמט spaces/{space}/messages/{message}, כאשר {message} מייצג את המזהה שהמערכת הקצתה או את השם המותאם אישית שהגדרתם כשיצרתם את ההודעה.

כדי לתת שם להודעה, צריך לציין מזהה מותאם אישית בשדה messageId כשיוצרים את ההודעה. השדה messageId מגדיר את הערך לשדה clientAssignedMessageId של המשאב Message.

אפשר לתת שם להודעה רק כשאתם יוצרים אותה. אי אפשר לתת שם למזהה מותאם אישית של הודעות קיימות או לשנות אותו. המזהה המותאם אישית צריך לעמוד בדרישות הבאות:

  • מתחיל ב-client-. לדוגמה, הערך client-custom-name הוא מזהה מותאם אישית תקין, אבל הערך custom-name לא תקין.
  • מכיל עד 63 תווים, ורק אותיות קטנות, מספרים ומקפים.
  • ייחודי במרחב המשותף. אי אפשר להשתמש באותו מזהה מותאם אישית להודעות שונות באפליקציית צ'אט.

הקוד הבא מציג דוגמה לאופן שבו אפליקציית Chat יכולה לשלוח הודעת טקסט עם מזהה למרחב משותף מסוים בשם משתמש מאומת:

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: { text: 'Hello with user credential!' }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with message id
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = 'client-MESSAGE-ID';
  const message = { text: 'Hello with user credential!' };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageId: messageId
  });

  // Handle the response
  console.log(response);
}

כדי להריץ את הדוגמה הזו, מחליפים את הפרטים הבאים:

  • SPACE_NAME: המזהה מהשדה name של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.
  • MESSAGE-ID: שם להודעה שמתחיל ב-custom-. השם צריך להיות ייחודי ושונה מכל שמות ההודעות האחרים שנוצרו על ידי אפליקציית Chat במרחב המשותף שצוין.

פתרון בעיות

כשאפליקציית Google Chat או כרטיס מחזירים שגיאה, מוצגת בממשק של Chat ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מוצגת הודעת שגיאה, אבל באפליקציה או בכרטיס של Chat מתקבלת תוצאה לא צפויה. לדוגמה, יכול להיות שלא תוצג הודעה בכרטיס.

יכול להיות שהודעת שגיאה לא תוצג בממשק המשתמש של Chat, אבל כשיומני השגיאות של אפליקציות Chat מופעלים, יהיו זמינות הודעות שגיאה תיאוריות ונתוני יומנים שיעזרו לכם לתקן שגיאות. במאמר פתרון בעיות ושגיאות ב-Google Chat מוסבר איך מציגים, מאתרים באגים ומתקנים שגיאות.