Przewodnik Agent API

Twój pierwszy agent

Otwórz @agentfather i wyślij /newagent. Wybierz nazwę i unikalny nick zakończony na _agent (7–32 znaki).
Kliknij przycisk tokena w odpowiedzi. Potwierdź wydanie i zapisz go na swoim serwerze. Pojawi się raz, w osobnym oknie, nigdy w historii czatu.
Uruchom przykład Pythona na swoim serwerze i napisz do agenta. Logika i AI działają w Twojej infrastrukturze; utworzenie agenta nie uruchamia modelu.

curl https://znosin.com/api/agent/v1/me \
  -H "Authorization: Bearer $ZNOSIN_AGENT_TOKEN"

Pobierz przykład Pythona ↓

ZNOSIN_AGENT_TOKEN · Python 3.10+

Dostępne w v1

Odbieraj kliknięcia przez GET /updates?callbacks=true. Aktualizacja zawiera message albo callback. Dane przycisku pochodzą z serwera, a użytkownik to callback.from. Sprawdzaj uprawnienia we własnym systemie. Odpowiadaj przez POST /callbacks/{id}/answer z text i showAlert. Klient czeka do 10 sekund; kliknięcie wygasa po 120 sekundach. Identyczną odpowiedź można powtórzyć. Kliknięcie nie tworzy wiadomości. Webhooki i przesyłanie załączników wychodzących nie są jeszcze dostępne.

Dokumentacja API

HTTPS i JSON. Wysyłaj Authorization: Bearer <token>. Sukces zawiera ok i result, błędy ok:false i error. Czas wiadomości to milisekundy Unix. Pełne pola opisuje schemat OpenAPI.

https://znosin.com/api/agent/v1

GET /meProfil

GET /updates?offset=0&timeout=25Wiadomości

POST /messagesWyślij tekst

PATCH /messages/{id}Edytuj tekst

DELETE /messages/{id}Usuń wiadomość

GET /commands?language=plMenu poleceń

PUT /commandsZapisz polecenia

GET /files/{id}Pobierz załącznik

POST /api/agent/v1/messages

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Hello!",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee"
}

PUT /api/agent/v1/commands

{
  "language": "pl",
  "commands": [
    {
      "command": "help",
      "description": "Przewodnik Agent API"
    }
  ]
}

OpenAPI 3.1 JSON →

Polecenia i przyciski

Dodaj markup do POST /messages lub PATCH /messages/{id}: wiersze inline zawierają akcje (text, id, data), linki HTTPS (text, url) albo miniaplikacje (text, appId). Klawiatura reply wysyła zwykłe odpowiedzi do agenta. oneTime ukrywa ją po użyciu; type remove usuwa klawiaturę. Podczas edycji pomiń markup, aby zachować przyciski, lub wyślij null, aby je usunąć.

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Choose an action",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee",
  "markup": {
    "type": "inline",
    "rows": [
      [
        {
          "text": "Confirm",
          "id": "confirm",
          "data": "confirm:123"
        },
        {
          "text": "Cancel",
          "id": "cancel",
          "data": "cancel:123"
        }
      ],
      [
        {
          "text": "Website",
          "url": "https://znosin.com"
        },
        {
          "text": "Calculator",
          "appId": "calculator"
        }
      ]
    ]
  }
}

Wpisz / na czacie, aby zobaczyć polecenia. W grupie wybór kieruje polecenie do jednego agenta: /command@nickname. Menu obsługuje siedem języków. Zarejestruj do 20 poleceń na język przez PUT /commands.

/setcommands @nickname pl · @agentfather

{
  "type": "reply",
  "rows": [
    [
      "Yes",
      "No"
    ],
    [
      "Help"
    ]
  ],
  "oneTime": true
}

8 rows × 4 buttons · 64 characters/label · 256 UTF-8 bytes/data · HTTPS

Przykład z przyciskami ↓

Język użytkownika

Wiadomości przychodzące i kliknięcia przycisków zawierają from.language_code: en, ru, uk, de, fr, pl lub zh. Jest to język interfejsu nadawcy w chwili zdarzenia, także w grupach. Starsze zdarzenia, nieznane preferencje i wiadomości agentów zwracają null — wybierz język zastępczy w swoim kodzie. Wartość przetrwa restart i ponowienie żądania. Kolejne wiadomości, edycje oraz ustawienia innego urządzenia jej nie zmieniają. Przekazane wiadomości mają język osoby przekazującej, a nie autora oryginału. To preferencja klienta, nie wykrywanie języka tekstu ani podstawa nadania uprawnień. Klienci wysyłają X-Znosin-Language; obsługiwane języki z Accept-Language są źródłem zastępczym. Twój kod tłumaczy odpowiedzi i przyciski. AgentFather używa języka interfejsu; /language ru ustala język, a /language auto przywraca wybór automatyczny.

{
  "from": {
    "id": "USER_ID",
    "name": "Alex",
    "nickname": "alex",
    "language_code": "pl"
  }
}

Dostęp i prywatność

Agent nie może rozpocząć prywatnej rozmowy. Najpierw pisze człowiek; /stop blokuje wiadomości, a /start wznawia działanie od nowych wpisów. W grupach widzi tylko polecenia, np. /help lub /help@name_agent, oraz odpowiedzi na własne wiadomości po dołączeniu. Nie otrzymuje cytowanej historii, starych wiadomości, poczty, portfela ani kluczy właściciela. Usunięcie z grupy odbiera dostęp.

Niezawodne dostarczanie

Long polling czeka do 25 sekund i odpowiada po nadejściu wiadomości. Używaj jednego odbiorcy na agenta i zapisuj nextOffset również przy pustym wyniku. Ponawiaj wysyłkę z tym samym clientId i treścią. Kolejka przechowuje do 10 000 wpisów przez maksymalnie 24 godziny; reset oznacza wygaśnięcie lub przepełnienie. Limity: 180 żądań/min, 60 wysyłek/min na agenta, 30 na czat. Respektuj Retry-After przy 429 i 503; zwiększaj odstępy przy błędach sieci.

Zarządzanie agentem

Polecenia @agentfather: /myagents, /token @nick, /disable @nick, /enable @nick, /setname @nick Nazwa i /setdescription @nick Opis. Rotacja natychmiast unieważnia stary token. Wyłączenie unieważnia token i czyści kolejkę. Po włączeniu wydaj nowy token. /language en|ru|uk|de|fr|pl|zh wybiera język, /language auto używa języka interfejsu. Do 20 agentów na właściciela.

Podłącz model AI

Zastąp echo wywołaniem modelu na swoim serwerze. Poinformuj użytkowników o danych wysyłanych dostawcy modelu. Traktuj wiadomości i pliki jako niezaufane dane, ogranicz uprawnienia narzędzi i wymagaj potwierdzenia ważnych działań. Nie umieszczaj tokenów Znosin ani kluczy modelu w promptach ani kodzie klienta.

Agenci w Twoich rozmowach