WhatsApp API

Nachrichten und Dateien über WhatsApp versenden — per einfachem HTTP-Request.

Base URL

https://wa.outrnk.io

Immer diese Adresse verwenden — niemals eine Server-IP oder einen Port.

Zwei Zugriffsebenen

Instanz-API — für Nutzer

Auth: API Key (wapi_…)

Nachrichten & Dateien senden, Status, QR, Nummern prüfen.

Admin-API — nur Betreiber

Auth: Login-Token (JWT)

Instanzen anlegen/starten/löschen, Webhooks, Chats.

Wichtig: Ein API Key gehört fest zu einer WhatsApp-Nummer. Die Instanz ergibt sich aus dem Key — sie wird nicht im Request gewählt. Mit einem API Key lassen sich keine Instanzen anlegen oder verwalten; das geht ausschließlich über die Admin-API.

⚠️ Erfolg steht im Body, nicht im HTTP-Status

Das Gateway antwortet bei Fehlern immer mit HTTP 500 — teilweise sogar dann, wenn die Nachricht tatsächlich zugestellt wurde. Der HTTP-Status ist daher nicht verlässlich.

Prüfung	Bedeutung
`body.success === true`	✅ Zugestellt
`body.success === false`	❌ Nicht zugestellt — Grund in `body.error`
HTTP-Status	⚠️ Ignorieren

Niemals automatisch neu senden, wenn eine Antwort kam — auch nicht bei success: false. Die Nachricht kann trotzdem angekommen sein; ein Retry erzeugt Duplikate. Erneut senden nur, wenn gar keine Antwort kam (Netzwerkfehler/Timeout).

const res  = await fetch(url, options);
const body = await res.json();

if (body.success) {
  // zugestellt
} else {
  // nicht zugestellt: body.error auswerten, NICHT automatisch wiederholen
}

Authentifizierung (Instanz-API)

Jeder Request braucht den API Key im Header:

Authorization: Bearer DEIN_API_KEY

Telefonnummern-Format

Eingabe	Ergebnis
`+491701234567`	✅ empfohlen (international)
`491701234567`	✅ funktioniert
`01701234567`	✅ wird automatisch zu `49170…`
`chatId: "4917…@c.us"`	✅ direkt möglich (auch `@lid`)

Nie an die eigene Nummer der Instanz senden — das bringt die WhatsApp-Session zum Absturz. Zum Testen eine andere Nummer verwenden.

POST /api/send-message

Sendet eine Textnachricht.

curl -X POST https://wa.outrnk.io/api/send-message \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+491701234567",
    "message": "Hallo aus der API!"
  }'

Felder

Feld	Pflicht	Beschreibung
`phone`	ja*	Empfängernummer
`chatId`	ja*	Alternative zu `phone`
`message`	ja	Nachrichtentext

* entweder phone oder chatId

Antwort

{
  "success": true,
  "data": {
    "messageId": "true_49170...@c.us_ABC",
    "phone": "+491701234567",
    "status": "sent"
  }
}

POST /api/send-media

Sendet eine Datei — PDF, Bild, Dokument. Zwei Varianten: URL (empfohlen, Gateway lädt die Datei) oder Base64.

Variante A — per URL

curl -X POST https://wa.outrnk.io/api/send-media \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+491701234567",
    "mediaUrl": "https://example.com/rechnung.pdf",
    "filename": "Rechnung.pdf",
    "caption": "Deine Rechnung"
  }'

Variante B — per Base64

curl -X POST https://wa.outrnk.io/api/send-media \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+491701234567",
    "mediaBase64": "JVBERi0xLjQKJcfs...",
    "mimetype": "application/pdf",
    "filename": "Rechnung.pdf",
    "caption": "Deine Rechnung"
  }'

Felder

Feld	Pflicht	Beschreibung
`phone`/`chatId`	ja	Empfänger
`mediaUrl`	ja*	Öffentlich erreichbare URL
`mediaBase64`	ja*	Base64 ohne `data:`-Präfix
`mimetype`	bei Base64	`application/pdf`, `image/png`, …
`filename`	nein	Dateiname beim Empfänger
`caption`	nein	Text zur Datei

* entweder mediaUrl oder mediaBase64 (+ mimetype)

Antwort

{
  "success": true,
  "data": {
    "messageId": "...",
    "phone": "+491701234567",
    "status": "sent",
    "type": "media"
  }
}

Unterstützt: PDF, PNG, JPG, GIF, MP4, MP3, DOCX, XLSX u. a.

WhatsApp-Limit: 64 MB (Bilder 5 MB)

POST /api/send-bulk

Mehrere Nachrichten auf einmal. Sie werden in eine Warteschlange gelegt und mit 1,5–3 s Abstand versendet (Spam-Schutz). Die Antwort bestätigt nur die Annahme, nicht die Zustellung.

Request

{
  "messages": [
    { "phone": "+491701234567", "message": "Nachricht 1" },
    { "phone": "+491709876543", "message": "Nachricht 2" }
  ]
}

Antwort

{
  "success": true,
  "data": {
    "queued": 2,
    "messages": [
      { "phone": "+491701234567", "status": "queued" }
    ]
  }
}

GET /api/status

Verbindungsstatus der eigenen Instanz. Vor Massenversand prüfen — nur bei connected senden.

curl https://wa.outrnk.io/api/status \
  -H "Authorization: Bearer DEIN_API_KEY"

status	Bedeutung
`connected`	✅ Betriebsbereit
`initializing`	Startet gerade
`authenticated`	Angemeldet, noch nicht bereit
`waiting_qr`	⚠️ QR-Code scannen nötig
`error`	Fehler, Neustart läuft

Antwort

{
  "success": true,
  "data": {
    "status": "connected",
    "phoneNumber": "491701234567",
    "connected": true,
    "queue": {
      "sent": 42, "failed": 0,
      "queued": 0, "pending": 0
    },
    "messages": {
      "totalMessages": 1516,
      "totalChats": 51
    }
  }
}

GET /api/qr

QR-Code zum Verbinden der WhatsApp-Nummer. Das Feld qr ist ein fertiges Data-URL-Bild und lässt sich direkt als <img src="…"> anzeigen.

Nicht verbunden

{
  "success": true,
  "data": {
    "qr": "data:image/png;base64,iVBOR...",
    "status": "waiting_qr"
  }
}

Bereits verbunden

{
  "success": true,
  "data": {
    "status": "connected",
    "phoneNumber": "491701234567"
  }
}

GET /api/check-number/:phone

Prüft, ob eine Nummer WhatsApp nutzt. Bei registered: false ist Senden zwecklos.

curl https://wa.outrnk.io/api/check-number/491701234567 \
  -H "Authorization: Bearer DEIN_API_KEY"

{
  "success": true,
  "data": {
    "phone": "491701234567",
    "registered": true,
    "whatsappId": "87041941463108@lid"
  }
}

ADMIN

Admin-API

Diese Endpunkte sind mit einem API Key nicht erreichbar. Sie benötigen ein Login-Token (JWT). Nur für den Betreiber.

POST /api/auth/login

curl -X POST https://wa.outrnk.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "DEIN_PASSWORT"
  }'

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "user": { "username": "admin" }
  }
}

Token ist 24 h gültig. Danach in jedem Admin-Request:

Authorization: Bearer DEIN_JWT_TOKEN

ADMIN

Instanzen verwalten

Methode	Endpoint	Zweck
GET	`/api/instances`	Alle Instanzen auflisten
POST	`/api/instances`	Neue Instanz anlegen
PUT	`/api/instances/:id`	Instanz bearbeiten
DEL	`/api/instances/:id`	Instanz löschen
POST	`/api/instances/:id/start`	Starten
POST	`/api/instances/:id/stop`	Stoppen
GET	`/api/instances/:id/status`	Status
GET	`/api/instances/:id/qr`	QR-Code
GET	`/api/instances/:id/share-token`	Teilbaren QR-Link erzeugen

Neue Instanz anlegen

curl -X POST https://wa.outrnk.io/api/instances \
  -H "Authorization: Bearer DEIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Kunde Mueller" }'

Die Antwort enthält id, port und den generierten API Key (wapi_…) für den Kunden.

QR-Link zum Weitergeben

Der Kunde scannt selbst — ohne Admin-Zugang:

curl https://wa.outrnk.io/api/instances/INSTANZ_ID/share-token \
  -H "Authorization: Bearer DEIN_JWT_TOKEN"

# ergibt eine oeffentliche Seite:
# https://wa.outrnk.io/qr/INSTANZ_ID/SHARE_TOKEN

ADMIN

Webhooks

Methode	Endpoint	Zweck
GET	`/api/instances/:id/webhook`	Konfiguration lesen
POST	`/api/instances/:id/webhook`	Setzen
DEL	`/api/instances/:id/webhook`	Entfernen

Webhook setzen

{
  "url": "https://deine-app.de/webhook",
  "secret": "optional"
}

Payload an deine URL

{
  "event": "message",
  "instanceId": "03da98e9-...",
  "timestamp": 1785000000000,
  "data": { }
}

Header: X-Instance-ID, X-Event-Type und — falls secret gesetzt — X-Webhook-Signature (HMAC-SHA256 über den JSON-Body). Bei Fehlern bis zu 3 Zustellversuche.

ADMIN

Chats & Nachrichten lesen

Methode	Endpoint	Zweck
GET	`/api/instances/:id/chats`	Chatliste
GET	`/api/instances/:id/chats/:chatId/messages`	Nachrichten eines Chats
GET	`/api/instances/:id/messages/recent`	Letzte Nachrichten

Fehlerbehandlung

HTTP	code	Ursache	Lösung
401	`UNAUTHORIZED`	Header fehlt/falsch	`Authorization: Bearer KEY` setzen
401	`INVALID_API_KEY`	Key unbekannt	Key prüfen
503	`INSTANCE_OFFLINE`	Instanz nicht online	`/api/status` prüfen, ggf. QR scannen
400	—	Pflichtfeld fehlt	Request-Body prüfen
500	—	Sende-/Validierungsfehler	`body.error` lesen — nicht automatisch wiederholen

Häufige `error`-Texte

Text	Bedeutung
`Number not registered on WhatsApp`	Empfänger hat kein WhatsApp
`WhatsApp not connected`	Instanz nicht verbunden (QR?)
`detached Frame` / `reading 'id'`	Interne Session-Störung; Instanz startet sich selbst neu

Vollständiges Beispiel (Node.js)

const API = 'https://wa.outrnk.io';
const KEY = process.env.WHATSAPP_API_KEY;

async function call(path, body) {
  const res = await fetch(`${API}${path}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  // Erfolg steht im Body, nicht im HTTP-Status:
  const data = await res.json().catch(() => null);
  return { ok: data?.success === true, error: data?.error, data: data?.data };
}

// Text senden
const t = await call('/api/send-message', {
  phone: '+491701234567',
  message: 'Hallo!',
});

// PDF senden
const p = await call('/api/send-media', {
  phone: '+491701234567',
  mediaUrl: 'https://example.com/rechnung.pdf',
  filename: 'Rechnung.pdf',
  caption: 'Deine Rechnung',
});

// NICHT automatisch wiederholen:
if (!t.ok) console.error('Nicht zugestellt:', t.error);

Checkliste für Integrationen

✓ Base URL https://wa.outrnk.io verwenden (keine Server-IP, kein Port)
✓ Authorization: Bearer <API_KEY> in jedem Request
✓ Erfolg ausschließlich an body.success festmachen
✓ Bei Antwort mit success: false nicht automatisch neu senden (Duplikatgefahr)
✓ Vor Massenversand /api/status prüfen (connected)
✓ Nummern international senden (+49…)
✓ Nie an die eigene Nummer der Instanz senden

Für KI-Assistenten: Diese Dokumentation gibt es auch als reine Textfassung zum Kopieren — wa.outrnk.io/api-docs.txt (öffentliche Nutzer-Fassung) (auch als /api-docs.md). Einfach komplett kopieren und der KI als Anweisung geben.

Navigation

WhatsApp API

Base URL

Zwei Zugriffsebenen

Instanz-API — für Nutzer

Admin-API — nur Betreiber

⚠️ Erfolg steht im Body, nicht im HTTP-Status

Authentifizierung (Instanz-API)

Telefonnummern-Format

Felder

Antwort

Variante A — per URL

Variante B — per Base64

Felder

Antwort

Request

Antwort

Antwort

Nicht verbunden

Bereits verbunden

Admin-API

Instanzen verwalten

Neue Instanz anlegen

QR-Link zum Weitergeben

Webhooks

Webhook setzen

Payload an deine URL

Chats & Nachrichten lesen

Fehlerbehandlung

Häufige error-Texte

Vollständiges Beispiel (Node.js)

Checkliste für Integrationen

Häufige `error`-Texte