Korzystanie z integracji w Synology Chat

W aplikacji Synology Chat dostępne są funkcje integracji niestandardowej, które umożliwiają skonfigurowanie przychodzących i wychodzących akcji Webhook oraz polecenia ukośnika. Aby włączyć te funkcje, kliknij ikonę Zdjęcia profilowego u góry po prawej stronie i wybierz opcję Integracja.

Przychodzące akcje Webhook

Przychodząca akcja Webhook będzie umieszczać w aplikacji Chat wiadomości ze źródeł zewnętrznych. Korzysta ona z ogólnych żądań HTTP z danymi JSON, a także innych opcjonalnych ustawień.

Aby wysyłać wiadomości:

Istnieją dwa sposoby przesyłania danych do adresu URL akcji Webhook:

• ciąg JSON w postaci parametru danych w żądaniu POST request,
• ciąg JSON w postaci treści żądania POST request.

Dane JSON mogą zawierać właściwość tekstu, która zostanie dodana do przypisanego kanału. Na przykład:

payload={"text": "Pierwszy wiersz wiadomości publikowanej na kanale.\nMożliwy jest również wybór drugiej linii wiadomości."}

Aby dodać odnośniki:

Aby dodać łącze, można wprowadzić je bezpośrednio do tekstu. Na przykład:

payload={"text": "<https://www.synology.com>"}

Inny przykład:

payload={"text": "Sprawdź to!! <https://www.synology.com|Kliknij tutaj> zobacz szczegóły!"}

Aby przesłać pliki:

Ponadto można przesłać plik w postach przychodzących. Aby przesłać plik, dane JSON muszą zawierać właściwość file_url oraz opcjonalnie właściwość tekstu. Pobierzemy Twój adres URL i potraktujemy go jak jako post z plikiem użytkownika. Na przykład:

payload={"text": "zabawny obrazek", "plik_url": "http://imgur.com/xxxxx"}

Wychodzące akcje Webhook

Wychodzące akcje Webhook nasłuchują słów wyzwalających w wiadomościach Czatu. Słowa wyzwalające wyślą odpowiednie dane do zewnętrznego adresu URL. Wychodzące akcje Webhook mogą zostać wyzwolone tylko po spełnieniu jednego lub obu poniższych warunków:

• wiadomość znajduje się w określonym kanale,
• wiadomość rozpoczyna się jednym z wybranych słów wyzwalających.

Jeśli kanał został wybrany, słowa wyzwalające są opcjonalne. Słowa wyzwalające są wymagane, jeśli żaden kanał nie został wybrany. Jednak po określeniu obu warunków wychodząca akcja Webhook będzie miała miejsce tylko wtedy, gdy oba warunki zostaną spełnione równocześnie.

Dane wychodzące:

Gdy odebrana wiadomość spełnia warunki wyzwalania, POST zostanie dostarczony do przypisanego adresu URL. Pola danych są opisane poniżej:

token: token bota
channel_id
channel_name
user_id
username
post_id
timestamp
text
trigger_word: dopasowane słowo wyzwalające

Odpowiadanie:

Jeśli w kanale Czatu odpowiedzi chce udzielić zewnętrzne miejsce docelowe, JSON musi zostać zwrócony w treści tej odpowiedzi. Pola obsługiwane są takie same jak w przypadku przychodzących akcji Webhook JSON.

Polecenie ukośnika

Polecenie ukośnika umożliwia proste wyzwalanie wychodzących akcji Webhook wpisując „/” w polu tekstowym. Odpowiedzi będą widoczne tylko dla ciebie, a więc inni użytkownicy nie będą widzieć wiadomości, które ich nie dotyczą.

Aby stworzyć polecenie ukośnika:

Polecenia ukośnika można modyfikować w zakładce Integration. Dostęp do obszaru Integration można uzyskać, klikając Zdjęcie profilowe w prawym górnym rogu.

Aby skorzystać z polecenia ukośnika:

W polu tekstowym dowolnego kanału lub konwersacji wpisz „/”. Spowoduje to wyświetlenie listy komend stworzonych przez użytkownika i jego zespołów. Przykładowo, po wpisaniu „/” i wybraniu „/lunch”, akcja Webhook wyświetli rekomendowany posiłek.

Boty

Bot może rozpocząć rozmowę z Tobą, zamieszczać wiadomości wysłane ze źródeł zewnętrznych i słuchać wiadomości wysłanych przez użytkownika w rozmowie.

Aby wyłączyć użytkownikom możliwość rozpoczynania aktywnej rozmowy z Twoimi botami:

Zaznaczenie opcji Ukryj na liście botów sprawi, że użytkownicy nie będą widzieli danego bota na liście ani nie będą mogli go dodawać.

Aby wysłać dane wychodzące:

Jeśli w pole konfiguracji bota został wprowadzony wychodzący adres URL, aplikacja Chat wyśle żądanie do strony URL, gdy użytkownik wyśle wiadomość do bota. Pola danych zostały opisane poniżej:

token: token bota
user_id
username
post_id
timestamp
text

Aby wysłać wiadomości wychodzące:

Korzystając z parametru danych w żądaniu POST request, możesz przypisać odbiorców i wiadomości. Na przykład:

payload={"text": "Pierwszy wiersz wiadomości publikowanej na kanale.\nMożliwy jest również wybór drugiej linii wiadomości.", "user_ids": [5] }

Oznacza to, że wiadomość Pierwszy wiersz wiadomości publikowanej na kanale.\nMożliwy jest również wybór drugiej linii wiadomości.> została wysłana do użytkownika z identyfikatorem user_id o wartości 5.

Aby dołączyć wiadomości do wiadomości przychodzących:

Bot może podczas rozmowy wysyłać teksty i pliki, a także dołączać specjalne dane (załącznik) i obiekty interaktywne (akcja). Do interaktywnych obiektów można używać teraz przycisków. Do pola załączników w danych możesz dodać wiadomość, którą chcesz dołączyć. Na przykład:

attachments: tablica z obiektem załącznika

attachment object: {
  callback_id: ciąg[2], który odnosi się do ciągu określonego przez usługę bota. Zostanie to do Ciebie wysłane, gdy użytkownik uruchomi zdarzenie z dołączonymi danymi.
  text: ciąg tekstowy
  actions: tablica obiektu działania
}

action object: {
  type: "button"
  text: ciąg tekstowy
  name: ciąg tekstowy
  value: ciąg tekstowy
  style: ciąg tekstowy, gdzie dopuszczalne wartości to green (zielony), grey (szary), red (czerwony), orange (pomarańczowy), blue (niebieski) i teal (turkus)
}

Na przykład:

payload={"text": "Hello World", "user_ids": [3], "attachments":
[{"callback_id": "abc", "text": "attachment", "actions":
[{"type": "button", "name": "resp", "value": "ok", "text": "OK", "style": "green"}]}]}

Aby odebrać dane interaktywne uruchomione przez użytkowników:

Chat wyśle żądanie do wychodzącego adresu URL bota, gdy użytkownik uruchomi interaktywny obiekt. Pola danych są opisane poniżej:

payload = {
  "actions": tablica obiektu działania, która odnosi się do działania wywołanego przez użytkownika
  "callback_id": ciąg tekstowy, który odnosi się do identyfikatora callback_id załącznika, w którym znajduje się akcja wywołana przez użytkownika
  "post_id"
  "token"
  "user": {
  "user_id"
  "username"
  }
}

Gdy bot trzyma żądanie, może odesłać dane JSON w celu sprawdzenia oryginalnego postu. Z wyjątkiem parametru user_id obsługiwany format jest taki sam jak format parametru payload.

Na przykład:

{"text": "Użytkownik otrzymał Twoją odpowiedź!"}

Aby wyświetlić rozmowy widoczne dla bota:

Możesz wysyłać żądanie do poniższych adresów URL:
[Chat URL]/webapi/entry.cgi?api=SYNO.Chat.External&method=channel_list&version=2

i może zawierać poniższy parametr:
token = token bota

Aby wyświetlić użytkowników widocznych dla bota:

Możesz wysyłać żądanie do poniższych adresów URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=user_list&version=2

i może zawierać poniższy parametr:
token = token bota

Aby wyświetlić wiadomości widoczne dla bota

Możesz wysyłać żądanie do poniższych adresów URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_list&version=2

i może zawierać poniższe parametry:
token = token bota
channel_id = channel_id jest wykorzystywany w celach przeglądania
next_count = liczba wiadomości po poście
prev_count = liczba wiadomości przed postem, minimalna wartość to 1
(opcjonalnie)post_id = post_id jest wykorzystywany w celach przeglądania, pusty post_id odnosi się do najnowszej wiadomości

Aby pobrać dane plików:

Możesz wysyłać żądanie do poniższych adresów URL:
{Chat URL}/webapi/entry.cgi?api=SYNO.Chat.External&method=post_file_get&version=2&post_id={post id}&token="{bot token}"

i może zawierać poniższe parametry:
token = token bota
post_id = post_id jest wykorzystywany w celach przeglądania