Agenci RCS for Business komunikują się z użytkownikami, wysyłając i odbierając wiadomości. Aby wysyłać wiadomości do użytkowników, agent wysyła żądania wiadomości do interfejsu API RCS Business Messaging. Pojedyncze żądanie może zawierać tekst , karty graficzne , pliki multimedialne i PDF , sugerowane odpowiedzi oraz sugerowane działania .
Platforma RCS for Business zwraca błędy w pewnych sytuacjach, aby ułatwić zarządzanie dostarczaniem wiadomości:
- Jeśli wyślesz wiadomość do użytkownika, którego urządzenie nie obsługuje RCS lub nie ma włączonej funkcji RCS, platforma RCS for Business zwróci błąd 404 NOT_FOUND. W takim przypadku możesz spróbować skontaktować się z użytkownikiem za pomocą metod awaryjnych zdefiniowanych w infrastrukturze.
- Jeśli wyślesz wiadomość do użytkownika RCS w sieci, w której Twój agent nie został jeszcze uruchomiony lub w sieci, w której nie włączono ruchu RCS, platforma RCS for Business zwróci błąd 404 NOT_FOUND.
- Jeśli wyślesz wiadomość z funkcjami, których urządzenie użytkownika nie obsługuje, platforma RCS for Business zwróci błąd 400 INVALID_ARGUMENT i nie dostarczy wiadomości.
W ramach strategii wielokanałowego przesyłania wiadomości najlepiej odwoływać wiadomości , które nie zostały dostarczone po rozsądnym czasie i wysyłać je innym kanałem. Aby odwoływać wiadomości automatycznie w zdefiniowanym czasie, ustaw datę wygaśnięcia wiadomości .
Odbiorca jest offline
Platforma RCS for Business nadal akceptuje wiadomość do doręczenia, nawet jeśli odbiorca jest offline. Otrzymujesz odpowiedź 200 OK, a platforma RCS for Business wstrzymuje wiadomość i podejmuje próby ponownego doręczenia przez 30 dni. Nie ma potrzeby ponownego proszenia RCS for Business o wysłanie wiadomości.
Usługa RCS for Business usuwa wszystkie niedostarczone wiadomości po upływie 30 dni od ich wysłania.
W zależności od przypadku, w którym korzysta Twój agent, możesz chcieć odwołać niedostarczoną wiadomość przed upływem 30 dni. Odwołanie może zapobiec otrzymywaniu przez użytkowników offline nieaktualnych wiadomości po powrocie do sieci. Istnieje wiele sposobów odwołania wiadomości:
- Aby zainicjować odwołanie , należy wysłać żądanie odwołania .
- Ustaw datę wygaśnięcia wiadomości , aby automatycznie ją odwołać w odpowiednim momencie.
Ustaw datę wygaśnięcia wiadomości
Czy wiadomość Twojego agenta jest ograniczona czasowo? Na przykład hasła jednorazowe (OTP) są ważne tylko przez krótki czas. Oferty ograniczone czasowo wygasają. Przypomnienia o spotkaniach nie są już ważne po dacie spotkania. Aby wiadomości były aktualne i trafne, ustaw datę wygaśnięcia wiadomości. Dzięki temu użytkownicy offline nie będą otrzymywać nieaktualnych treści po powrocie do sieci. Data wygaśnięcia to również dobry sygnał do uruchomienia strategii awaryjnego wysyłania wiadomości, aby użytkownicy otrzymywali potrzebne informacje na czas.
Aby ustawić datę wygaśnięcia wiadomości, określ jedno z następujących pól w wiadomości agenta:
-
expireTime: dokładny czas w formacie UTC, kiedy wiadomość wygaśnie. -
ttl(czas życia): ilość czasu, po której wiadomość wygaśnie.
Informacje na temat formatowania i opcji wartości można znaleźć w AgentMessage .
Maksymalna wartość ttl i expireTime wynosi 15 dni od daty wysłania wiadomości.
Chociaż nie ma minimalnej wartości ttl i expireTime , zaleca się, aby po wysłaniu wiadomości odczekać co najmniej 10 sekund , aby znacznie zmniejszyć szansę otrzymania powiadomienia o odwołaniu i dostarczeniu.
Czas życia (TTL) wiadomości
Ustawiając TTL dla wiadomości RCS for Business, określasz, jak długo wiadomość ma być uznawana za ważną i możliwą do dostarczenia. Jeśli wiadomość nie zostanie pomyślnie dostarczona na urządzenie użytkownika w tym okresie TTL, platforma RCS for Business automatycznie podejmie próbę jej odwołania.
Inicjując odwołanie wiadomości, żądasz od platformy RCS for Business zaprzestania prób dostarczenia tej konkretnej wiadomości. Działanie to ma jednak wpływ tylko na przyszłe próby dostarczenia. Jeśli urządzenie użytkownika pomyślnie pobrało już wiadomość, jest ona przetwarzana, a platforma RCS for Business nie może jej odwołać z urządzenia użytkownika.
Oto, czego możesz się spodziewać w kwestii powiadomień:
Wiadomość dostarczona w czasie TTL: Jeśli urządzenie użytkownika połączy się z siecią i odbierze wiadomość przed upływem czasu TTL, otrzymasz powiadomienie
DELIVERED. Powiadomienie o odwołaniu nie zostanie wysłane, ponieważ wiadomość została pomyślnie dostarczona. Jest to najczęstszy i najbardziej oczekiwany scenariusz.Wiadomość nie została dostarczona przed upływem czasu TTL: Jeśli czas TTL upłynie przed dotarciem wiadomości do urządzenia użytkownika (na przykład urządzenie jest offline), platforma RCS for Business podejmie próbę odwołania wiadomości. Otrzymasz powiadomienie
TTL_EXPIRATION_REVOKED, które oznacza, że wiadomość została pomyślnie usunięta z kolejki doręczeń. W takim przypadku użytkownik nie otrzyma wiadomości.
Zalecenia dotyczące obsługi przypadków brzegowych
Nasz system równolegle przetwarza doręczenie wiadomości RCS for Business i przekroczenia TTL. Z tego powodu bardzo rzadko zdarzają się skrajne przypadki, w których moment wysłania powiadomień jest nieoczekiwany. Na przykład możesz otrzymać zarówno powiadomienie o doręczeniu, jak i TTL, lub nie otrzymać żadnego.
Oto nasze zalecenia dotyczące obsługi powiadomień o wiadomościach RCS for Business:
Powiadomienie
DELIVERED: Otrzymanie powiadomieniaDELIVEREDwiadomości potwierdza jej dotarcie do użytkownika. Możesz bezpiecznie zignorować wszelkie późniejsze powiadomienia TTL dotyczące tej konkretnej wiadomości.Powiadomienie
TTL_EXPIRATION_REVOKED: Jeśli otrzymasz powiadomienie TTL o statusieTTL_EXPIRATION_REVOKED, oznacza to, że system RCS for Business zaprzestał prób dostarczenia tej konkretnej wiadomości. Należy potraktować tę wiadomość jako niedostarczoną i w razie potrzeby zastosować strategię awaryjną.Powiadomienie TTL z jakimkolwiek innym statusem: Otrzymanie powiadomienia TTL z jakimkolwiek innym statusem oznacza nieudaną próbę odwołania.
- W przypadku ważnych wiadomości, takich jak hasła jednorazowe (OTP), zainicjuj metodę awaryjną.
- W przypadku wiadomości niekrytycznych zdecyduj, czy zainicjować procedurę zapasową.
- Brak powiadomień: W rzadkich przypadkach system może nie wysłać powiadomienia TTL, a klient może również nie wygenerować powiadomienia o dostarczeniu. Jest to niezwykle rzadki przypadek.
Ustaw typ ruchu wiadomości
Interfejs API RBM zawiera pole messageTrafficType do kategoryzacji wiadomości. Podczas gdy przypadki użycia agentów nadal definiują ich zachowanie i obowiązujące reguły biznesowe, messageTrafficType umożliwia bardziej szczegółową kategoryzację treści wiadomości. Ostatecznie umożliwia to pojedynczemu agentowi obsługę wielu przypadków użycia. Obecnie nie ma to wpływu na istniejące przypadki użycia agentów ani reguły biznesowe.
To pole jest opcjonalne, ale zalecamy jego ustawienie teraz. Dzięki temu nie pojawi się komunikat o błędzie, gdy stanie się wymagane.
Aby ustawić typ ruchu wiadomości, przypisz odpowiedni messageTrafficType do każdej wiadomości na podstawie jej zawartości. RCS for Business obsługuje następujące typy ruchu.
| Rodzaj ruchu | Treść wiadomości | Przypadek użycia agenta |
|---|---|---|
AUTHENTICATION | Do wiadomości uwierzytelniających. | OTP |
TRANSACTION | W przypadku wiadomości dotyczących istniejących usług lub produktów użytkownika. Na przykład: potwierdzeń, potwierdzeń płatności lub szczegółów rezerwacji. | Transakcyjne lub wielokrotnego użytku |
PROMOTION | W przypadku wiadomości promocyjnych, takich jak oferty, rabaty, ogłoszenia lub inne treści promocyjne. | Promocyjne lub wielofunkcyjne |
SERVICEREQUEST | W przypadku wiadomości o usługach, o które użytkownik wyraźnie poprosił. | OTP, transakcyjne, promocyjne lub wielokrotnego użytku |
ACKNOWLEDGEMENT | W przypadku wiadomości potwierdzających działanie użytkownika – w szczególności prośbę o anulowanie subskrypcji. Potwierdza to, że prośba użytkownika została odebrana i jest przetwarzana. | OTP, transakcyjne, promocyjne lub wielokrotnego użytku |
Jeżeli nie ustawiono żadnego typu ruchu, system przypisuje domyślny typ dla danego przypadku użycia agenta .
| Przypadek użycia agenta | Domyślny typ ruchu |
|---|---|
| OTP | AUTHENTICATION |
| Transakcyjny | TRANSACTION |
| Promocyjny | PROMOTION |
| Wielofunkcyjny | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Agenci wielozadaniowi nie mają domyślnego typu ruchu. Należy jawnie ustawić typ ruchu dla każdej wiadomości na podstawie jej zawartości. Jeśli nie zmienisz wartości MESSAGE_TRAFFIC_TYPE_UNSPECIFIED , wystąpi błąd.
Limity rozmiaru wiadomości
Maksymalny rozmiar całego komunikatu AgentMessage w postaci ciągu znaków wynosi 250 KB. Część tekstowa komunikatu ma własny limit 3072 znaków.
Aby zapobiec nieoczekiwanemu zużyciu danych przez użytkowników, maksymalny rozmiar pliku, który można wysłać za pośrednictwem RCS for Business, wynosi 100 MiB, a łączny rozmiar wszystkich plików multimedialnych i załączników PDF w jednej wiadomości RCS for Business nie może przekraczać 100 MiB. (1 MiB = 1 048 576 bajtów). Więcej informacji można znaleźć w sekcji Pliki multimedialne i PDF .
Tekst
Najprostsze komunikaty składają się z tekstu. Wiadomości tekstowe najlepiej nadają się do przekazywania informacji bez konieczności stosowania elementów wizualnych, złożonej interakcji czy odpowiedzi.
Przykład
Poniższy kod wysyła wiadomość tekstową. Informacje o formatowaniu i opcjach wartości można znaleźć w pliku phones.agentMessages.create .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Podstawowa treść wiadomości - konwersja SMS-ów
Operatorzy wprowadzili modele rozliczeniowe , aby wspierać przeniesienie wiadomości SMS do systemu RCS for Business. Wiadomość RCS for Business zawierająca do 160 znaków UTF-8 nazywana jest wiadomością podstawową.
Konstruując żądanie wysłania wiadomości podstawowej, pamiętaj, że znaki liczone są jako 1 bajt (UTF-8). Jeśli wysyłasz wiadomość zawierającą znaki specjalne, takie jak emoji lub zestaw znaków wielobajtowych, każdy znak liczony jest jako 2-4 znaki UTF-8 lub więcej.
Wpisz tekst w pole, aby sprawdzić jego długość:
Treść wiadomości tekstowych i podgląd linków
Klienci RCS mogą implementować podglądy linków. Jeśli wiadomość tekstowa RCS for Business zawiera adres URL witryny ze znacznikami OpenGraph , klient może wygenerować podgląd (obraz, tytuł itp.), zapewniając bogatsze wrażenia. Na przykład, zobacz podstawową wiadomość z podglądem adresu URL .
Należy pamiętać, że klient RCS może umożliwiać użytkownikowi wyłączenie podglądu łączy.
Jednorazowe hasła do weryfikacji użytkownika
Za pomocą RCS for Business możesz wysyłać hasła jednorazowe (OTP) w celu automatycznej weryfikacji użytkowników za pomocą interfejsu API SMS Retriever. Nie ma dedykowanego interfejsu API do odczytywania haseł jednorazowych przesyłanych przez RCS for Business.
Jak to działa na Androidzie
W przypadku aplikacji na Androida, które zarejestrowały się w interfejsie API SMS Retriever , interfejs API nasłuchuje poprawnie sformatowanej wiadomości RCS for Business. Wiadomość ta musi zawierać zarówno kod jednorazowego hasła (OTP), jak i unikalny skrót identyfikujący aplikację.
Gdy wiadomość RCS for Business zostanie odebrana w prawidłowym formacie, API SMS Retriever przetwarza ją tak samo, jak jednorazowe hasło SMS. Po dopasowaniu skrótu do aplikacji, jednorazowe hasło jest wyodrębniane i przekazywane do aplikacji w celu automatycznej weryfikacji użytkownika.
- Przykładowa wiadomość tekstowa RCS for Business służąca do weryfikacji użytkownika:
Your code is <OTP><app hash>. - Przykład:
Your code is 123456 M8tue43FGT.
Aby dowiedzieć się więcej o SMS Retriever i powiązanych interfejsach API, zapoznaj się z dokumentacją SMS Retriever . Szczegółowe informacje na temat automatycznej weryfikacji użytkowników w aplikacjach zarejestrowanych w interfejsie API SMS Retriever można znaleźć na tym schemacie blokowym .
Jak to działa na iOS
W systemie iOS wbudowana funkcja obsługi haseł jednorazowych (OTP) automatycznie wykrywa i sugeruje hasła jednorazowe RCS for Business do automatycznego wypełniania, podobnie jak w przypadku haseł jednorazowych SMS. Aplikacja na iOS nie wymaga integracji z konkretnym API, aby odczytać hasło jednorazowe.
Pliki multimedialne i PDF
Gdy wysyłasz wiadomość zawierającą obraz, wideo, plik audio lub PDF, Twój agent musi podać publicznie dostępny adres URL tej treści lub bezpośrednio przesłać plik.
Maksymalny rozmiar pliku, jaki można wysłać, wynosi 100 MiB. Łączny rozmiar wszystkich plików multimedialnych i załączników PDF w jednej wiadomości nie może przekraczać 100 MiB.
Kompresja i transkodowanie multimediów
Platforma RCS for Business automatycznie transkoduje i kompresuje pliki multimedialne (np. obrazy i filmy) przed ich wysłaniem, aby mieć pewność, że ładują się szybko i działają prawidłowo w różnych sieciach i na różnych urządzeniach.
Kompresja opiera się na jakości nośnika wejściowego, a nie wyłącznie na limitach rozmiaru pliku. Oznacza to, że plik można skompresować nawet wtedy, gdy jego rozmiar jest znacznie poniżej maksymalnego limitu 100 MiB. Standardy transkodowania stale się zmieniają, więc nie ma sztywnego limitu rozmiaru pliku, który określałby, kiedy transkodowanie zostanie pominięte. Eksperymentuj z różnymi formatami multimediów, wymiarami i współczynnikami kompresji, aby znaleźć optymalną równowagę dla swoich danych.
Specyfikacje miniatur
W przypadku plików multimedialnych można również określić miniaturę, która umożliwia użytkownikom podgląd zawartości przed kliknięciem. W przypadku plików audio domyślny widżet audio służy jako symbol zastępczy.
- Maksymalny rozmiar pliku miniatury to 100 kB. Dla optymalnego działania zalecamy rozmiar 50 kB lub mniejszy.
- Proporcje miniatury powinny odpowiadać proporcjom oryginalnego pliku.
Buforowanie i zarządzanie adresami URL
Platforma RCS for Business buforuje pliki przez 60 dni, a interfejs API zwraca identyfikator pliku, który agent może dołączyć do wiadomości wysyłanych do użytkowników. Po 60 dniach RCS for Business usuwa pliki z pamięci podręcznej.
Podczas określania plików za pomocą adresu URL, najlepszą praktyką jest ustawienie contentMessage.forceRefresh na false . Ustawienie contentMessage.forceRefresh na true wymusza na RCS for Business pobieranie nowej zawartości z określonego adresu URL, nawet jeśli zawartość tego adresu jest zapisana w pamięci podręcznej, co wydłuża czas dostarczania wiadomości użytkownikom.
Przykład adresu URL pliku
Poniższy kod wysyła obraz. Informacje o formatowaniu i opcjach wartości można znaleźć w artykule AgentContentMessage .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
Alternatywnie możesz przesłać multimedia przed wysłaniem ich w wiadomości za pomocą polecenia files.create .
Przykład przesyłania pliku
Poniższy kod przesyła plik wideo i plik miniatury, a następnie wysyła oba pliki w wiadomości. Informacje na temat formatowania i opcji wartości można znaleźć w files.create i AgentContentMessage .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: video/mp4" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"# Capture server-specified video file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: image/jpeg" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"# Capture server-specified image file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "uploadedRbmFile": { "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME", "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME" } } }'
Obsługiwane typy mediów
RCS for Business obsługuje następujące typy multimediów. W przypadku miniatur obsługiwane są tylko formaty: image/jpeg, image/jpg, image/gif i image/png.
| Typ nośnika | Typ dokumentu | Rozszerzenie | Działa z bogatymi kartami |
|---|---|---|---|
| aplikacja/ogg | Dźwięk OGG | .ogx | NIE |
| aplikacja/pdf | Tak (tylko dla Wiadomości Google w Indiach) | ||
| audio/aac | Dźwięk AAC | .aac | NIE |
| audio/mp3 | Dźwięk MP3 | .mp3 | NIE |
| dźwięk/mpeg | Dźwięk MPEG | .mpeg | NIE |
| dźwięk/mpg | Dźwięk MPG | .mp3 | NIE |
| dźwięk/mp4 | Dźwięk MP4 | .mp4 | NIE |
| audio/mp4-latm | Dźwięk MP4-latm | .mp4 | NIE |
| dźwięk/3gpp | Dźwięk 3GPP | .3gp | NIE |
| obraz/jpeg | JPEG | .jpeg, .jpg | Tak |
| obraz/gif | GIF | .gif | Tak |
| obraz/png | PNG | .png | Tak |
| wideo/h263 | Wideo H263 | .h263 | Tak |
| wideo/m4v | Wideo M4V | .m4v | Tak |
| wideo/mp4 | Wideo MP4 | .mp4 | Tak |
| wideo/mpeg4 | Wideo MPEG-4 | .mp4, .m4p | Tak |
| wideo/mpeg | Wideo MPEG | .mpeg | Tak |
| wideo/webm | Wideo WEBM | .webm | Tak |
Sugestie
Twój agent wysyła sugestie (sugerowane odpowiedzi i sugerowane działania) na listach żetonów sugestii lub w bogatych kartach .
Sugerowane odpowiedzi
Sugerowane odpowiedzi prowadzą użytkowników przez konwersację, zapewniając odpowiedzi, na które Twój agent wie, jak zareagować.
Gdy użytkownik kliknie sugerowaną odpowiedź, Twój agent otrzyma zdarzenie zawierające tekst odpowiedzi i dane zwrotne . Maksymalna długość danych wynosi 2048 znaków.
Przykład
Poniższy kod wysyła tekst z dwiema sugerowanymi odpowiedziami. Informacje na temat formatowania i opcji wartości można znaleźć w artykule SuggestedReply .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Sugerowane działania
Sugerowane działania prowadzą użytkowników przez rozmowy, wykorzystując wbudowane funkcje ich urządzeń. Twój agent może zasugerować użytkownikom wybranie numeru, otwarcie lokalizacji na mapie, udostępnienie lokalizacji, otwarcie adresu URL lub utworzenie wydarzenia w kalendarzu.
Dla każdej sugerowanej czynności możesz opcjonalnie podać zapasowy adres URL (maksymalnie 2048 znaków). Ten adres URL otworzy się w nowym oknie przeglądarki, jeśli urządzenie użytkownika nie obsługuje sugerowanej czynności.
Gdy użytkownik kliknie sugerowaną akcję, Twój agent otrzyma zdarzenie zawierające dane zwrotne dotyczące tej akcji .
Informacje na temat formatowania i opcji wartości można znaleźć w artykule SuggestedAction .
Wyświetlanie sugestii
Istnieją dwa sposoby wyświetlania sugestii:
- Trwałe : sugerowane działania lub odpowiedzi, które są wyświetlane w dymku wiadomości i pozostają niezmienione przez cały czas trwania konwersacji.
- Tymczasowe : sugestie wyświetlane poza dymkiem wiadomości i znikające, gdy konwersacja jest kontynuowana.
Obsługiwane formaty wiadomości
- Stałe sugestie: Praca z samodzielnymi wiadomościami tekstowymi i bogatymi kartami.
- Sugestie tymczasowe: praca z samodzielnymi wiadomościami tekstowymi, wiadomościami multimedialnymi i bogatymi kartami.
Połącz sugestie
W tej samej wiadomości lub bogatej karcie możesz mieszać sugestie stałe i tymczasowe.
- Wiadomości tekstowe: Sugestie są domyślnie tymczasowe. Aby pozostały w bańce, należy je skonfigurować jako trwałe.
- Karty Rich: domyślnie obsługują do czterech stałych sugestii. Możesz dodać tymczasowe sugestie jako „listę chipów” pod kartą.
Limity sugestii
Pojedyncza wiadomość tekstowa obsługuje maksymalnie 11 sugestii. Wszelkie sugestie stałe wliczają się do tego limitu. Na przykład, jeśli dodasz 4 sugestie stałe, możesz dodać maksymalnie 7 sugestii przejściowych.
| Typ sugestii | Limit | Gdzie się pojawiają |
|---|---|---|
| Uporczywy | Do 4 | Wewnątrz bańki wiadomości |
| Przejściowy | Do 11 | Poza bańką (jako chipsy) |
Limit znaków
Każda propozycja może mieć maksymalnie 25 znaków.
Przejrzystość adresu URL w sugerowanych działaniach
Aby zbudować zaufanie użytkowników, podstawowy adres URL jest wyświetlany jako druga linia tekstu wewnątrz przycisku sugestii dla sugerowanych działań „Otwórz adres URL”. To spójne zachowanie dotyczy samodzielnych wiadomości tekstowych, kart rozszerzonych i karuzel.
Wspieranie klientów w zakresie ciągłych sugestii
- Obsługiwane: Google Messages (wersja
20260225.00lub nowsza). - Nieobsługiwane: wersje aplikacji Google Messages starsze niż
20260225.00, iOS i Samsung Messages.
Wybierz numer
Funkcja „Wybierz numer” umożliwia użytkownikowi wybranie numeru telefonu wskazanego przez agenta. Numery telefonów mogą zawierać wyłącznie cyfry ( 0-9 ), znak plus ( + ), gwiazdkę ( * ) i znak cyfry ( # ). Międzynarodowy format E.164 (na przykład +14155555555 ) jest obsługiwany, ale nie jest wymagany. Oznacza to, że zarówno +14155555555 jak i 1011 są prawidłowymi wpisami.
Przykład
Poniższy kod wysyła akcję wybierania numeru. Informacje na temat formatowania i opcji wartości można znaleźć w artykule DialAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Wyświetl lokalizację
Akcja „Wyświetl lokalizację” wyświetla lokalizację w domyślnej aplikacji mapowej użytkownika. Możesz określić lokalizację według szerokości i długości geograficznej lub za pomocą zapytania opartego na bieżącej lokalizacji użytkownika. Możesz również ustawić własną etykietę dla pinezki wyświetlanej w aplikacji mapowej.
Przykład
Poniższy kod wysyła akcję lokalizacji widoku. Informacje na temat formatowania i opcji wartości można znaleźć w artykule ViewLocationAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Udostępnij lokalizację
Akcja „Udostępnij lokalizację” pozwala użytkownikowi udostępnić lokalizację agentowi. Użytkownik może udostępnić swoją bieżącą lokalizację lub lokalizację wybraną ręcznie z aplikacji Mapy.
Przykład
Poniższy kod wysyła akcję lokalizacji udostępniania. Informacje na temat formatowania i opcji wartości można znaleźć w artykule ShareLocationAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Otwórz adres URL
Akcja „Otwórz adres URL” pozwala kierować użytkowników do strony internetowej wskazanej przez agenta. Domyślnie strona internetowa otwiera się w przeglądarce użytkownika. Możesz również skonfigurować otwieranie strony internetowej w widoku internetowym. Szczegółowe informacje znajdziesz w artykule „Otwieranie adresu URL za pomocą widoku internetowego” .
Tylko w Wiadomościach Google
Wyświetlanie podstawowego adresu URL : Aby zwiększyć przejrzystość wiadomości A2P, Google Messages wyświetla podstawowy adres URL w sugerowanych akcjach „Otwórz adres URL”. Ta zmiana dotyczy sugerowanych akcji w standardowych kartach rozszerzonych i karuzelach kart rozszerzonych .
Wyświetlanie ikony aplikacji dla linków internetowych : Jeśli użytkownik ma skonfigurowaną domyślną aplikację dla strony internetowej, otwiera się ona zamiast przeglądarki lub widoku internetowego, a przycisk sugestii wyświetla ikonę aplikacji. Aby ikona aplikacji była wyświetlana w Wiadomościach Google, należy podać pełny, bezpośredni adres URL. Jeśli używasz skróconego adresu URL, wyświetlana jest domyślna ikona „Otwórz adres URL”.
Przykład
Poniższy kod wysyła akcję otwierania adresu URL. Informacje na temat formatowania i opcji wartości można znaleźć w artykule OpenUrlAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Otwórz adres URL za pomocą widoku internetowego
Akcja „Otwórz adres URL z webview” ładuje określoną stronę internetową w aplikacji do przesyłania wiadomości za pomocą silnika renderującego domyślnej przeglądarki. Pozwala to użytkownikowi na interakcję ze stroną internetową bez opuszczania konwersacji RCS for Business. Jeśli urządzenie użytkownika nie obsługuje webviewów, strona internetowa otwiera się w przeglądarce użytkownika. Aby włączyć webviewy, zapoznaj się z OpenURLApplication .
Widoki internetowe mają trzy tryby wyświetlania. Informacje na temat formatowania i opcji wartości można znaleźć w WebviewViewMode .
- Pełny: strona internetowa zajmuje cały ekran
- Połowa: Strona internetowa zajmuje połowę ekranu
- Wysokość: strona internetowa zajmuje trzy czwarte ekranu
Przykład
Poniższy kod wysyła adres URL Open z akcją webview. Informacje na temat formatowania i opcji wartości można znaleźć w artykule OpenURLAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com", "application": "WEBVIEW", "webviewViewMode": "FULL", "description": "Accessibility description" } } } ] } }'
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { String URL = "https://www.google.com"; // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // Create suggestion to view webpage in full mode Suggestion viewInFullMode = getUrlActionInWebview(URL, "FULL") suggestions.add(viewInFullMode); // create suggestion to view webpage in half mode Suggestion viewInHalfMode = getUrlActionInWebview(URL, "HALF") suggestions.add(viewInHalfMode); // create suggestion to view webpage in tall mode Suggestion viewInTallMode = getUrlActionInWebview(URL, "TALL") suggestions.add(viewInTallMode); // Send simple text message with the suggested action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); } /** * Creates a suggested action to open URL in webview. * * @return a suggestion object for an open URL in webview action . */ private Suggestion getUrlActionInWebview(String url, String viewMode) { // create an open url action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl(url); openUrlAction.setApplication("WEBVIEW"); openUrlAction.setWebviewViewMode(viewMode); openUrlAction.setDescription("Accessibility description"); // attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setOpenUrlAction(openUrlAction); suggestedAction.setText('display_text'); suggestedAction.setPostbackData('postback_data_123'); // attach the action to a suggestion object Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); return suggestion; }
Utwórz wydarzenie w kalendarzu
Akcja Utwórz wydarzenie w kalendarzu otwiera aplikację kalendarza użytkownika i rozpoczyna tworzenie nowego wydarzenia z określonymi informacjami.
Tytuł wydarzenia w kalendarzu jest wymagany. Ma maksymalnie 100 znaków. Opis wydarzenia w kalendarzu jest opcjonalny i ma maksymalnie 500 znaków.
Przykład
Poniższy kod wysyła akcję tworzenia zdarzenia kalendarza. Informacje na temat formatowania i opcji wartości można znaleźć w artykule CreateCalendarEventAction .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Lista sugestii
Twój agent wysyła użytkownikom listy sugestii wraz z wiadomościami, które mają pomóc im w podjęciu dalszych działań. Lista sugestii wyświetla się tylko wtedy, gdy powiązana wiadomość znajduje się na dole konwersacji. Wszelkie kolejne wiadomości w konwersacji (od użytkownika lub agenta) nadpisują listę sugestii.
Elementy na liście to sugerowane odpowiedzi i sugerowane działania .
Lista żetonów może zawierać maksymalnie 11 sugerowanych żetonów, a etykieta każdego żetonu może mieć maksymalnie 25 znaków.
Informacje na temat formatowania i opcji wartości można znaleźć w AgentContentMessage .
Bogate karty
Karty Rich łączą multimedia, tekst i interaktywne sugestie w jedną wiadomość. Idealnie nadają się do prezentowania powiązanych informacji (na przykład produktu z jego zdjęciem, nazwą i ceną) i prowadzenia użytkowników przez jasne wskazówki dotyczące kolejnego kroku, np. sugestia „Wyświetl szczegóły”.
Karta bogata może zawierać następujące elementy:
- Media (obraz, GIF lub wideo)
- Tekst tytułu
- Tekst opisu
- Sugerowane odpowiedzi i sugerowane działania (maksymalnie 4)
Każde z tych pól jest opcjonalne, ale przynajmniej jedno z pól 1–3 musi zostać uwzględnione na karcie rozszerzonej.
Można wysłać wiele kartek razem, w poziomo przewijanej karuzeli .
Należy pamiętać, że całkowity ładunek dla rozbudowanej karty wynosi 250 KB.
Pełne dane techniczne znajdziesz w dokumentacji kart Rich .
Wysokość karty
Karty rozszerzone rozszerzają się w pionie, dopasowując się do swojej zawartości. Ich minimalna wysokość wynosi 112 DP, a maksymalna 344 DP. Jeśli zawartość karty nie jest wystarczająco duża, aby wypełnić minimalną wysokość karty, karta rozszerza się, a nadmiar wypełnia wolną przestrzenią.
Materiały multimedialne na bogatych kartach muszą mieścić się w jednej z trzech wysokości:
- Krótki: 112 DP
- Średni: 168 DP
- Wzrost: 264 DP
Jeśli dane medium nie mieści się w wymiarach karty ze względu na wybraną wysokość, podgląd medium jest wybierany poprzez powiększenie i przycięcie medium.
Przykład
Poniższy kod wysyła bogatą kartę z obrazkiem i sugerowanymi odpowiedziami. Informacje na temat formatowania i opcji wartości znajdziesz w artykule RichCard .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
Karuzele bogatych kart
Karuzele łączą ze sobą wiele bogatych kart , umożliwiając użytkownikom porównywanie elementów i reagowanie na każdy z nich z osobna.
Karuzele mogą zawierać od dwóch do maksymalnie dziesięciu kart rozszerzonych. Karty rozszerzonych w karuzelach muszą spełniać ogólne wymagania dotyczące zawartości i wysokości kart rozszerzonych, opisane w dokumentacji kart rozszerzonych . Więcej informacji na temat układu i specyfikacji karuzeli można znaleźć w dokumentacji karuzeli .
Przykład
Poniższy kod wysyła karuzelę kart rozszerzonych. Informacje na temat formatowania i opcji wartości można znaleźć w artykule RichCard .
kędzior
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "carouselCard": { "cardWidth": "MEDIUM", "cardContents": [ { "title": "Card #1", "description": "The description for card #1", "suggestions": [ { "reply": { "text": "Card #1", "postbackData": "card_1" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg", "forceRefresh": false } } }, { "title": "Card #2", "description": "The description for card #2", "suggestions": [ { "reply": { "text": "Card #2", "postbackData": "card_2" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg", "forceRefresh": false } } } ] } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Images for the carousel cards let card1Image = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; // Define the card contents for a carousel with two cards, each with one suggested reply let cardContents = [ { title: 'Card #1', description: 'The description for card #1', suggestions: [ { reply: { text: 'Card #1', postbackData: 'card_1', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card1Image, forceRefresh: false, }, }, }, { title: 'Card #2', description: 'The description for card #2', suggestions: [ { reply: { text: 'Card #2', postbackData: 'card_2', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card2Image, forceRefresh: false, }, }, }, ]; // Definition of carousel card let params = { msisdn: '+12223334444', cardContents: cardContents, }; // Send the device the carousel card defined above rbmApiHelper.sendCarouselCard(params, function(response) { console.log(response); });
Jawa
import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.CardWidth; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); List cardContents = new ArrayList(); // Images for the carousel cards String card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; // Create suggestions for first carousel card List card1Suggestions = new ArrayList(); card1Suggestions.add( new SuggestionHelper("Card #1", "card_1")); cardContents.add( new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, card1Suggestions) .getCardContent(MediaHeight.SHORT) ); // Images for the carousel cards String card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Create suggestions for second carousel card List card2Suggestions = new ArrayList(); card2Suggestions.add( new SuggestionHelper("Card #2", "card_2")); cardContents.add( new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, card2Suggestions) .getCardContent(MediaHeight.SHORT) ); // Send the carousel to the user rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Pyton
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Images for the carousel cards card_image_1 = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; # Suggested replies to be used in the cards suggestions1 = [ messages.SuggestedReply('Card #1', 'reply:card_1') ] suggestions2 = [ messages.SuggestedReply('Card #2', 'reply:card_2') ] # Define the card contents for a carousel with two cards, # each with one suggested reply card_contents = [] card_contents.append(messages.CardContent('Card #1', 'The description for card #1', card_image_1, 'MEDIUM', suggestions1)) card_contents.append(messages.CardContent('Card #2', 'The description for card #2', card_image_2, 'MEDIUM', suggestions2)) # Send the device the carousel card defined above carousel_card = messages.CarouselCard('MEDIUM', card_contents) cluster = messages.MessageCluster().append_message(carousel_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Image references to be used in the carousel cards string card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Suggestion chip lists to be used in carousel cards List<Suggestion> suggestions1 = new List<Suggestion> { new SuggestionHelper("Card #1", "card_1").SuggestedReply() }; List<Suggestion> suggestions2 = new List<Suggestion> { new SuggestionHelper("Card #2", "card_2").SuggestedReply() }; // Create the card content for the carousel List<CardContent> cardContents = new List<CardContent> { // Add items as card content new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, suggestions1).GetCardContent(), new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, suggestions2).GetCardContent() }; // Send the carousel to the user rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);