RCS-Vorschläge Chips

Mit RCS Suggestions können Sie vorgeschlagene Antworten und Aktionen in Ihren RCS-Nachrichten verwenden. Sie können in verschiedenen Nachrichtentypen wie Karten, Karussells und Textnachrichten enthalten sein und werden in der JSON-Nutzlast dieser Nachrichten als Array von Vorschlagsobjekten definiert.

Bei diesen Vorschlagsobjekten kann es sich um Antwortvorschläge, Aktionsvorschläge oder eine Kombination aus beidem handeln. Die genaue Struktur der Objekte variiert je nach Art des Vorschlags.

Vorschläge

Vorschläge sind interaktive UI-Elemente, die in unterstützten RCS-Messaging-Apps als Schaltflächen oder "Chips" dargestellt werden. Jeder Vorschlag stellt eine schnelle Antwort oder eine Aktion dar, auf die der Benutzer tippen kann. Diese Chips erscheinen unter dem Hauptteil der Nachricht und verschwinden, sobald der Nutzer mit ihnen interagiert oder eine neue Nachricht empfangen hat.

Es gibt zwei Arten von Vorschlägen:

Vorgeschlagene Antworten: Vordefinierte Benutzerreaktionen, die eine Eingangsnachricht vom Typ reply zu der für Ihren Webhook für eingehende Nachrichten definierten URL.
Vorgeschlagene Maßnahmen: Schaltflächen, die eine Aktion ausführen, z. B. eine URL öffnen oder eine Nummer anrufen, und eine eingehende Nachricht vom Typ button zu der für Ihren Webhook für eingehende Nachrichten definierten URL.

Hinweis: Sie können auch ein Vorschlags-Array in eine Rich-Card-Nachricht aufnehmen. Da ein Karussell eine Sammlung von Karten ist, kann jede Karte in einem Karussell auch ihr eigenes Vorschlags-Array enthalten. Siehe Reichhaltige Karten und Karussells für weitere Informationen.

Vorgeschlagene Antworten

Verwenden Sie vorgeschlagene Antworten, wenn Sie eine Antwort erwarten, die programmatisch verarbeitet werden kann. Jede Antwort enthält:

text: Wird auf dem Chip angezeigt.
postback_data: Ein Bezeichner, der in der eingehenden reply Nutzlast der Nachricht als id Parameter.

Hier ist ein Beispiel für eine RCS-Nachricht des Typs text mit zwei Antwortvorschlägen:

{
   "to": "447700900000",
   "from": "Vonage",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello, world!",
   "suggestions": [
       {
           "type": "reply",
           "text": "Suggestion #1",
           "postback_data": "suggestion_1"
       },
       {
           "type": "reply",
           "text": "Suggestion #2",
           "postback_data": "suggestion_2"
       }
   ]
}

Wenn der Empfänger auf einen der Vorschläge tippt, würde dies eine Eingangsnachricht vom Typ replyHier wird der Wert von id variieren, je nachdem, welchen Vorschlagschip der Nutzer ausgewählt hat:

{
  "to": "Vonage",
  "from": "447900000000",
  "channel": "rcs",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2024-02-08T10:12:44Z",
  "message_type": "reply",
  "reply": {
    "id": "suggestion_1",
    "title": "Suggestion #1"
  }
}

Vorgeschlagene Maßnahmen

Vorgeschlagene Aktionen führen eine Funktion aus und geben strukturierte Daten über eine Tastennachricht zurück. Alle Aktionen erfordern:

type: Bestimmt die Art der Aktion
text: Chip-Etikett (max. 25 Zeichen)
postback_data: Ein Bezeichner, der in der eingehenden button Nutzlast der Nachricht als payload Parameter.

Die meisten Aktionstypen erfordern auch einen oder mehrere zusätzliche Parameter, um die spezifische Aktion zu unterstützen. Einige Typen haben auch weitere optionale Parameter. Diese Parameter werden in den nachstehenden Beschreibungen der einzelnen Typen näher erläutert:

Eine URL öffnen

Dieses Aktionsobjekt hat eine type von open_url und hat die folgenden zusätzlichen Eigenschaften:

url: Die zu öffnende URL. Hinweis: Die einzigen zulässigen Schemata sind http:// und https://andere Schemata wie z.B. tel, mailtousw. sind nicht zulässig.
description: Eine optionale Beschreibung der URL für Zwecke der Barrierefreiheit.
url (String): Dies ist die zu öffnende URL.

Wenn dieser Aktionschip angetippt wird, öffnet das Gerät des Empfängers die angegebene URL entweder im Standardbrowser des Geräts oder in einer installierten App (wenn eine App als Handler für die Domain der URL registriert ist).

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description"
   }
  ]
 }

Eine URL in der Webansicht öffnen

Dieses Aktionsobjekt hat eine type von open_url_in_webview und hat die folgenden zusätzlichen Eigenschaften:

url: Die zu öffnende URL. Hinweis: Die einzigen zulässigen Schemata sind http:// und https://andere Schemata wie z.B. tel, mailtousw. sind nicht zulässig.
description: Eine optionale Beschreibung der URL für Zwecke der Barrierefreiheit.
view_mode: Der Modus für die Anzeige der URL im Webview-Fenster. Entweder FULL, TALL, oder HALF.

Wenn dieser Aktionschip angetippt wird, öffnet das Gerät des Empfängers die angegebene URL innerhalb der Messaging-App selbst, wobei die Größe der Webseite innerhalb der App-Oberfläche durch den Wert des Parameters view_mode Parameter.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url_in_webview",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description",
     "view_mode": "FULL"
   }
  ]
 }

Wählen Sie eine Number

Dieses Aktionsobjekt hat eine type von dial und hat die folgenden zusätzlichen Eigenschaften:

phone_number (String): Dies ist die zu wählende Telefonnummer. Sie muss im E.164-Format vorliegen, die Landesvorwahl enthalten und mit einem vorangestellten +zum Beispiel +447900000000
fallback_url (String): Dies ist eine URL, die geöffnet werden soll, wenn es nicht möglich ist, die Wahlaktion zu starten.

Wenn dieser Aktions-Chip angetippt wird, wird der Empfänger angewiesen, die angegebene Telefonnummer anzurufen.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "dial",
     "text": "Call",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/contact/",
     "phone_number": "+15556667777"
   }
 ]
}

Einen Standort anzeigen

Dieses Aktionsobjekt hat eine type von view_location und hat die folgenden zusätzlichen Eigenschaften:

latitude (Zeichenfolge): Der Breitengrad in Grad. Er muss im Bereich [-90.0, +90.0] liegen.
longitude (Zeichenfolge): Der Längengrad in Grad. Er muss im Bereich [-180.0, +180.0] liegen.
pin_label (String): eine optionale Eigenschaft, die der auf der Karte angezeigten Stecknadel eine Beschriftung hinzufügt.
fallback_url (String): Dies ist eine URL, die geöffnet werden soll, wenn es nicht möglich ist, die Ansichtsortaktion zu starten.

Wenn dieser Aktions-Chip angetippt wird, zeigt das Gerät des Empfängers den angegebenen Ort in der Standard-Kartenanwendung des Geräts an.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "view_location",
     "text": "View map",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
     "latitude": "37.4220188",
     "longitude": "-122.0844786",
     "pin_label": "Googleplex"
   }
 ]
}

Einen Standort freigeben

Dieses Aktionsobjekt hat eine type von share_location und hat nur drei erforderliche Parameter: type, textund postback_data.

Wenn dieser Aktions-Chip angetippt wird, öffnet das Gerät des Empfängers die Standard-Standortauswahl, damit der Empfänger einen Ort für die Rücksendung auswählen kann.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "share_location",
     "text": "Share your location",
     "postback_data": "postback_data_1234"
   }
 ]
}

Ein Kalenderereignis erstellen

Dieses Aktionsobjekt hat eine type von create_calendar_event und hat die folgenden zusätzlichen Eigenschaften:

start_time (String im Zeitstempelformat): definiert die Startzeit des Ereignisses. Ein Zeitstempel im RFC3339 UTC-Format "Zulu", zum Beispiel 2024-06-28T19:00:00Z
end_time (String im Timestamp-Format): definiert die Endzeit des Ereignisses. Ein Zeitstempel im RFC3339 UTC-Format "Zulu", zum Beispiel 2024-06-28T19:00:00Z.
title (String): definiert den Titel des Ereignisses.
description (String): definiert die Beschreibung des Ereignisses.
fallback_url (String): Dies ist eine URL, die geöffnet wird, wenn die Aktion "Kalenderereignis erstellen" nicht ausgelöst werden kann.

Wenn dieser Aktions-Chip angetippt wird, öffnet das Gerät des Empfängers die Standard-Kalender-App und beginnt mit der Erstellung eines neuen Kalenderereignisses mit den im Aktionsobjekt definierten Daten.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
         {
     "type": "create_calendar_event",
     "text": "Save to calendar",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/calendar",
     "start_time": "2020-06-30T19:00:00Z",
     "end_time": "2020-06-30T20:00:00Z",
     "title": "My calendar event",
     "description": "Description of the calendar event"
   }
 ]
}

Code-Schnipsel

Nachfolgend finden Sie eine Liste von Codeschnipseln zum Senden von Nachrichtenanforderungen für verschiedene Nachrichtentypen: