# JavaScript API

Mehrere Blöcke des Chatbots führen Ihren JavaScript-Code aus. Der Code rechnet, wertet Antworten externer Dienste aus, ändert Variablen und Tags des Kontakts, sendet Nachrichten und entscheidet, wohin das Szenario weitergeht. Dieser Abschnitt ist eine Referenz für alle, die solchen Code schreiben.

## Wo der Code ausgeführt wird

| Wo | Wann der Code startet | Was ihm außer den Funktionen zur Verfügung steht |
|---|---|---|
| Block [„JavaScript-Interpreter“](https://support.watbot.org/de/chatbots/blocks/developer/javascript) | Der Kontakt hat den Block erreicht | Daten des Kontakts |
| Block [„HTTP-Anfrage“](https://support.watbot.org/de/chatbots/blocks/developer/http), Feld „Antwort mit JavaScript verarbeiten“ | Der Server hat auf die Anfrage geantwortet | Daten des Kontakts und die Serverantwort `response` |
| Block [„Eingehender Webhook“](https://support.watbot.org/de/chatbots/blocks/developer/incoming-webhook) | An der Adresse des Blocks ist eine Anfrage eingegangen | Die Anfrage `request`, die Daten des Kontakts erst, nachdem der Code ihn gefunden hat |
| Block [„Zeilen aus Google Sheets lesen“](https://support.watbot.org/de/chatbots/blocks/lists/google-sheet-reader), Feld „JavaScript zur Tabellenverarbeitung“ | Der Block hat Zeilen in der Tabelle gefunden | Daten des Kontakts und die gefundenen Zeilen `sheet.data` |

Was in diesen Daten steht, beschreibt die Seite [„Eingebaute Variablen“](https://support.watbot.org/de/api/javascript/builtins). Die Funktionen sind in allen Blöcken dieselben:

| Seite | Funktionen |
|---|---|
| [Variablen](https://support.watbot.org/de/api/javascript/variables) | `getContactVariable`, `setContactVariable`, `deleteContactVariable`, `getGlobalVariable`, `setGlobalVariable`, `deleteGlobalVariable` |
| [Tags](https://support.watbot.org/de/api/javascript/tags) | `getContactTags`, `hasContactTag`, `setContactTag`, `deleteContactTag` |
| [Nachrichten und Sprünge](https://support.watbot.org/de/api/javascript/messages) | `sendMessage`, `goToBlock`, `disableContinue` |
| [Kontakt auswählen](https://support.watbot.org/de/api/javascript/contact) | `setContactById` und weitere — nur im Block „Eingehender Webhook“ |
| [Signaturen und Base64](https://support.watbot.org/de/api/javascript/crypto) | `hash_hmac`, `base64_encode`, `base64_decode` |

## Wie der Code ausgeführt wird

1. Der Code läuft vollständig auf einem separaten Server. Die Funktionen ändern den Kontakt nicht sofort, sondern merken sich, was zu tun ist: welche Variablen und Tags geschrieben, welche Nachrichten gesendet werden, zu welchem Block gesprungen wird.
2. Der Code endet ohne Fehler — der Bot schreibt die Variablen und Tags des Kontakts und die globalen Variablen des Bots, sendet dann in der Reihenfolge der Aufrufe die Nachrichten und leitet den Kontakt in den Block aus `goToBlock`. Danach wird die Verbindung „Fortsetzen“ ausgelöst, sofern der Code sie nicht abgeschaltet hat.
3. Der Code endet mit einem Fehler — nichts wird übernommen, auch nicht das, was der Code vor dem Fehler aufgerufen hat.

Innerhalb eines Laufs sehen die Lesefunktionen bereits, was der Code vorher geschrieben hat: Nach `setContactVariable('strauss', 'Rosen')` liefert `getContactVariable('strauss')` den Wert `'Rosen'`, obwohl die Variable beim Kontakt noch nicht gespeichert ist.

Der Code startet bei jedem Durchlauf des Blocks neu. Gewöhnliche JavaScript-Variablen (`var`) bleiben zwischen den Läufen nicht erhalten — was Sie sich merken müssen, schreiben Sie in Variablen des Kontakts oder in globale Variablen des Bots.

## Sprache

Der Code wird als JavaScript nach dem Standard ES5 ausgeführt. Aus neueren Standards fehlen:

- `let` und `const` — deklarieren Sie Variablen mit `var`;
- Pfeilfunktionen — schreiben Sie `function (x) { return x * 2; }`;
- Template-Strings in Backticks — verbinden Sie Zeichenketten mit `+`;
- Klassen, Destrukturierung, `Promise`, `async`/`await`, `setTimeout`;
- Methoden aus neueren Standards: `includes`, `startsWith`, `padStart`, `find`, `Object.assign`, `Array.from` und ähnliche. Statt `includes` und `startsWith` eignet sich `indexOf`.

Alles aus ES5 ist vorhanden: `JSON.parse` und `JSON.stringify`, `Math`, `Date`, die String- und Array-Methoden `split`, `replace`, `trim`, `map`, `filter`, `forEach`, `reduce`, `indexOf`, `sort`. Die Direktive `'use strict'` stört nicht, schaltet den strikten Modus aber nicht ein.

Netzwerkanfragen aus dem Code sind nicht möglich: `fetch`, `XMLHttpRequest` und `require` stehen nicht zur Verfügung. Für Anfragen gibt es den Block „HTTP-Anfrage“.

### Datumsangaben

`Date` rechnet in der Zeitzone des Servers, nehmen Sie für Berechnungen daher die Methoden mit `UTC`: `getUTCHours()`, `getUTCDate()`. Eine Zeichenkette wie `2026-01-31 12:00:00` (so sieht `created_at` aus) kann `Date` nicht lesen — ersetzen Sie das Leerzeichen durch `T` und hängen Sie `Z` an:

```js
var created = new Date(created_at.replace(' ', 'T') + 'Z');
var days = Math.floor((new Date() - created) / 86400000);
```

### Reguläre Ausdrücke

Reguläre Ausdrücke laufen auf der Engine RE2, und einige Möglichkeiten von JavaScript funktionieren dort nicht. Code mit einem solchen Muster bricht mit dem Fehler `Invalid regular expression` ab:

| Muster | Was es ist |
|---|---|
| `(?=...)`, `(?!...)` | Lookahead |
| `(?<=...)`, `(?<!...)` | Lookbehind |
| `\1`, `\2` | Rückverweise auf eine Gruppe |

`\w`, `\b` und `\d` kennen nur lateinische Buchstaben ohne Umlaute und Ziffern: `/\w+/` findet das Wort „Blütenstrauß“ nicht vollständig. Zählen Sie solche Buchstaben ausdrücklich auf: `/[a-zäöüß]+/i`.

## Grenzen

| Was | Grenze |
|---|---|
| Länge des Codes | 16 384 Zeichen in jedem Code-Feld |
| Ausführungszeit | 5 Sekunden. Code, der nicht rechtzeitig fertig wird, bricht mit dem Fehler `Script execution time exceeded` ab |
| `sendMessage` | 10 Nachrichten pro Lauf |
| `goToBlock` | Ein Aufruf pro Lauf |
| Funktionen zur Kontaktauswahl | Ein Aufruf pro Anfrage, nur im Block „Eingehender Webhook“ |

## Fehler und Fehlersuche

Was bei einem Lauf passiert ist, zeigt das „Ausführungsprotokoll“ in den Einstellungen des Blocks: Quellcode, Wert des letzten Ausdrucks, ausgeführte Aktionen und Fehlertext.

Der Wert des letzten Ausdrucks ist das wichtigste Werkzeug zur Fehlersuche. Schreiben Sie einen Variablennamen oder einen Ausdruck ans Ende des Codes, und sein Wert erscheint im Protokoll. Wandeln Sie ein Objekt oder ein Array vorher in eine Zeichenkette um, sonst steht im Protokoll `[object Object]`:

```js
var bouquet = { name: 'Rosen', count: 7 };
JSON.stringify(bouquet);
```

`console.log` verursacht keinen Fehler, schreibt aber nichts ins Protokoll.

Wohin ein Fehler geht, hängt vom Block ab:

| Block | Was bei einem Fehler passiert |
|---|---|
| „JavaScript-Interpreter“ | Der Fehlertext geht an den Kontakt in den Chat, die Verbindung „Fortsetzen“ wird ausgelöst |
| „HTTP-Anfrage“ | Der Fehlertext geht an den Kontakt in den Chat, die Verbindung „Fortsetzen“ wird nicht ausgelöst |
| „Zeilen aus Google Sheets lesen“ | Der Fehlertext geht an den Kontakt in den Chat, die Verbindung „Fortsetzen“ wird nicht ausgelöst |
| „Eingehender Webhook“ | Der Kontakt erhält nichts, der Block beantwortet die Anfrage mit dem Code `422` und dem Fehlertext |

In der Meldung eines Syntaxfehlers ist die Zeilennummer um eins größer als im Editor: Der Fehler `Line 4:5 Unexpected identifier` meint Zeile vier minus eins — also Zeile drei.

Einen Fehler können Sie auch absichtlich auslösen — `throw new Error('Kein Preis')` hält den Code an, und nichts von dem, was er getan hat, wird gespeichert. In Blöcken, die den Fehlertext in den Chat senden, sieht der Kontakt `Error: Kein Preis`.

> [!TIP]
> Testen Sie den Code in der Vorschau des Bots — Button „Bot testen“ im Editor. So sehen Sie den Fehler, nicht Ihre Kunden.