Komponenty wiadomości

Boty dołączają do wiadomości components w formacie Discorda dokładnie tak jak na Discordzie, a kliknięcie przychodzi jako INTERACTION_CREATE ze zwykłym tokenem i callbackiem, więc biblioteki nie wymagają zmian. Ta strona opisuje, co GameVox wyświetla, jak interakcje docierają do twojej aplikacji i w czym limity różnią się od Discorda.

Co działa

Wiersze akcji (typ 1) zawierające przyciski (typ 2, style od 1 do 5) i tekstowe listy wyboru (typ 3). Przycisk-link (styl 5) otwiera swój url i nigdy nie wysyła interakcji.
Serwery w chmurze i hostowane samodzielnie. Komponenty są zapisywane razem z wiadomością i zwracane przy odczytach REST oraz w MESSAGE_CREATE / MESSAGE_UPDATE. Edycja wiadomości z components: [] je usuwa.
Każdy klient. Klient desktopowy i webowy, iOS i Android wyświetlają przyciski i tekstowe listy wyboru (najwyżej 5 wierszy po 5 elementów na wiadomość) oraz okna modalne i odpowiedzi efemeryczne.
Okna modalne (callback typu 9) i odpowiedzi efemeryczne (flags: 64), opisane niżej.

Wiadomość z wierszem przycisków i listą wyboru:

POST /api/v10/channels/{channel_id}/messages

{
  "content": "Next map?",
  "components": [
    {
      "type": 1,
      "components": [
        { "type": 2, "style": 1, "label": "Vote", "custom_id": "vote" },
        { "type": 2, "style": 5, "label": "Rules", "url": "https://example.com/rules" }
      ]
    },
    {
      "type": 1,
      "components": [
        {
          "type": 3,
          "custom_id": "map",
          "placeholder": "Pick a map",
          "options": [
            { "label": "Dust", "value": "dust" },
            { "label": "Nuke", "value": "nuke" }
          ]
        }
      ]
    }
  ]
}

Nieobsługiwane

Listy wyboru użytkowników, ról, wzmianek i kanałów (typy od 5 do 8). Są przyjmowane i zapisywane, ale klienty pokazują je jako wyłączone, więc nigdy nie wywołują interakcji.
Komponenty v2 (komponenty układu). Nie są wyświetlane.
Przyciski premium (styl 6). Są pokazywane jako wyłączone.
Wiadomości bezpośrednie. Interakcje z komponentami, okna modalne i odpowiedzi efemeryczne działają tylko na kanałach serwera.

Odbieranie kliknięcia

Kliknięcie przychodzi jako INTERACTION_CREATE z type: 3 (MESSAGE_COMPONENT) i zawiera data.custom_id, data.component_type oraz, dla listy wyboru, data.values. message to pełna kliknięta wiadomość razem z komponentami, niezależnie od intencji twojego bota. Wysłane okno modalne przychodzi jako type: 5 (MODAL_SUBMIT) z wpisanymi wartościami w data.components.

GameVox sprawdza każde kliknięcie względem zapisanej wiadomości, zanim zobaczy je twoja aplikacja: element musi nadal być w wiadomości i być włączony, wartości listy wyboru muszą należeć do jej opcji i mieścić się w min_values / max_values, a członek musi widzieć kanał. Kliknięcie trafia tylko do aplikacji, której bot opublikował wiadomość.

Interakcje są dostarczane przez połączenie twojego bota z gateway albo wysyłane metodą POST na twój Interactions Endpoint URL, jeśli go ustawisz (zobacz OAuth2). W trybie HTTP dwie rzeczy różnią się od Discorda:

Mimo to utrzymuj połączoną sesję gateway. GameVox przekazuje każdą interakcję twojej aplikacji przez tę sesję, zanim wyśle ją metodą POST na twój endpoint. Bez połączonej sesji nic nie zostanie dostarczone, a członek, który kliknie, dowie się, że aplikacja nie jest online.
Treść odpowiedzi jest ignorowana. Odpowiadaj, wywołując POST /interactions/{id}/{token}/callback; callback zwrócony w treści odpowiedzi na POST nie dociera do nikogo.

Odpowiadanie

Przez zwykły endpoint callbacku. Token interakcji jest ważny przez 15 minut.

Typ	Działanie
`4` `CHANNEL_MESSAGE_WITH_SOURCE`	Publikuje odpowiedź na kanale. Z `flags: 64` odpowiedź jest efemeryczna.
`5` `DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE`	Potwierdza od razu; pierwszy `PATCH .../messages/@original` publikuje odpowiedź. Z `flags: 64` ta odpowiedź jest efemeryczna.
`6` `DEFERRED_UPDATE_MESSAGE`	Potwierdza bez widocznej zmiany. `@original` wskazuje potem klikniętą wiadomość, więc późniejszy `PATCH .../messages/@original` ją edytuje.
`7` `UPDATE_MESSAGE`	Edytuje klikniętą wiadomość w miejscu, razem z komponentami.
`9` `MODAL`	Otwiera okno modalne dla członka, który kliknął.

Follow-upy (do 5 na interakcję, flags: 64 dla efemerycznych) oraz GET / PATCH / DELETE na @original i na wiadomościach follow-up działają jak na Discordzie. Typy 4, 5 i 9 oraz odpowiedzi efemeryczne działają też dla komend ukośnikowych; typy 6 i 7 wymagają klikniętej wiadomości.

Odpowiedzi efemeryczne

Odpowiedź efemeryczna trafia tylko do członka, który wywołał interakcję, w jego otwartych sesjach, i jest oznaczona jako widoczna tylko dla niego. Nigdy nie jest zapisywana na kanale: nie ma jej w historii wiadomości ani w MESSAGE_CREATE, znika po przeładowaniu, a twoja aplikacja może ją edytować lub usunąć przez 15 minut. Komponenty w odpowiedzi efemerycznej działają jak wszystkie inne. Tak samo jest na serwerach w chmurze i hostowanych samodzielnie.

Okna modalne

Do 5 wierszy akcji z polami tekstowymi (typ 4). Wszystko inne w oknie modalnym jest odrzucane. Styl 1 to jedna linia, styl 2 to akapit.
Tytuł i etykiety są przycinane do 45 znaków, a podpowiedzi do 100. Pole mieści do 4000 znaków. required domyślnie ma wartość true.
GameVox sprawdza wysłane dane względem otwartego okna (pola wymagane, min_length, max_length), zanim zobaczy je twoja aplikacja.
Okno modalne wygasa po 15 minutach i można je wysłać raz.

Limity

components jednej wiadomości: 64 KiB JSON na serwerach w chmurze; 128 KiB i 40 komponentów najwyższego poziomu na serwerach hostowanych samodzielnie. Większe żądanie kończy się błędem 400.
custom_id: do 100 znaków; elementu z dłuższym nie da się użyć. Listy wyboru: do 25 wartości po maksymalnie 100 znaków.
Kliknięcia: jedna interakcja z komponentem na członka i serwer co 0,7 sekundy. Serwer hostowany samodzielnie dodatkowo pozwala na najwyżej 5 kliknięć na członka w ciągu 5 sekund. Szybsze kliknięcia są odrzucane i nigdy nie docierają do twojej aplikacji.
Odpowiedzi efemeryczne i okna modalne: 120 na aplikację dla każdego członka w 15-minutowym oknie, liczone razem. Edycja istniejącej się nie liczy. Po przekroczeniu limitu żądanie kończy się błędem 429.
Treść odpowiedzi efemerycznej: do 4000 znaków.

← Powrót do dokumentacji