---
title: Powiadomienia Direct – osobiste klucze API do natychmiastowych alertów
sidebarTitle: Direct
description: Wysyłaj powiadomienia wprost, używając osobistego klucza API – bez konfigurowania kanału. Twórz klucze Direct i wyzwalaj alerty z tytułem, treścią i odnośnikiem.
---

# Powiadomienia Direct

Powiadomienia Direct pozwalają wysyłać osobiste alerty przez prosty adres URL webhooka — bez konfigurowania kanału, bez szablonów, bez subskrybentów. Wystarczy utworzyć klucz, wywołać adres URL i natychmiast dostać powiadomienie na urządzenie.

## Czym jest Direct?

Kanały świetnie sprawdzają się przy uporządkowanych powiadomieniach opartych na szablonach, którymi można się dzielić z innymi. Czasem jednak chcesz po prostu szybkiego, osobistego powiadomienia — build się skończył, skrypt się wykonał, czujnik zadziałał. Direct powstał właśnie do tego.

W Direct dostajesz osobisty klucz API przypisany do unikalnego adresu URL webhooka. Gdy wywołasz ten adres z tytułem i treścią, powiadomienie trafi bezpośrednio do Ciebie. Konfigurowanie kanału jest zbędne.

### Kiedy wybrać Direct, a kiedy kanały

| | Direct | Kanały |
|---|---|---|
| **Konfiguracja** | Utwórz klucz, użyj adresu URL | Utwórz kanał, skonfiguruj szablony |
| **Odbiorcy** | Tylko Ty | Każdy, kto subskrybuje |
| **Szablony** | Brak — tytuł i treść podajesz w każdym żądaniu | Konfigurowalne szablony ze zmiennymi |
| **Warunki** | Brak | Obsługa dostarczania warunkowego |
| **Najlepsze do** | Osobistych skryptów, szybkich alertów, automatyzacji | Współdzielonych alertów, uporządkowanych procesów |

## Pierwsze kroki

### 1. Utwórz klucz Direct

W aplikacji Echobell dotknij **Direct** na górze listy kanałów. Następnie dotknij **Utwórz**, aby wygenerować nowy klucz Direct. Nadaj mu opisową nazwę (np. „Build Server”, „Home Lab”, „Trading Bot”).

### 2. Skopiuj adres URL webhooka

Każdy klucz Direct ma unikalny adres URL webhooka w tym formacie:

```
https://hook.echobell.one/d/{your-key-token}
```

Adres znajdziesz i skopiujesz w widoku szczegółów klucza Direct w aplikacji. Ze względów bezpieczeństwa token jest domyślnie ukryty — dotknij, aby go pokazać.

### 3. Wyślij powiadomienie

Wywołaj adres URL webhooka z ciałem JSON zawierającym pola `title` i `body`:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}
```

To wszystko — powiadomienie otrzymasz natychmiast.

## Wysyłanie żądań

### Żądanie POST (zalecane)

Wyślij ciało JSON z treścią powiadomienia:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}
```

### Żądanie GET

Parametry możesz też przekazać w ciągu zapytania:

```http
GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25
```

### Tylko POST

Każdy klucz Direct ma własne ustawienie **Tylko POST** w aplikacji Echobell. Domyślnie jest wyłączone.

Gdy jest włączone, klucz może wyzwolić wyłącznie metoda `POST`. Żądanie `GET` na jego adres URL webhooka zostaje odrzucone z kodem `405 Method Not Allowed` i nie wysyła żadnego powiadomienia:

```json
{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}
```

Żądania `HEAD` działają bez zmian — odpowiadają kodem `200` i nigdy nie wyzwalają powiadomienia, niezależnie od tego, czy Tylko POST jest włączone, czy nie.

Ustawienie działa osobno dla każdego klucza, więc możesz trzymać jeden klucz przyjazny dla `GET` do jednolinijkowców w powłoce, a drugi tylko dla POST do adresów wklejanych na czacie czy stronach wiki.

### Pola żądania

We wszystkich nazwach pól **wielkość liter nie ma znaczenia** — `title`, `Title` i `TITLE` są traktowane tak samo, niezależnie od tego, czy przekazujesz je w ciele JSON, czy w ciągu zapytania.

| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
| `title` | string | Nie | Tytuł powiadomienia. W razie pominięcia domyślnie „Direct Notification”. |
| `body` | string | Nie | Treść powiadomienia. |
| `externalLink` | string | Nie | Klikalny odnośnik pokazywany we wpisie powiadomienia. |
| `notificationType` | string | Nie | Poziom pilności powiadomienia. Przyjmuje `active`, `time-sensitive` lub `calling`. Domyślnie `active`. Zobacz [Typy powiadomień](#typy-powiadomień). |

### Typy powiadomień

Poziom pilności powiadomień Direct kontrolujesz polem `notificationType`:

| Typ | Opis |
|---|---|
| `active` | Standardowe powiadomienie, dostarczane w zwykły sposób. To ustawienie domyślne. |
| `time-sensitive` | Powiadomienie o wysokim priorytecie, które potrafi przebić się przez tryby Skupienia. |
| `calling` | Alert w formie połączenia na sytuacje krytyczne. **Wymaga aktywnej subskrypcji premium.** Bez premium działa jak `time-sensitive`. |

Przykład z typem powiadomienia:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}
```

## Format odpowiedzi

Udane żądanie zwraca:

```json
{
  "success": true,
  "message": "Notification triggered successfully."
}
```

Jeśli klucz jest nieprawidłowy lub nie został znaleziony (zwróć uwagę, że nadal zwracany jest kod HTTP `200`):

```json
{
  "success": false,
  "message": "Direct key not found."
}
```

## Zarządzanie kluczami Direct

### Wiele kluczy

Możesz utworzyć wiele kluczy Direct do różnych celów:

- **„CI Server”** — do powiadomień o buildach i wdrożeniach
- **„Home Automation”** — do alertów z czujników IoT
- **„Cron Jobs”** — do wyników zadań zaplanowanych
- **„Trading Bot”** — do alertów rynkowych

Każdy klucz ma własny, niezależny adres URL webhooka. Wpisy powiadomień są automatycznie powiązane z kluczem, który je wyzwolił, więc łatwo rozpoznasz, która usługa wysłała dane powiadomienie.

### Reset tokenu

Jeśli adres URL webhooka danego klucza wyciekł, możesz zresetować token w widoku szczegółów klucza. Powstanie wtedy nowy adres URL, a stary natychmiast przestanie działać. Zaktualizuj wszystkie skrypty i usługi korzystające ze starego adresu.

### Usuwanie klucza

Usunięcie klucza Direct trwale unieważnia jego adres URL webhooka. Wszystkie żądania na stary adres zakończą się niepowodzeniem.

## Typowe zastosowania

### Skrypty powłoki

```bash
# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'
```

### Zadania cron

```bash
# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'
```

### Python

```python
import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)
```

### Node.js

```javascript
await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});
```

### GitHub Actions

```yaml
- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'
```

## Dobre praktyki

### Bezpieczeństwo

- **Traktuj adresy URL kluczy Direct jak sekrety** — każdy, kto ma adres, może wysyłać Ci powiadomienia
- **Używaj zmiennych środowiskowych** do przechowywania tokenów kluczy w skryptach i CI/CD
- **Resetuj tokeny** natychmiast, gdy podejrzewasz, że klucz wyciekł
- **Twórz osobne klucze** dla różnych usług, aby móc unieważniać je pojedynczo

### Organizacja

- **Nadawaj kluczom opisowe nazwy** — podziękujesz sobie, gdy będziesz zarządzać kilkoma naraz
- **Używaj jednego klucza na usługę** — łatwiej wtedy rozpoznać źródło powiadomienia i odebrać dostęp
- **Usuwaj nieużywane klucze** — zmniejszysz powierzchnię ataku

### Obsługa błędów

Integrując Direct ze swoimi skryptami, opieraj logikę na polu `success` w JSON-ie, a nie na statusie HTTP:

- **200 OK**: żądanie zostało odebrane. Sprawdź ciało JSON: `success: true` oznacza, że powiadomienie zostało wyzwolone, a `success: false`, że nie. Nieznany lub zresetowany klucz Direct zwraca HTTP `200` z `{ "success": false, "message": "Direct key not found." }` — to **nie** jest `404`.
- **400 Bad Request**: token klucza ma nieprawidłową długość. Popraw adres URL.
- **405 Method Not Allowed**: klucz ma włączone [Tylko POST](#tylko-post), a żądanie nie było metodą `POST`. Przestaw wywołanie na `POST` albo wyłącz to ustawienie.

Echobell nie ogranicza liczby wywołań Direct, więc odpowiedź `429` nie występuje.

## Prywatność i bezpieczeństwo

### Co jest przechowywane

- **Na naszych serwerach**:
  - Metadane kluczy Direct (nazwa, zahaszowany token, właściciel)
  - Payload żądania jest tymczasowo przetwarzany i przechowywany na potrzeby dostarczenia

- **Na Twoim urządzeniu**:
  - Treść powiadomień (tytuł, treść)
  - Historia wyzwoleń wraz ze znacznikami czasu
  - Odnośniki zewnętrzne

### Czego nie przechowujemy

- Nie zatrzymujemy trwale payloadów żądań po dostarczeniu
- Nie analizujemy treści powiadomień
- Nie udostępniamy Twoich danych osobom trzecim

## Rozwiązywanie problemów

### Brak powiadomień

1. **Sprawdź adres URL webhooka** — skopiuj go bezpośrednio z aplikacji i upewnij się, że nie ma dodatkowych spacji
2. **Sprawdź, czy klucz nadal istnieje** — mógł zostać usunięty albo jego token zresetowany
3. **Zadbaj o uprawnienia do powiadomień** — aplikacja Echobell potrzebuje na Twoim urządzeniu zgody na powiadomienia
4. **Przetestuj przez curl** — aby wykluczyć problemy z Twoim klientem HTTP:
   ```bash
   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'
   ```

### Błędy żądań

- **Błąd parsowania JSON**: upewnij się, że ustawiony jest nagłówek `Content-Type: application/json`, a ciało jest poprawnym JSON-em
- **Nie znaleziono klucza**: odpowiedź z `"success": false` i komunikatem `"Direct key not found."` oznacza, że token został zresetowany albo klucz usunięty (status HTTP nadal wynosi `200`)

### Problem nadal występuje?

- Odwiedź nasze [Centrum wsparcia](/docs/support), aby uzyskać więcej pomocy
- Napisz na echobell@weelone.com, podając:
  - Opis problemu
  - Przykładowe żądanie (z zamaskowanym tokenem)
  - Zachowanie oczekiwane i faktyczne

## Kolejne kroki

- **[Integracja z webhookami](/docs/webhook)** — do współdzielonych powiadomień z szablonami i kanałami
- **[Składnia szablonów](/docs/template)** — poznaj szablony powiadomień w kanałach
- **[Wyzwalacze e-mail](/docs/email-trigger)** — wyzwalaj powiadomienia przez e-mail
- **[Przeglądaj integracje](/docs/features)** — połącz Echobell z narzędziami, których już używasz