Agenci RCS dla firm 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 RCS Business Messaging API. Pojedyncze żądanie może zawierać tekst, karty z elementami multimedialnymi, pliki multimedialne i PDF, sugerowane odpowiedzi i sugerowane działania.
Platforma RCS dla firm zwraca błędy w określonych sytuacjach, aby ułatwić Ci 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 tej funkcji, platforma RCS dla firm zwróci błąd 404 NOT_FOUND. W takim przypadku możesz spróbować skontaktować się z użytkownikiem za pomocą metod rezerwowych 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, która nie włączyła ruchu RCS, platforma RCS dla firm 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 dla firm zwróci błąd 400 INVALID_ARGUMENT i nie dostarczy wiadomości.
W ramach strategii wysyłania wiadomości wielokanałowych najlepiej wycofać wiadomości, które nie zostały dostarczone po upływie rozsądnego czasu, i wysłać je innym kanałem. Aby automatycznie wycofywać wiadomości o określonej godzinie, ustaw datę wygaśnięcia wiadomości.
Adresat jest offline
Platforma RCS dla firm nadal akceptuje wiadomość do dostarczenia, jeśli odbiorca jest offline. Otrzymasz odpowiedź 200 OK, a platforma RCS dla firm przechowuje wiadomość i będzie próbować ponownie ją dostarczyć przez 30 dni. Nie musisz prosić RCS dla firm o ponowne wysłanie wiadomości.
RCS dla firm usuwa wszystkie niedostarczone wiadomości po 30 dniach od ich przesłania.
W zależności od przypadku użycia agenta możesz wycofać niedostarczoną wiadomość przed upływem 30-dniowego limitu czasu. Cofnięcie może uniemożliwić użytkownikom offline otrzymanie nieaktualnej wiadomości po powrocie do trybu online. Wiadomość możesz wycofać na kilka sposobów:
- Wyślij prośbę o unieważnienie, aby je zainicjować.
- Ustaw datę ważności wiadomości, aby automatycznie cofnąć wiadomość w odpowiednim czasie.
Ustawianie daty ważności wiadomości
Czy wiadomość agenta jest pilna? Na przykład hasła jednorazowe są ważne tylko przez krótki czas. Oferty ograniczone czasowo wygasają. Przypomnienia o spotkaniach nie są przydatne po dacie spotkania. Aby wiadomości były aktualne i trafne, ustaw ich datę wygaśnięcia. Może to zapobiec otrzymywaniu przez użytkowników offline treści nieaktualnych po ponownym połączeniu z internetem. Wygaśnięcie to też dobry sygnał do wywołania strategii wysyłania wiadomości zastępczych, aby użytkownicy otrzymywali potrzebne informacje na czas.
Aby ustawić wygaśnięcie wiadomości, w wiadomości agenta podaj jedno z tych pól:
expireTime: dokładny czas wygaśnięcia wiadomości w strefie czasowej UTC.ttl(czas życia danych): czas, po którym wiadomość wygasa.
Opcje formatowania i wartości znajdziesz w sekcji AgentMessage.
Maksymalna wartość dla ttl i expireTime to 15 dni od przesłania wiadomości.
Chociaż nie ma wartości minimalnej ttl i expireTime, zalecamy odczekanie co najmniej 10 sekund od przesłania wiadomości, aby znacznie zmniejszyć prawdopodobieństwo otrzymania powiadomienia o wycofaniu i dostarczeniu.
Czas życia wiadomości (TTL)
Ustawiając TTL dla wiadomości RCS dla firm, określasz, jak długo wiadomość powinna być uznawana za ważną i dostarczalną. Jeśli wiadomość nie zostanie dostarczona na urządzenie użytkownika w tym okresie TTL, platforma RCS dla firm automatycznie spróbuje ją wycofać.
Gdy inicjujesz wycofanie wiadomości, wysyłasz do platformy RCS dla firm prośbę o zaprzestanie prób dostarczenia tej konkretnej wiadomości. Ta czynność ma jednak wpływ tylko na przyszłe próby dostarczenia. Jeśli urządzenie użytkownika pobrało już wiadomość, jest ona przetwarzana, a platforma RCS Business Messaging nie może cofnąć dostępu do niej na urządzeniu użytkownika.
Oto czego możesz się spodziewać w przypadku powiadomień:
Wiadomość dostarczona w okresie TTL: jeśli urządzenie użytkownika przejdzie w tryb online i otrzyma wiadomość przed upływem okresu TTL, otrzymasz powiadomienie
DELIVERED. Nie wyślemy powiadomienia o odwołaniu, ponieważ wiadomość została dostarczona. Jest to najbardziej typowy i oczekiwany scenariusz.Wiadomość nie została dostarczona przed upływem czasu TTL: jeśli czas TTL upłynie, zanim wiadomość dotrze na urządzenie użytkownika (np. urządzenie jest offline), platforma RCS dla firm spróbuje wycofać wiadomość. Otrzymasz powiadomienie
TTL_EXPIRATION_REVOKEDinformujące o tym, że wiadomość została usunięta z kolejki dostarczania. W takim przypadku użytkownik nie otrzyma wiadomości.
Zalecenia dotyczące obsługi przypadków brzegowych
Nasz system przetwarza dostarczanie wiadomości RCS dla firm i wygaśnięcie czasu życia równolegle. Z tego powodu w bardzo rzadkich przypadkach możesz zauważyć nietypowe sytuacje, w których czas wyświetlania powiadomień jest nieoczekiwany. Możesz na przykład otrzymać powiadomienie o dostarczeniu i o TTL lub nie otrzymać żadnego z nich.
Oto nasze zalecenia dotyczące obsługi powiadomień o wiadomościach do firm w RCS dla firm:
DELIVEREDpowiadomienie: jeśli otrzymasz powiadomienieDELIVEREDo wiadomości, oznacza to, że wiadomość dotarła do użytkownika. Możesz bezpiecznie zignorować wszelkie kolejne powiadomienia o TTL dotyczące tej konkretnej wiadomości.Powiadomienie
TTL_EXPIRATION_REVOKED: jeśli otrzymasz powiadomienie TTL ze stanemTTL_EXPIRATION_REVOKED, oznacza to, że system RCS dla firm przestaje próbować dostarczyć tę konkretną wiadomość. Potraktuj tę wiadomość jako niedostarczoną i w razie potrzeby zastosuj strategię rezerwową.Powiadomienie TTL z dowolnym innym stanem: jeśli otrzymasz powiadomienie TTL z dowolnym innym stanem, oznacza to niejednoznaczną próbę unieważnienia.
- W przypadku ważnych wiadomości, takich jak hasła jednorazowe (OTP), uruchom metodę rezerwową.
- W przypadku wiadomości o mniejszym znaczeniu zdecyduj, czy chcesz zainicjować przełączenie awaryjne.
- Brak powiadomień: w rzadkich przypadkach system może nie wysłać powiadomienia TTL, a klient może nie wygenerować powiadomienia o dostarczeniu. To bardzo rzadki przypadek.
Ustawianie typu ruchu wiadomości
Interfejs RBM API zawiera pole messageTrafficType, które służy do kategoryzowania wiadomości.
Chociaż przypadki użycia agenta nadal określają zachowanie agenta i to, które reguły biznesowe mają zastosowanie, messageTrafficType umożliwia bardziej szczegółowe kategoryzowanie treści wiadomości. Dzięki temu jeden agent może obsługiwać wiele przypadków użycia. Obecnie nie ma to wpływu na dotychczasowe przypadki użycia agentów ani reguły biznesowe.
To pole jest opcjonalne, ale zalecamy jego ustawienie już teraz, aby uniknąć błędu, gdy stanie się wymagane.
Aby ustawić typ ruchu wiadomości, przypisz odpowiedni messageTrafficType do każdej wiadomości na podstawie jej treści. RCS dla firm obsługuje te typy ruchu:
| Typ ruchu | Treść wiadomości | Przypadek użycia agenta |
|---|---|---|
AUTHENTICATION |
w przypadku wiadomości uwierzytelniających. | Hasło jednorazowe |
TRANSACTION |
Wiadomości dotyczące istniejących usług lub produktów użytkownika. Na przykład potwierdzenia, pokwitowania płatności lub szczegóły rezerwacji. | Transakcyjne lub wielokrotnego użycia |
PROMOTION |
W przypadku wiadomości promocyjnych, takich jak oferty, rabaty, ogłoszenia lub inne treści promocyjne. | Promocyjne lub wielokrotnego użycia |
SERVICEREQUEST |
Wiadomości dotyczące usług, o które użytkownik wyraźnie poprosił. | Hasło jednorazowe, transakcyjne, promocyjne lub wielokrotnego użytku |
ACKNOWLEDGEMENT |
W przypadku wiadomości używanych do potwierdzania działania użytkownika, a w szczególności prośby o anulowanie subskrypcji. Jest to potwierdzenie, że otrzymaliśmy prośbę użytkownika i ją przetwarzamy. | Hasło jednorazowe, transakcyjne, promocyjne lub wielokrotnego użytku |
Jeśli nie ustawisz typu ruchu, system przypisze domyślny typ dla przypadku użycia agenta.
| Przypadek użycia agenta | Domyślny typ ruchu |
|---|---|
| OTP | AUTHENTICATION |
| Transakcyjne | TRANSACTION |
| Promocyjne | PROMOTION |
| Wielofunkcyjne | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Agenci wielofunkcyjni nie mają domyślnego typu ruchu. W przypadku każdej wiadomości musisz wyraźnie określić typ ruchu na podstawie jej treści. Jeśli nie zastąpisz wartości MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, wystąpi błąd.
Limity rozmiaru wiadomości
Maksymalny rozmiar całego ciągu znaków AgentMessage to 250 KB. Część tekstowa wiadomości 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 pomocą RCS dla firm, wynosi 100 MiB, a łączny rozmiar wszystkich załączników multimedialnych i PDF w jednej wiadomości RCS dla firm nie może przekraczać 100 MiB. (1 MiB = 1 048 576 bajtów). Więcej informacji znajdziesz w sekcji Pliki multimedialne i PDF.
Tekst
Najprostsze wiadomości składają się z tekstu. Wiadomości tekstowe najlepiej nadają się do przekazywania informacji bez potrzeby używania elementów wizualnych, złożonych interakcji czy odpowiedzi.
Przykład
Poniższy kod wysyła wiadomość w formacie zwykłego tekstu. Opcje formatowania i wartości znajdziesz w phones.agentMessages.create.
cURL
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); });
Java
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(); }
Python
# 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", );
Treść wiadomości podstawowej – konwersja SMS-ów
Operatorzy wprowadzili modele rozliczeń, aby wspierać przejście z wiadomości SMS na RCS dla firm. Wiadomość RCS dla firm zawierająca maksymalnie 160 znaków UTF-8 nazywana jest wiadomością podstawową.
Podczas tworzenia prośby o wysłanie wiadomości podstawowej pamiętaj, że znaki są liczone jako 1 bajt (UTF-8). Jeśli wyślesz wiadomość zawierającą znaki specjalne, takie jak emoji lub wielobajtowy zestaw znaków, każdy znak będzie liczyć się jako 2–4 znaki UTF-8 lub więcej.
Wpisz w polu tekst, aby sprawdzić jego długość:
treść wiadomości tekstowej i podgląd linków;
Klienci RCS mogą implementować podgląd linków. Jeśli wiadomość RCS dla firm zawierająca tylko tekst zawiera adres URL witryny z tagami Open Graph, klient może wygenerować podgląd (obraz, tytuł itp.), co zapewnia lepsze wrażenia. Na przykład zobacz podstawową wiadomość z podglądem adresu URL.
Pamiętaj, że klient RCS może umożliwiać użytkownikowi wyłączenie podglądów linków.
Hasła jednorazowe do weryfikacji użytkowników
Za pomocą RCS dla firm możesz wysyłać jednorazowe hasła (OTP) do automatycznej weryfikacji użytkowników za pomocą interfejsu SMS Retriever API. Nie ma specjalnego interfejsu API do odczytywania kodów OTP, które przychodzą w ramach RCS dla firm.
Jak to działa w przypadku Androida
W przypadku aplikacji na Androida zarejestrowanych w interfejsie SMS Retriever API interfejs API nasłuchuje prawidłowo sformatowanych wiadomości RCS dla firm. Wiadomość musi zawierać zarówno kod OTP, jak i unikalny hash identyfikujący Twoją aplikację.
Gdy wiadomość RCS dla firm zostanie odebrana w prawidłowym formacie, interfejs SMS Retriever przetworzy ją tak samo jak SMS-a z kodem OTP. Gdy skrót zostanie dopasowany do aplikacji, kod OTP zostanie wyodrębniony i przekazany do aplikacji w celu automatycznej weryfikacji użytkownika.
- Przykładowa wiadomość tekstowa RCS dla firm do weryfikacji użytkownika:
Your code is <OTP><app hash>. - Przykład:
Your code is 123456 M8tue43FGT.
Więcej informacji o SMS Retriever i powiązanych interfejsach API znajdziesz w dokumentacji SMS Retriever. Szczegółowe informacje o automatycznej weryfikacji użytkowników w aplikacjach zarejestrowanych w interfejsie SMS Retriever API znajdziesz na tym schemacie.
Jak to działa w przypadku iOS
W przypadku iOS wbudowana w system obsługa haseł jednorazowych automatycznie wykrywa i sugeruje hasła jednorazowe RCS dla firm do automatycznego wypełniania, tak samo jak w przypadku haseł jednorazowych SMS. Aby aplikacja na iOS mogła odczytać kod OTP, nie jest wymagana żadna specjalna integracja z interfejsem API.
Pliki multimedialne i PDF
Gdy wysyłasz wiadomość z obrazem, filmem, plikiem audio lub PDF, Twój agent musi podać publicznie dostępny adres URL treści lub bezpośrednio przesłać plik.
Maksymalny rozmiar pliku, który można wysłać, to 100 MiB, a łączny rozmiar wszystkich załączników z multimediami i plikami PDF w jednej wiadomości nie może przekraczać 100 MiB.
Specyfikacja miniatur
W przypadku plików multimedialnych możesz też określić miniaturę, która umożliwi użytkownikom wyświetlenie podglądu treści przed kliknięciem. W przypadku plików audio jako symbol zastępczy używany jest domyślny widżet audio.
- Maksymalny rozmiar pliku miniatury to 100 KB. Aby zapewnić optymalną wygodę użytkowników, zalecamy, aby rozmiar pliku nie przekraczał 50 KB.
- Współczynnik proporcji miniatury powinien być zgodny ze współczynnikiem proporcji oryginalnego pliku.
Buforowanie i zarządzanie adresami URL
Platforma RCS dla firm buforuje pliki przez 60 dni, a interfejs API zwraca identyfikator pliku, który agent może uwzględnić w wiadomościach do użytkowników. Po 60 dniach RCS Business usuwa pliki z pamięci podręcznej.
Podczas określania plików za pomocą adresu URL sprawdzoną metodą jest ustawienie wartości contentMessage.forceRefresh na false. Ustawienie wartości contentMessage.forceRefresh na true wymusza pobieranie przez RCS dla firm nowych treści z określonego adresu URL, nawet jeśli treść adresu URL jest zapisana w pamięci podręcznej. Wydłuża to czas dostarczania wiadomości do użytkowników.
Przykład adresu URL pliku
Poniższy kod wysyła obraz. Opcje formatowania i wartości znajdziesz w sekcji
AgentContentMessage.
cURL
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); });
Java
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(); }
Python
# 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");
Możesz też przesłać multimedia przed wysłaniem ich w wiadomości za pomocą 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. Opcje formatowania i wartości znajdziesz w sekcjach files.create i AgentContentMessage.
cURL
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 multimediów
RCS dla firm obsługuje te 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 | Współpraca z kartami informacyjnymi |
|---|---|---|---|
| application/ogg | Dźwięk OGG | .ogx | Nie |
| application/pdf | Tak (tylko w przypadku Wiadomości Google w Indiach) | ||
| audio/aac | Dźwięk AAC | .aac | Nie |
| audio/mp3 | format dźwięku MP3 | .mp3 | Nie |
| audio/mpeg | MPEG audio | .mpeg | Nie |
| audio/mpg | MPG; | .mp3 | Nie |
| audio/mp4 | MP4 audio | .mp4 | Nie |
| audio/mp4-latm | MP4-latm audio | .mp4 | Nie |
| audio/3gpp | Dźwięk 3GPP | .3gp | Nie |
| image/jpeg | JPEG | .jpeg, .jpg | Tak |
| image/gif | GIF | .gif | Tak |
| image/png | PNG | .png | Tak |
| video/h263 | Film H263 | .h263 | Tak |
| video/m4v | Film M4V | .m4v | Tak |
| video/mp4 | Film MP4 | .mp4 | Tak |
| video/mpeg4 | Film MPEG-4 | .mp4, .m4p | Tak |
| video/mpeg | Film MPEG | .mpeg | Tak |
| video/webm | Film WEBM | .webm | Tak |
Sugestie
Agent wysyła sugestie (sugerowane odpowiedzi i sugerowane działania) w listach elementów z sugestiami (maksymalnie 11 sugestii) lub w kartach informacyjnych (maksymalnie 4 sugestie).
Każda sugestia może mieć maksymalnie 25 znaków.
Sugerowane odpowiedzi
Sugerowane odpowiedzi prowadzą użytkowników przez rozmowy, dostarczają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. Ładunek może mieć maksymalnie 2048 znaków.
Przykład
Poniższy kod wysyła tekst z 2 sugerowanymi odpowiedziami. Opcje formatowania i wartości znajdziesz w sekcji SuggestedReply.
cURL
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); });
Java
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(); }
Python
# 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 urządzeń. Agent może sugerować użytkownikom wybieranie numeru, otwieranie lokalizacji na mapie, udostępnianie lokalizacji, otwieranie adresu URL lub tworzenie wydarzenia w kalendarzu.
W przypadku każdego sugerowanego działania możesz opcjonalnie podać zastępczy adres URL (maksymalnie 2048 znaków). Ten URL otworzy się w nowym oknie przeglądarki, jeśli urządzenie użytkownika nie obsługuje sugerowanego działania.
Gdy użytkownik kliknie sugerowane działanie, Twój agent otrzyma zdarzenie zawierające dane zwrotne działania.
Opcje formatowania i wartości znajdziesz w sekcji SuggestedAction.
Wybierz numer
Działanie Dial (Wybierz numer) pomaga użytkownikowi wybrać numer telefonu określony przez agenta.
Numery telefonów mogą zawierać tylko cyfry (0-9), znak plusa (+), gwiazdkę (*) i znak numeru (#). Obsługiwany jest format międzynarodowy E.164 (np. +14155555555), ale nie jest on wymagany. Oznacza to, że prawidłowe są zarówno wpisy +14155555555, jak i 1011.
Przykład
Poniższy kod wysyła działanie wybierania numeru. Opcje formatowania i wartości znajdziesz w sekcji
DialAction.
cURL
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); });
Java
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(); }
Python
# 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świetlanie lokalizacji
Działanie Wyświetl lokalizację wyświetla lokalizację w domyślnej aplikacji do map użytkownika. Lokalizację możesz określić za pomocą szerokości i długości geograficznej lub zapytania opartego na bieżącej lokalizacji użytkownika. Możesz też ustawić etykietę własną pinezki, która będzie wyświetlana w aplikacji Mapy.
Przykład
Poniższy kod wysyła działanie „Wyświetl lokalizację”. Opcje formatowania i wartości znajdziesz w ViewLocationAction.
cURL
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); });
Java
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(); }
Python
# 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ępnianie lokalizacji
Działanie Udostępnij lokalizację umożliwia użytkownikowi udostępnienie lokalizacji agentowi. Użytkownik może udostępnić bieżącą lokalizację lub lokalizację wybraną ręcznie w aplikacji Mapy.
Przykład
Poniższy kod wysyła działanie udostępniania lokalizacji. Opcje formatowania i wartości znajdziesz w ShareLocationAction.
cURL
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); });
Java
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(); }
Python
# 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 );
Otwieranie adresu URL
Działanie Otwórz adres URL umożliwia kierowanie użytkowników na stronę internetową wskazaną przez agenta. Domyślnie strona internetowa otwiera się w przeglądarce użytkownika. Możesz też ustawić otwieranie strony w widoku internetowym. Więcej informacji znajdziesz w sekcji Otwieranie adresu URL za pomocą widoku internetowego.
Tylko w Wiadomościach Google
Wyświetlanie podstawowego adresu URL: aby zwiększyć przejrzystość w przypadku wiadomości A2P, Wiadomości Google wyświetlają podstawowy adres URL w sugerowanych działaniach „Otwórz adres URL”. Ta zmiana dotyczy sugerowanych działań na standardowych kartach informacyjnych i karuzelach kart informacyjnych.
Wyświetlanie ikony aplikacji w przypadku linków internetowych: jeśli użytkownik ma skonfigurowaną domyślną aplikację dla strony internetowej, otwiera się ona zamiast przeglądarki lub komponentu WebView, a przycisk sugestii wyświetla ikonę aplikacji. Aby ikona aplikacji wyświetlała się w Wiadomościach Google, musisz podać pełny, bezpośredni adres URL. Jeśli używasz skróconego adresu URL, zamiast niego wyświetla się domyślna ikona Otwórz URL.
Przykład
Ten kod wysyła działanie otwierania adresu URL. Opcje formatowania i wartości znajdziesz w sekcji OpenUrlAction.
cURL
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); });
Java
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(); }
Python
# 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 );
Otwieranie adresu URL w widoku internetowym
Działanie Otwórz adres URL w widoku internetowym wczytuje określoną stronę internetową w aplikacji do obsługi wiadomości za pomocą silnika renderowania domyślnej przeglądarki. Umożliwia to użytkownikowi interakcję ze stroną internetową bez opuszczania rozmowy RCS dla firm. Jeśli urządzenie użytkownika nie obsługuje widoków internetowych, strona internetowa otworzy się w przeglądarce użytkownika. Aby włączyć widoki internetowe, zapoznaj się z tym artykułem: OpenURLApplication
Widoki internetowe mają 3 tryby wyświetlania. Opcje formatowania i wartości znajdziesz w sekcji
WebviewViewMode.
- Pełny: strona internetowa zajmuje cały ekran.
- Połowa: strona internetowa zajmuje połowę ekranu.
- Wysoki: strona internetowa zajmuje trzy czwarte ekranu.
Przykład
Poniższy kod wysyła działanie „Otwórz URL z widokiem WebView”. Opcje formatowania i wartości znajdziesz w sekcji OpenURLAction.
cURL
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" } } } ] } }'
Java
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; }
Tworzenie wydarzenia w kalendarzu
Działanie 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. Może mieć maksymalnie 100 znaków. Opis wydarzenia w kalendarzu jest opcjonalny i może mieć maksymalnie 500 znaków.
Przykład
Poniższy kod wysyła działanie tworzenia wydarzenia w kalendarzu. Opcje formatowania i wartości znajdziesz w sekcji CreateCalendarEventAction.
cURL
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); });
Java
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(); }
Python
# 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 elementów z sugestiami
Agent wysyła listy elementów z sugestiami w wiadomościach, aby kierować dalszymi działaniami użytkowników. Lista elementów jest wyświetlana tylko wtedy, gdy powiązana z nią wiadomość znajduje się u dołu rozmowy. Wszystkie kolejne wiadomości w rozmowie (od użytkownika lub agenta) zastępują listę elementów.
Elementy na liście to sugerowane odpowiedzi i sugerowane działania.
Listy z elementami do kliknięcia zawierają maksymalnie 11 elementów, a każda etykieta elementu może mieć maksymalnie 25 znaków.
Opcje formatowania i wartości znajdziesz w sekcji AgentContentMessage.
Karty informacyjne
Karty z elementami multimedialnymi łączą multimedia, tekst i interaktywne sugestie w jednej wiadomości. Są one idealne do prezentowania powiązanych informacji (np. produktu ze zdjęciem, nazwą i ceną) oraz kierowania użytkowników za pomocą jasnych sugestii dotyczących kolejnego kroku, takich jak „Wyświetl szczegóły”.
Karta informacyjna może zawierać:
- Multimedia (obraz, GIF lub film)
- Tekst tytułu
- Tekst opisu
- Sugerowane odpowiedzi i sugerowane działania (maksymalnie 4)
Każde z tych pól jest opcjonalne, ale co najmniej jedno z pól 1–3 musi być uwzględnione w karcie z elementami rozszerzonymi.
Wiele kart można wysyłać razem w przewijanej w poziomie karuzeli.
Pamiętaj, że łączny ładunek karty informacyjnej to 250 KB.
Szczegółowe informacje techniczne znajdziesz w dokumentacji kart z elementami rozszerzonymi.
Wysokość karty
Karty informacyjne rozwijają się w pionie, aby dopasować się do zawartości. Mają minimalną wysokość 112 DP i maksymalną wysokość 344 DP. Jeśli zawartość karty nie jest wystarczająco duża, aby wypełnić minimalną wysokość karty, karta rozszerza się i wypełnia dodatkową wysokość białym miejscem.
Media w kartach z elementami multimedialnymi muszą mieć jedną z 3 wysokości:
- Krótki: 112 DP
- Średnia: 168 DP
- Wysoki: 264 DP
Jeśli multimedia nie mieszczą się w wymiarach karty przy wybranej wysokości, podgląd multimediów jest wybierany przez powiększenie i przycięcie multimediów.
Przykład
Poniższy kod wysyła kartę informacyjną z obrazem i sugerowanymi odpowiedziami. Opcje formatowania i wartości znajdziesz w sekcji RichCard.
cURL
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); });
Java
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(); }
Python
# 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");
Karuzela kart informacyjnych
Karuzela łączy kilka kart z elementami rozszerzonymi, dzięki czemu użytkownicy mogą porównywać produkty i reagować na każdy z nich osobno.
Karuzela może zawierać od 2 do 10 kart z elementami multimedialnymi. Karty informacyjne w karuzelach muszą spełniać ogólne wymagania dotyczące treści i wysokości, które opisano w dokumentacji kart informacyjnych. Więcej informacji o układzie i specyfikacjach karuzeli znajdziesz w dokumentacji karuzeli.
Przykład
Poniższy kod wysyła karuzelę kart informacyjnych. Opcje formatowania i wartości znajdziesz w sekcji RichCard.
cURL
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); });
Java
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(); }
Python
# 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);