Wysyłanie i odbieranie komunikatów za pomocą interfejsu API łącznika bota
Usługa Bot Connector umożliwia botowi komunikację między wieloma kanałami, takimi jak Email, Slack i nie tylko. Ułatwia komunikację między botem a użytkownikiem, przekazując działania z bota do kanału i z kanału do bota. Każde działanie zawiera informacje używane do kierowania komunikatu do odpowiedniego miejsca docelowego wraz z informacjami o tym, kto utworzył wiadomość, kontekst wiadomości i odbiorcę wiadomości. W tym artykule opisano sposób używania usługi Bot Connector do wymiany działań komunikatów między botem a użytkownikiem w kanale.
Odpowiadanie na wiadomość
Tworzenie odpowiedzi
Gdy użytkownik wyśle wiadomość do bota, bot otrzyma komunikat jako obiekt Działania typu komunikat. Aby utworzyć odpowiedź na wiadomość użytkownika, utwórz nowy Activity obiekt i zacznij od ustawienia następujących właściwości:
| Właściwość | Wartość |
|---|---|
| konwersacja | Ustaw tę właściwość na zawartość conversation właściwości w komunikacie użytkownika. |
| Z | Ustaw tę właściwość na zawartość recipient właściwości w komunikacie użytkownika. |
| locale | Ustaw tę właściwość na zawartość locale właściwości w komunikacie użytkownika, jeśli została określona. |
| odbiorca | Ustaw tę właściwość na zawartość from właściwości w komunikacie użytkownika. |
| replyToId | Ustaw tę właściwość na zawartość id właściwości w komunikacie użytkownika. |
| typ | Ustaw tę właściwość na komunikat. |
Następnie ustaw właściwości, które określają informacje, które mają być przekazywane użytkownikowi. Można na przykład ustawić text właściwość , aby określić tekst, który ma być wyświetlany w komunikacie, ustawić speak właściwość , aby określić tekst, który ma być używany przez bota, i ustawić attachments właściwość, aby określić załączniki multimediów lub karty sformatowane do uwzględnienia w wiadomości. Aby uzyskać szczegółowe informacje o często używanych właściwościach komunikatów, zobacz Tworzenie komunikatów.
Wyślij odpowiedź
serviceUrl Użyj właściwości w działaniu przychodzącym, aby zidentyfikować podstawowy identyfikator URI, którego bot powinien użyć do wystawienia odpowiedzi.
Aby wysłać odpowiedź, wyślij to żądanie:
POST /v3/conversations/{conversationId}/activities/{activityId}
W tym identyfikatorze URI żądania zastąp element {conversationId} wartością właściwości obiektu id w działaniu (odpowiedź) i zastąp element {activityId} wartością replyToIdconversation właściwości w działaniu (odpowiedź). Ustaw treść żądania na utworzony obiekt Activity , aby reprezentować odpowiedź.
W poniższym przykładzie pokazano żądanie, które wysyła prostą odpowiedź tekstową tylko do wiadomości użytkownika. W tym przykładowym żądaniu https://smba.trafficmanager.net/teams reprezentuje podstawowy identyfikator URI. Podstawowy identyfikator URI dla żądań, których problemy z botem mogą się różnić. Aby uzyskać szczegółowe informacje na temat ustawiania podstawowego identyfikatora URI, zobacz Dokumentacja interfejsu API.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
Wyślij wiadomość (nieodpowiedziową)
Większość wiadomości wysyłanych przez bota będzie odpowiadać na wiadomości odbierane od użytkownika. Jednak czasami bot musi wysłać wiadomość do konwersacji, która nie jest bezpośrednią odpowiedzią na żadną wiadomość od użytkownika. Na przykład bot może wymagać rozpoczęcia nowego tematu konwersacji lub wysłania wiadomości pożegnalnej na końcu konwersacji.
Aby wysłać wiadomość do konwersacji, która nie jest bezpośrednią odpowiedzią na żadną wiadomość od użytkownika, wyślij następujące żądanie:
POST /v3/conversations/{conversationId}/activities
W tym identyfikatorze URI żądania zastąp ciąg {conversationId} identyfikatorem konwersacji.
Ustaw treść żądania na obiekt Activity utworzony w celu reprezentowania odpowiedzi.
Uwaga
Platforma Bot Framework nie nakłada żadnych ograniczeń na liczbę komunikatów, które może wysyłać bot. Jednak większość kanałów wymusza limity ograniczania przepustowości, aby uniemożliwić botom wysyłanie dużej liczby komunikatów w krótkim czasie. Ponadto jeśli bot wysyła wiele komunikatów w krótkim odstępie czasu, kanał może nie zawsze renderować komunikaty w odpowiedniej kolejności.
Rozpocznij konwersację
Czasami bot musi zainicjować konwersację z co najmniej jednym użytkownikiem. Aby rozpocząć konwersację z użytkownikiem w kanale, bot musi znać jego informacje o koncie i informacje o koncie użytkownika w tym kanale.
Porada
Jeśli bot może wymagać rozpoczęcia konwersacji z użytkownikami w przyszłości, buforuj informacje o koncie użytkownika, inne istotne informacje, takie jak preferencje użytkownika i ustawienia regionalne, oraz adres URL usługi (do użycia jako podstawowy identyfikator URI w żądaniu Rozpocznij konwersację).
Aby rozpocząć konwersację, wykonaj następujące żądanie:
POST /v3/conversations
Ustaw treść żądania na obiekt ConversationParameters , który określa informacje o koncie bota i informacje o koncie użytkowników, których chcesz uwzględnić w konwersacji.
Uwaga
Nie wszystkie kanały obsługują konwersacje grupowe. Zapoznaj się z dokumentacją kanału, aby określić, czy kanał obsługuje konwersacje grupowe i zidentyfikować maksymalną liczbę uczestników, na którą kanał zezwala w konwersacji.
W poniższym przykładzie pokazano żądanie, które rozpoczyna konwersację. W tym przykładowym żądaniu https://smba.trafficmanager.net/teams reprezentuje podstawowy identyfikator URI. Podstawowy identyfikator URI dla żądań, których problemy z botem mogą się różnić. Aby uzyskać szczegółowe informacje na temat ustawiania podstawowego identyfikatora URI, zobacz Dokumentacja interfejsu API.
POST https://smba.trafficmanager.net/teams/v3/conversations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
Jeśli konwersacja zostanie nawiązana z określonymi użytkownikami, odpowiedź będzie zawierać identyfikator identyfikujący konwersację.
{
"id": "abcd1234"
}
Bot może następnie użyć tego identyfikatora konwersacji, aby wysłać wiadomość do użytkowników w konwersacji.