Talkward API

Mit der API verbinden Sie Talkward mit Ihren eigenen Systemen: Gespräche und Kontakte lesen, Nachrichten senden, Status, Tags und Felder setzen, bei neuen Ereignissen per Webhook benachrichtigt werden und Meldungen in Team-Kanäle schreiben. Für Make, Zapier und n8n gibt es fertige Bausteine als eigene Erweiterungen; sie nutzen dieselbe API.

Basis-Adressehttps://chat.talkward.app/api/v1

37 Endpunkte · REST · JSON · Webhooks · OpenAPI-Datei

API-Schlüssel

Den Schlüssel erzeugst du in Talkward unter Einstellungen › Erweiterungen › API. Die API ist ab Professional ohne Aufpreis dabei.

Live ausprobieren

Anmeldung

Erzeugen Sie unter Einstellungen › Erweiterungen › API einen Schlüssel und senden Sie ihn bei jeder Anfrage in der Kopfzeile Authorization mit:

HTTP

Authorization: Bearer tw_…

Statt Authorization geht auch die Kopfzeile X-API-Key: tw_…. Ein Schlüssel gehört zu genau einem Arbeitsbereich und sieht nur dessen Daten. Widerrufen Sie ihn, hört jede Verbindung damit sofort auf. Bewahren Sie den Schlüssel wie ein Passwort auf und nutzen Sie ihn nur auf Ihrem Server, nie im Browser.

Beim Erzeugen wählen Sie die Rechte: Lesen und schreiben oder Nur lesen. Ein Schlüssel nur zum Lesen darf alle GET-Aufrufe; jeder andere Aufruf endet mit 403 integration.nur_lesen. Das passt für Auswertungen, Dashboards und Dienstleister, die nichts verändern sollen.

Antworten und Fehler

Alle Antworten sind JSON. Erfolgreiche Antworten tragen "ok": true. Fehler kommen mit passendem HTTP-Status und einem Code, zum Beispiel {"ok": false, "fehler": "konversation.nicht_gefunden"}.

Status	Bedeutung
400	Eingabe ungültig (Code nennt das Feld, z. B. `verfassen.adresse`)
401	Schlüssel fehlt, ist falsch oder widerrufen (`integration.token_ungueltig`)
403	Funktion nicht freigeschaltet (`berechtigung.fehlt` mit `funktion`) oder Schlüssel nur zum Lesen (`integration.nur_lesen`)
404	Gespräch, Kontakt, Marke, Anhang oder Webhook gibt es nicht
409	Gespräch ist archiviert, oder derselbe `Idempotency-Key` läuft noch (`api.idempotenz_laeuft`)
422	Derselbe `Idempotency-Key` mit anderem Inhalt (`api.idempotenz_anders`)
429	Zu viele Anfragen; `Retry-After` nennt die Sekunden bis zum nächsten Versuch

Limits

Je Schlüssel sind 300 Anfragen pro Minute erlaubt. Jede Antwort nennt den Stand in drei Kopfzeilen:

Kopfzeile	Bedeutung
`X-RateLimit-Limit`	Anfragen je Minute (300)
`X-RateLimit-Remaining`	noch frei in dieser Minute
`X-RateLimit-Reset`	Sekunden, bis die Minute neu beginnt

Ist das Kontingent aufgebraucht, kommt 429 mit Retry-After (Sekunden). Zeitangaben sind ISO 8601 mit Zeitzone, zum Beispiel 2026-09-25T09:14:00+00:00.

Blättern und Abgleich

Listen liefern höchstens limit Einträge. Gibt es mehr, steht in der Antwort weiter: diesen Wert beim nächsten Aufruf als nach mitgeben, bis weiter leer (null) ist. Für einen regelmäßigen Abgleich mit Ihrem System eignet sich geaendert_seit (Zeitpunkt des letzten Abgleichs): Dann kommen nur Gespräche bzw. Kontakte, die sich seitdem geändert haben.

HTTP

GET /gespraeche?geaendert_seit=2026-09-29T06:00:00Z&limit=100
GET /gespraeche?geaendert_seit=2026-09-29T06:00:00Z&limit=100&nach=MjAyNi0wOS0yOVQwNzoxMjo…

Wiederholen ohne Doppel

Bricht eine Verbindung ab, weiß Ihr System nicht, ob eine Nachricht schon raus ist. Schicken Sie darum bei schreibenden Aufrufen die Kopfzeile Idempotency-Key mit, einen eigenen, eindeutigen Wert je Vorgang (zum Beispiel die Nummer Ihres Auftrags oder eine UUID, höchstens 200 Zeichen):

HTTP

Idempotency-Key: versand-10234

Talkward merkt sich die Antwort 24 Stunden. Kommt derselbe Aufruf mit demselben Schlüssel noch einmal, liefert Talkward die gemerkte Antwort mit der Kopfzeile Idempotent-Replayed: true, statt die Nachricht ein zweites Mal zu senden. Fehler werden nicht gemerkt; nach einem Fehler dürfen Sie es mit demselben Schlüssel erneut versuchen. Make, Zapier und n8n wiederholen fehlgeschlagene Schritte automatisch, deshalb lohnt sich der Schlüssel dort besonders.

Objekte

Ein Gespräch sieht so aus:

JSON

{
  "id": 101,
  "marke": "bertrand",
  "marke_name": "BERTRAND",
  "kanal": "whatsapp",
  "status": "mensch",
  "spam": false,
  "ungelesen": true,
  "zugewiesen": "anna@shop.de",
  "abteilung": {
    "id": 3,
    "name": "Versand"
  },
  "kunde": {
    "name": "Nina Neu",
    "mail": "nina@example.com",
    "telefon": "+4915112345678"
  },
  "betreff": null,
  "sprache": "de",
  "auftrag": "10234",
  "tags": [
    "VIP"
  ],
  "felder": {
    "Kundennummer": "4711"
  },
  "erstellt": "2026-09-25T09:12:00+00:00",
  "aktualisiert": "2026-09-25T09:14:00+00:00",
  "link": "https://chat.talkward.app/#/posteingang/haupt/101"
}

status ist ki (die KI antwortet), mensch (beim Team) oder erledigt. Eine Nachricht:

JSON

{
  "id": 5012,
  "von": "kunde",
  "text": "Wo bleibt meine Bestellung?",
  "mitarbeiter": null,
  "anhaenge": [
    {
      "id": "Xy3kQ9bT2mLp",
      "name": "rechnung.pdf",
      "mime": "application/pdf",
      "groesse": 48211,
      "url": "https://chat.talkward.app/api/v1/gespraeche/101/anhaenge/Xy3kQ9bT2mLp"
    }
  ],
  "erstellt": "2026-09-25T09:14:00+00:00"
}

von ist kunde, mitarbeiter, ki oder notiz. Die url eines Anhangs laden Sie mit demselben Schlüssel herunter (siehe Anhang herunterladen).

Arbeitsbereich

Verbindung prüfen

GET/api/v1/ich

Zeigt, zu welchem Arbeitsbereich der Schlüssel gehört. Gut als erster Aufruf, um den Schlüssel zu testen.

GET Anfrage

curl "https://chat.talkward.app/api/v1/ich" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/ich', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/ich",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/ich', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "mandant": {
    "id": "6f1c…",
    "name": "Haferhain GmbH"
  },
  "schluessel": {
    "name": "Warenwirtschaft",
    "art": "allgemein",
    "rechte": "alles"
  }
}

Marken auflisten

GET/api/v1/marken

Alle aktiven Marken des Arbeitsbereichs. Den key brauchen Sie für marke in anderen Aufrufen.

GET Anfrage

curl "https://chat.talkward.app/api/v1/marken" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/marken', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/marken",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/marken', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "marken": [
    {
      "key": "haferhain",
      "name": "Haferhain"
    }
  ]
}

Team auflisten

GET/api/v1/team

Alle aktiven Mitarbeiter mit Anwesenheit. anwesenheit ist da, pause oder abwesend; das setzt jeder Mitarbeiter selbst. Ein abgelaufenes „abwesend bis“ gilt wieder als da. abwesend_bis steht nur bei abwesend mit Datum.

GET Anfrage

curl "https://chat.talkward.app/api/v1/team" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/team', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/team",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/team', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "team": [
    {
      "login": "anna@shop.de",
      "name": "Anna",
      "anwesenheit": "da",
      "abwesend_bis": null
    }
  ]
}

Abteilungen auflisten

GET/api/v1/abteilungen

Abteilungen mit Verteilregel und Mitgliedern. regel ist alle oder belastung. Ohne die Funktion abteilungen (ab Professional) ist die Liste leer.

GET Anfrage

curl "https://chat.talkward.app/api/v1/abteilungen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/abteilungen', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/abteilungen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/abteilungen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "abteilungen": [
    {
      "id": 3,
      "name": "Versand",
      "regel": "belastung",
      "mitglieder": [
        "anna@shop.de"
      ]
    }
  ]
}

Tags auflisten

GET/api/v1/tags

Alle benutzten Tags der Gespräche und Segmente der Kontakte mit Häufigkeit, häufigste zuerst. Gut für Auswahlfelder in Make, Zapier oder n8n.

GET Anfrage

curl "https://chat.talkward.app/api/v1/tags" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/tags', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/tags",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraeche": [
    {
      "name": "VIP",
      "anzahl": 42
    }
  ],
  "kontakte": [
    {
      "name": "Newsletter",
      "anzahl": 310
    }
  ]
}

Felder auflisten

GET/api/v1/felder

Namen der eigenen Felder, die in Gesprächen bzw. Kontakten vorkommen.

GET Anfrage

curl "https://chat.talkward.app/api/v1/felder" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/felder', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/felder",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/felder', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraeche": [
    "Kundennummer"
  ],
  "kontakte": [
    "Kundennummer",
    "Bonusstufe"
  ]
}

WhatsApp-Vorlagen auflisten

GET/api/v1/marken/{marke}/whatsapp-vorlagen

Die bei Meta freigegebenen Vorlagen der WhatsApp-Nummer dieser Marke. parameter ist die Zahl der Platzhalter {{1}}, {{2}}, … im Text. Ohne eingerichtete WhatsApp-Nummer kommt 400 whatsapp.nicht_eingerichtet.

GET Anfrage

curl "https://chat.talkward.app/api/v1/marken/haferhain/whatsapp-vorlagen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/marken/haferhain/whatsapp-vorlagen', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/marken/haferhain/whatsapp-vorlagen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/marken/haferhain/whatsapp-vorlagen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "vorlagen": [
    {
      "name": "versand_info",
      "sprache": "de",
      "text": "Hallo {{1}}, Ihr Paket {{2}} ist unterwegs.",
      "parameter": 2,
      "kategorie": "UTILITY"
    }
  ]
}

Gespräche

Jede Änderung an einem Gespräch steht als Zeile im Gesprächsverlauf.

Gespräche auflisten

GET/api/v1/gespraeche

Gespräche des Arbeitsbereichs, zuletzt aktualisierte zuerst.

Query-Parameter

kontaktstring
E-Mail-Adresse oder Telefonnummer des Kunden
statusstring
offen, ki, mensch oder erledigt
markestring
Nur Gespräche dieser Marke (key)
geaendert_seitstring
Nur Gespräche, die sich seit diesem Zeitpunkt geändert haben (ISO 8601 mit Zeitzone)
limitinteger
1 bis 100, Vorgabe 20
nachstring
Wert von weiter aus der vorigen Antwort, für die nächste Seite

GET Anfrage

curl "https://chat.talkward.app/api/v1/gespraeche?status=mensch&limit=20" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche?status=mensch&limit=20', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/gespraeche",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "status": "mensch",
        "limit": 20,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/gespraeche', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'status' => 'mensch',
        'limit' => 20,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraeche": [
    {
      "id": 101,
      "marke": "haferhain",
      "kanal": "whatsapp",
      "status": "mensch",
      "…": "…"
    }
  ],
  "weiter": "MjAyNi0wOS0yNVQwOToxNDowMCswMDowMHwxMDE"
}

Gespräch abrufen

GET/api/v1/gespraeche/{id}

Ein Gespräch mit allen Feldern (siehe Objekte).

GET Anfrage

curl "https://chat.talkward.app/api/v1/gespraeche/101" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/gespraeche/101",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/gespraeche/101', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "marke": "haferhain",
    "kanal": "whatsapp",
    "status": "mensch",
    "…": "…"
  }
}

Nachrichten eines Gesprächs

GET/api/v1/gespraeche/{id}/nachrichten

Der Verlauf eines Gesprächs, älteste zuerst. Interne Notizen nur auf Wunsch. Ohne vor und nach kommen die letzten limit Nachrichten. mehr sagt, ob es in dieser Richtung weitere gibt.

Query-Parameter

notizenboolean
1 liefert interne Notizen mit
limitinteger
1 bis 500, Vorgabe 50
vorinteger
Nachrichten-ID: die Nachrichten davor (ältere nachladen)
nachinteger
Nachrichten-ID: die Nachrichten danach (neue abholen)

GET Anfrage

curl "https://chat.talkward.app/api/v1/gespraeche/101/nachrichten?notizen=1&limit=50" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/nachrichten?notizen=1&limit=50', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/gespraeche/101/nachrichten",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "notizen": 1,
        "limit": 50,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/gespraeche/101/nachrichten', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'notizen' => 1,
        'limit' => 50,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "nachrichten": [
    {
      "id": 5012,
      "von": "kunde",
      "text": "Wo bleibt meine Bestellung?",
      "mitarbeiter": null,
      "anhaenge": [],
      "erstellt": "2026-09-25T09:14:00+00:00"
    }
  ],
  "mehr": false
}

Anhang herunterladen

GET/api/v1/gespraeche/{id}/anhaenge/{anhang}

Die Datei eines Anhangs, immer als Download. Den Link finden Sie als url in anhaenge jeder Nachricht.

GET Anfrage

curl "https://chat.talkward.app/api/v1/gespraeche/101/anhaenge/Xy3kQ9bT2mLp" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/anhaenge/Xy3kQ9bT2mLp', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/gespraeche/101/anhaenge/Xy3kQ9bT2mLp",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/gespraeche/101/anhaenge/Xy3kQ9bT2mLp', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort senden

POST/api/v1/gespraeche/{id}/nachrichten

Die Nachricht geht über den Kanal des Gesprächs sofort an den Kunden. Im Posteingang steht der Name Ihres Schlüssels als Absender. Bei WhatsApp gilt das 24-Stunden-Fenster: Hat der Kunde länger nicht geschrieben, verlangt WhatsApp eine Vorlage (siehe WhatsApp-Vorlage senden), und die Antwort meldet zugestellt: false.

Body

textstringPflicht (eines von beiden)
Text an den Kunden (ohne Text genügt ein Anhang)
anhaengeobject[]
Bis zu 5 Dateien: dateiname, inhalt (Base64), mime (optional); je höchstens 15 MB; Bilder, PDF, Office-Dateien

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/nachrichten" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Anbei Ihre Rechnung.",
  "anhaenge": [
    {
      "dateiname": "rechnung-10234.pdf",
      "inhalt": "JVBERi0xLjQK…"
    }
  ]
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/nachrichten', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "Anbei Ihre Rechnung.",
    "anhaenge": [
      {
        "dateiname": "rechnung-10234.pdf",
        "inhalt": "JVBERi0xLjQK…"
      }
    ]
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/nachrichten",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "text": "Anbei Ihre Rechnung.",
        "anhaenge": [
            {
                "dateiname": "rechnung-10234.pdf",
                "inhalt": "JVBERi0xLjQK…",
            },
        ],
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/nachrichten', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'text' => 'Anbei Ihre Rechnung.',
        'anhaenge' => [
            [
                'dateiname' => 'rechnung-10234.pdf',
                'inhalt' => 'JVBERi0xLjQK…',
            ],
        ],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "nachricht": {
    "id": 5013,
    "von": "mitarbeiter",
    "…": "…"
  },
  "zugestellt": true,
  "gespraech": {
    "id": 101,
    "…": "…"
  }
}

WhatsApp-Vorlage senden

POST/api/v1/gespraeche/{id}/vorlage

Schickt in ein WhatsApp-Gespräch eine bei Meta freigegebene Vorlage, auch nach dem 24-Stunden-Fenster. Typisch für Versandmeldungen, Terminerinnerungen oder die Rückmeldung nach Tagen. Im Verlauf steht der Text so, wie ihn der Kunde bekommt.

Body

namestringPflicht
Name der Vorlage (siehe WhatsApp-Vorlagen auflisten)
sprachestring
Sprache der Vorlage, Vorgabe de
parameterstring[]
Werte für {{1}}, {{2}}, …; genau so viele, wie die Vorlage hat

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/vorlage" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "versand_info",
  "sprache": "de",
  "parameter": [
    "Nina",
    "10234"
  ]
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/vorlage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "versand_info",
    "sprache": "de",
    "parameter": [
      "Nina",
      "10234"
    ]
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/vorlage",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "name": "versand_info",
        "sprache": "de",
        "parameter": ["Nina", "10234"],
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/vorlage', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'name' => 'versand_info',
        'sprache' => 'de',
        'parameter' => ['Nina', '10234'],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "nachricht": {
    "id": 5030,
    "text": "Hallo Nina, Ihr Paket 10234 ist unterwegs.",
    "…": "…"
  },
  "zugestellt": true,
  "gespraech": {
    "id": 101,
    "…": "…"
  }
}

Neue Nachricht schreiben

POST/api/v1/nachrichten

Schreibt an eine E-Mail-Adresse oder WhatsApp-Nummer. Gibt es zu Marke und Adresse ein offenes Gespräch, geht die Nachricht dorthin, sonst entsteht ein neues (neu: true).

Body

markestringPflicht
Marke (key), über die gesendet wird
kanalstringPflicht
mail oder whatsapp
anstringPflicht
E-Mail-Adresse oder Telefonnummer mit Ländervorwahl
textstringPflicht (eines von beiden)
Text der Nachricht (entfällt mit vorlage oder wenn ein Anhang dabei ist)
anhaengeobject[]
Dateien wie bei Antwort senden
vorlageobject
Nur WhatsApp: {name, sprache, parameter} statt Text; nötig, wenn der Kunde nicht in den letzten 24 Stunden geschrieben hat
namestring
Name des Kunden
betreffstring
Betreff (nur E-Mail)
statusstring
Danach setzen: erledigt, an_ki oder an_mensch

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/nachrichten" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "marke": "haferhain",
  "kanal": "mail",
  "an": "nina@example.com",
  "name": "Nina Neu",
  "betreff": "Ihre Bestellung 10234",
  "text": "Guten Tag, Ihre Bestellung ist unterwegs."
}'

const res = await fetch('https://chat.talkward.app/api/v1/nachrichten', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "marke": "haferhain",
    "kanal": "mail",
    "an": "nina@example.com",
    "name": "Nina Neu",
    "betreff": "Ihre Bestellung 10234",
    "text": "Guten Tag, Ihre Bestellung ist unterwegs."
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/nachrichten",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "marke": "haferhain",
        "kanal": "mail",
        "an": "nina@example.com",
        "name": "Nina Neu",
        "betreff": "Ihre Bestellung 10234",
        "text": "Guten Tag, Ihre Bestellung ist unterwegs.",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/nachrichten', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'marke' => 'haferhain',
        'kanal' => 'mail',
        'an' => 'nina@example.com',
        'name' => 'Nina Neu',
        'betreff' => 'Ihre Bestellung 10234',
        'text' => 'Guten Tag, Ihre Bestellung ist unterwegs.',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "nachricht": {
    "id": 5020,
    "…": "…"
  },
  "zugestellt": true,
  "neu": true,
  "gespraech": {
    "id": 102,
    "…": "…"
  }
}

Notiz hinzufügen

POST/api/v1/gespraeche/{id}/notizen

Eine interne Notiz. Der Kunde sieht sie nicht.

Body

textstringPflicht
Text der Notiz

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/notizen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Kunde hat telefonisch nachgefragt."
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/notizen', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "Kunde hat telefonisch nachgefragt."
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/notizen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "text": "Kunde hat telefonisch nachgefragt.",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/notizen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'text' => 'Kunde hat telefonisch nachgefragt.',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "nachricht": {
    "id": 5014,
    "von": "notiz",
    "text": "Kunde hat telefonisch nachgefragt.",
    "…": "…"
  }
}

Status setzen

POST/api/v1/gespraeche/{id}/status

Body

statusstringPflicht
erledigt, offen, an_ki, an_mensch oder spam

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/status" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "erledigt"
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/status', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "erledigt"
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/status",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "status": "erledigt",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/status', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'status' => 'erledigt',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "status": "erledigt",
    "…": "…"
  }
}

Gespräch zuweisen

POST/api/v1/gespraeche/{id}/zuweisen

Body

loginstringPflicht
Login des Mitarbeiters; leer entfernt die Zuweisung

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/zuweisen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "login": "anna@shop.de"
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/zuweisen', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "login": "anna@shop.de"
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/zuweisen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "login": "anna@shop.de",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/zuweisen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'login' => 'anna@shop.de',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "zugewiesen": "anna@shop.de",
    "…": "…"
  }
}

Abteilung setzen

POST/api/v1/gespraeche/{id}/abteilung

Gibt das Gespräch der Abteilung nach ihrer Verteilregel: Bei alle liegt es bei der Abteilung, bei belastung geht es an das verfügbare Mitglied mit den wenigsten offenen Gesprächen und steht dann unter zugewiesen. 403 ohne Funktion abteilungen, 404 bei fremder oder unbekannter Abteilung.

Body

abteilungintegerPflicht
ID der Abteilung; null entfernt sie

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/abteilung" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "abteilung": 3
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/abteilung', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "abteilung": 3
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/abteilung",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "abteilung": 3,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/abteilung', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'abteilung' => 3,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "abteilung": {
      "id": 3,
      "name": "Versand"
    },
    "…": "…"
  }
}

Tags ändern

POST/api/v1/gespraeche/{id}/tags

Body

hinzustring[]
Tags, die dazukommen
wegstring[]
Tags, die entfernt werden

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/tags" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "hinzu": [
    "VIP"
  ],
  "weg": [
    "Retoure"
  ]
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/tags', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "hinzu": [
      "VIP"
    ],
    "weg": [
      "Retoure"
    ]
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/tags",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "hinzu": ["VIP"],
        "weg": ["Retoure"],
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'hinzu' => ['VIP'],
        'weg' => ['Retoure'],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "tags": [
      "VIP"
    ],
    "…": "…"
  }
}

Felder setzen

POST/api/v1/gespraeche/{id}/felder

Body

felderobjectPflicht
Name und Wert je Feld; ein leerer Wert entfernt das Feld

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/felder" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "felder": {
    "Kundennummer": "4711"
  }
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/felder', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "felder": {
      "Kundennummer": "4711"
    }
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/felder",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "felder": {
            "Kundennummer": "4711",
        },
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/felder', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'felder' => [
            'Kundennummer' => '4711',
        ],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "felder": {
      "Kundennummer": "4711"
    },
    "…": "…"
  }
}

Kundendaten ändern

POST/api/v1/gespraeche/{id}/kontakt

Name, E-Mail-Adresse oder Telefonnummer des Kunden in diesem Gespräch.

Body

namestring
Name des Kunden
mailstring
E-Mail-Adresse
telefonstring
Telefonnummer mit Ländervorwahl

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/gespraeche/101/kontakt" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nina Neu",
  "telefon": "+4915112345678"
}'

const res = await fetch('https://chat.talkward.app/api/v1/gespraeche/101/kontakt', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Nina Neu",
    "telefon": "+4915112345678"
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/gespraeche/101/kontakt",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "name": "Nina Neu",
        "telefon": "+4915112345678",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/gespraeche/101/kontakt', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'name' => 'Nina Neu',
        'telefon' => '+4915112345678',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "gespraech": {
    "id": 101,
    "kunde": {
      "name": "Nina Neu",
      "…": "…"
    },
    "…": "…"
  }
}

Kontakte

Alle Kontakte abrufen

GET/api/v1/kontakte/profile

Alle Kontaktprofile aus dem Bereich Kontakte, nach ID aufsteigend. Zum Blättern weiter als nach mitgeben; für den Abgleich geaendert_seit.

Query-Parameter

suchestring
Name, E-Mail oder Telefon
segmentstring
Nur Kontakte mit diesem Segment
geaendert_seitstring
Nur Kontakte, die sich seitdem geändert haben (ISO 8601 mit Zeitzone)
limitinteger
1 bis 200, Vorgabe 50
nachinteger
Wert von weiter aus der vorigen Antwort

GET Anfrage

curl "https://chat.talkward.app/api/v1/kontakte/profile?segment=Newsletter&limit=50" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/profile?segment=Newsletter&limit=50', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/kontakte/profile",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "segment": "Newsletter",
        "limit": 50,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/kontakte/profile', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'segment' => 'Newsletter',
        'limit' => 50,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakte": [
    {
      "id": 42,
      "name": "Nina Neu",
      "mail": "nina@example.com",
      "tags": [
        "Newsletter"
      ],
      "…": "…"
    }
  ],
  "weiter": 42
}

Kontakte suchen

GET/api/v1/kontakte

Query-Parameter

suchestring
Name, E-Mail, Telefon oder Bestellnummer

GET Anfrage

curl "https://chat.talkward.app/api/v1/kontakte?suche=nina%40example.com" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/kontakte?suche=nina%40example.com', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/kontakte",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "suche": "nina@example.com",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/kontakte', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'suche' => 'nina@example.com',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakte": [
    {
      "schluessel": "nina@example.com",
      "name": "Nina Neu",
      "mails": [
        "nina@example.com"
      ],
      "telefone": [],
      "marken": [
        "haferhain"
      ],
      "letztes_gespraech": 101,
      "offen": 1
    }
  ]
}

Kontakt abrufen

GET/api/v1/kontakte/{id}

Das Kontaktprofil aus dem Bereich Kontakte mit Segmenten, Feldern, Firma, Kennzahlen und den Ereignissen der Zeitleiste.

GET Anfrage

curl "https://chat.talkward.app/api/v1/kontakte/42" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/42', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/kontakte/42",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/kontakte/42', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakt": {
    "id": 42,
    "name": "Nina Neu",
    "mail": "nina@example.com",
    "…": "…"
  },
  "ereignisse": [],
  "link": "https://chat.talkward.app/#/kontakte/42"
}

Kontakt anlegen oder ergänzen

POST/api/v1/kontakte

Gibt es die Person schon (gleiche E-Mail oder Telefonnummer), werden leere Felder gefüllt; Segmente und Felder kommen dazu. Eines von mail und telefon ist Pflicht.

Body

mailstringPflicht (eines von beiden)
E-Mail-Adresse
telefonstringPflicht (eines von beiden)
Telefonnummer mit Ländervorwahl
namestring
Name
sprachestring
Sprache, z. B. de
landstring
Land als ISO-Code, z. B. DE
stadtstring
Stadt
firmastring
Firma
positionstring
Position in der Firma
websitestring
Website
tagsstring[]
Segmente
felderobject
Eigene Felder, Name und Wert

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/kontakte" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mail": "nina@example.com",
  "name": "Nina Neu",
  "land": "DE",
  "tags": [
    "Newsletter"
  ],
  "felder": {
    "Kundennummer": "4711"
  }
}'

const res = await fetch('https://chat.talkward.app/api/v1/kontakte', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mail": "nina@example.com",
    "name": "Nina Neu",
    "land": "DE",
    "tags": [
      "Newsletter"
    ],
    "felder": {
      "Kundennummer": "4711"
    }
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/kontakte",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "mail": "nina@example.com",
        "name": "Nina Neu",
        "land": "DE",
        "tags": ["Newsletter"],
        "felder": {
            "Kundennummer": "4711",
        },
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/kontakte', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'mail' => 'nina@example.com',
        'name' => 'Nina Neu',
        'land' => 'DE',
        'tags' => ['Newsletter'],
        'felder' => [
            'Kundennummer' => '4711',
        ],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakt": {
    "id": 42,
    "…": "…"
  },
  "neu": true,
  "link": "https://chat.talkward.app/#/kontakte/42"
}

Kontakt ändern

PATCH/api/v1/kontakte/{id}

Ändert nur die mitgeschickten Felder; ein leerer Wert ("") leert das Feld. tags und felder ersetzen die bisherigen. Name und Sprache laufen auch in die Gespräche der Person. Ist die neue E-Mail oder Telefonnummer schon an einem anderen Kontakt, kommt 409 kontakt.vorhanden mit dessen id.

Body

namestring
Name
mailstring
E-Mail-Adresse
telefonstring
Telefonnummer mit Ländervorwahl
sprache, land, stadt, firma, position, websitestring
wie beim Anlegen
tagsstring[]
Segmente (ersetzen die bisherigen)
felderobject
Eigene Felder (ersetzen die bisherigen)

PATCH Anfrage

curl -X PATCH "https://chat.talkward.app/api/v1/kontakte/42" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nina Neumann",
  "stadt": "Köln",
  "tags": [
    "VIP",
    "Newsletter"
  ]
}'

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/42', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Nina Neumann",
    "stadt": "Köln",
    "tags": [
      "VIP",
      "Newsletter"
    ]
  }),
});
const daten = await res.json();

import os, requests

res = requests.patch(
    "https://chat.talkward.app/api/v1/kontakte/42",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "name": "Nina Neumann",
        "stadt": "Köln",
        "tags": ["VIP", "Newsletter"],
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('PATCH', 'https://chat.talkward.app/api/v1/kontakte/42', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'name' => 'Nina Neumann',
        'stadt' => 'Köln',
        'tags' => ['VIP', 'Newsletter'],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakt": {
    "id": 42,
    "name": "Nina Neumann",
    "…": "…"
  },
  "link": "https://chat.talkward.app/#/kontakte/42"
}

Kontakt löschen

DEL/api/v1/kontakte/{id}

Löscht das Kontaktprofil, zum Beispiel auf Wunsch der Person (DSGVO Art. 17). Mit gespraeche=1 löscht Talkward auch alle Gespräche der Person samt Nachrichten und Anhängen, endgültig und ohne Papierkorb.

Query-Parameter

gespraecheboolean
1 löscht auch alle Gespräche mit der E-Mail-Adresse oder Telefonnummer

DEL Anfrage

curl -X DELETE "https://chat.talkward.app/api/v1/kontakte/42?gespraeche=1" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/42?gespraeche=1', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.delete(
    "https://chat.talkward.app/api/v1/kontakte/42",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "gespraeche": 1,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('DELETE', 'https://chat.talkward.app/api/v1/kontakte/42', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'gespraeche' => 1,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "geloescht": {
    "kontakt": 42,
    "gespraeche": 3,
    "dateien": 1
  }
}

Auskunft exportieren

GET/api/v1/kontakte/{id}/export

Alles, was Talkward zu einer Person gespeichert hat (DSGVO Art. 15): Profil, Ereignisse und alle Gespräche mit Nachrichten und internen Notizen, als eine JSON-Datei.

GET Anfrage

curl "https://chat.talkward.app/api/v1/kontakte/42/export" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/42/export', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/kontakte/42/export",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/kontakte/42/export', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "erstellt": "2026-09-29T10:00:00+02:00",
  "kontakt": {
    "id": 42,
    "…": "…"
  },
  "ereignisse": [],
  "gespraeche": [
    {
      "gespraech": {
        "id": 101,
        "…": "…"
      },
      "nachrichten": [
        {
          "id": 5012,
          "…": "…"
        }
      ]
    }
  ]
}

Ereignis melden

POST/api/v1/kontakte/ereignis

Schreibt ein Ereignis in die Zeitleiste der Kontaktseite. Gibt es den Kontakt noch nicht, wird er angelegt. Je Kontakt bleiben die letzten 100 Ereignisse.

Body

mailstringPflicht (eines von beiden)
E-Mail-Adresse (oder telefon)
telefonstringPflicht (eines von beiden)
Telefonnummer (oder mail)
namestringPflicht
Name des Ereignisses, z. B. Bestellung:Abgeschlossen
datenobject
Beliebige Werte zum Ereignis
farbestring
rot, orange, gelb, gruen, blau, lila, rosa, braun, grau oder schwarz

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/kontakte/ereignis" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mail": "nina@example.com",
  "name": "Bestellung:Abgeschlossen",
  "daten": {
    "nummer": "10234",
    "summe": 49.9
  },
  "farbe": "gruen"
}'

const res = await fetch('https://chat.talkward.app/api/v1/kontakte/ereignis', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mail": "nina@example.com",
    "name": "Bestellung:Abgeschlossen",
    "daten": {
      "nummer": "10234",
      "summe": 49.9
    },
    "farbe": "gruen"
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/kontakte/ereignis",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "mail": "nina@example.com",
        "name": "Bestellung:Abgeschlossen",
        "daten": {
            "nummer": "10234",
            "summe": 49.9,
        },
        "farbe": "gruen",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/kontakte/ereignis', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'mail' => 'nina@example.com',
        'name' => 'Bestellung:Abgeschlossen',
        'daten' => [
            'nummer' => '10234',
            'summe' => 49.9,
        ],
        'farbe' => 'gruen',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "kontakt_id": 42,
  "ereignis": {
    "name": "Bestellung:Abgeschlossen",
    "farbe": "gruen",
    "…": "…"
  }
}

Webhooks

Mit einem Webhook meldet Talkward Ereignisse sofort an Ihre Adresse. Die Adresse muss mit https:// beginnen und öffentlich erreichbar sein.

Ereignis	Wann
`nachricht_neu`	Ein Kunde schreibt
`nachricht_gesendet`	Eine Antwort von Team, KI oder Automation ist beim Kunden angekommen
`gespraech_neu`	Ein neues Gespräch beginnt
`uebergabe`	Das Gespräch geht an das Team
`erledigt`	Das Gespräch ist erledigt
`wieder_offen`	Ein erledigtes Gespräch ist wieder offen
`zuweisung`	Das Gespräch wird jemandem zugewiesen
`abteilung_zugewiesen`	Das Gespräch geht an eine Abteilung
`tag`	Ein Tag kommt hinzu
`notiz_neu`	Eine interne Notiz kommt dazu
`spam`	Das Gespräch wird als Spam markiert
`meldung_neu`	Eine Meldung über `POST /meldungen` ist eingegangen
`kontakt_neu`	Ein Kontakt entsteht (aus einem Gespräch, von Hand, per Import oder API)
`kontakt_geaendert`	Ein Kontakt wird geändert
`kontakt_geloescht`	Ein Kontakt wird gelöscht

Webhook anlegen

POST/api/v1/webhooks

Die Antwort enthält das geheimnis, mit dem Sie die Signatur jeder Zustellung prüfen. Es wird nur dieses eine Mal gezeigt.

Body

ereignisstringPflicht
Eines der Ereignisse oben
urlstringPflicht
Ihre Adresse, beginnt mit https://
markestring
Nur Ereignisse dieser Marke

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/webhooks" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ereignis": "nachricht_neu",
  "url": "https://example.com/talkward"
}'

const res = await fetch('https://chat.talkward.app/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ereignis": "nachricht_neu",
    "url": "https://example.com/talkward"
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "ereignis": "nachricht_neu",
        "url": "https://example.com/talkward",
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/webhooks', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'ereignis' => 'nachricht_neu',
        'url' => 'https://example.com/talkward',
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "id": "3f2a9c1e-…",
  "ereignis": "nachricht_neu",
  "url": "https://example.com/talkward",
  "marke": null,
  "aktiv": true,
  "erstellt": "2026-09-25T09:00:00+00:00",
  "geheimnis": "Jx8q…"
}

Webhook testen

POST/api/v1/webhooks/{id}/test

Schickt sofort ein signiertes Ereignis test an die Adresse und meldet, was zurückkam. Ohne Wiederholung, gut beim Einrichten.

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/test" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/test",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/test', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "ergebnis": {
    "ok": true,
    "status": 200,
    "dauer_ms": 183
  }
}

Zustellungen ansehen

GET/api/v1/webhooks/{id}/zustellungen

Die letzten Zustellversuche (neueste zuerst, höchstens 50 werden aufbewahrt) mit Status, Dauer und Fehler, dazu was noch auf einen neuen Versuch wartet. So finden Sie heraus, warum Ihr System nichts bekommt.

Query-Parameter

limitinteger
1 bis 50, Vorgabe 20

GET Anfrage

curl "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/zustellungen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/zustellungen', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/zustellungen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c/zustellungen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "webhook": {
    "id": "3f2a9c1e-…",
    "letzter_status": 500,
    "fehler_folge": 2,
    "…": "…"
  },
  "zustellungen": [
    {
      "zustellung": 88,
      "ereignis": "nachricht_neu",
      "versuch": 2,
      "status": 500,
      "dauer_ms": 312,
      "fehler": null,
      "erstellt": "2026-09-29T09:15:00+00:00"
    }
  ],
  "wartend": [
    {
      "zustellung": 88,
      "ereignis": "nachricht_neu",
      "versuche": 2,
      "naechster_versuch": "2026-09-29T09:45:00+00:00"
    }
  ]
}

Webhooks auflisten

GET/api/v1/webhooks

Alle Webhooks dieses Schlüssels.

GET Anfrage

curl "https://chat.talkward.app/api/v1/webhooks" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/webhooks', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/webhooks', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "webhooks": [
    {
      "id": "3f2a9c1e-…",
      "ereignis": "nachricht_neu",
      "url": "https://example.com/talkward",
      "marke": null,
      "aktiv": true
    }
  ]
}

Webhook löschen

DEL/api/v1/webhooks/{id}

Beendet den Webhook sofort.

DEL Anfrage

curl -X DELETE "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.delete(
    "https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('DELETE', 'https://chat.talkward.app/api/v1/webhooks/3f2a9c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true
}

Beispiel-Nutzlasten

GET/api/v1/webhooks/beispiele

Nutzlasten, wie sie Ihr Webhook bekäme, gebaut aus Ihren echten Gesprächen. Praktisch zum Einrichten in Make, Zapier oder n8n.

Query-Parameter

ereignisstring
Ereignis, Vorgabe nachricht_neu
limitinteger
1 bis 10, Vorgabe 3

GET Anfrage

curl "https://chat.talkward.app/api/v1/webhooks/beispiele?ereignis=nachricht_neu&limit=3" \
  -H "Authorization: Bearer $TALKWARD_API_KEY"

const res = await fetch('https://chat.talkward.app/api/v1/webhooks/beispiele?ereignis=nachricht_neu&limit=3', {
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
  },
});
const daten = await res.json();

import os, requests

res = requests.get(
    "https://chat.talkward.app/api/v1/webhooks/beispiele",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    params={
        "ereignis": "nachricht_neu",
        "limit": 3,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('GET', 'https://chat.talkward.app/api/v1/webhooks/beispiele', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'query' => [
        'ereignis' => 'nachricht_neu',
        'limit' => 3,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "beispiele": [
    {
      "id": 88,
      "ereignis": "nachricht_neu",
      "zeit": "2026-09-25T09:14:00+00:00",
      "gespraech": {
        "…": "…"
      },
      "nachricht": {
        "…": "…"
      }
    }
  ]
}

Zustellung und Signatur

Talkward schickt jedes Ereignis als POST mit JSON:

JSON

{
  "id": 88,
  "ereignis": "nachricht_neu",
  "zeit": "2026-09-25T09:14:00+00:00",
  "gespraech": {
    "id": 101,
    "…": "…"
  },
  "nachricht": {
    "id": 5012,
    "von": "kunde",
    "text": "Wo bleibt meine Bestellung?",
    "…": "…"
  }
}

Je nach Ereignis kommen dazu: nachricht (bei nachricht_neu, nachricht_gesendet und notiz_neu), zugewiesen (Login, bei zuweisung), abteilung (bei abteilung_zugewiesen), tags_neu (bei tag), vorher und grund (bei uebergabe, erledigt, wieder_offen und spam), meldung (bei meldung_neu). Die drei Kontakt-Ereignisse tragen statt gespraech den kontakt, so wie er beim Ereignis war (bei kontakt_geloescht also vor dem Löschen).

Jede Zustellung trägt die Kopfzeilen X-Talkward-Ereignis, X-Talkward-Zustellung (eindeutige Nummer) und X-Talkward-Signatur. Die Signatur ist sha256= gefolgt vom HMAC-SHA256 des Bodys mit dem geheimnis aus der Antwort beim Anlegen. So prüfen Sie, dass die Meldung von Talkward kommt:

PYTHON

import hashlib, hmac
erwartet = "sha256=" + hmac.new(geheimnis.encode(), body_bytes, hashlib.sha256).hexdigest()
echt = hmac.compare_digest(erwartet, request.headers["X-Talkward-Signatur"])

Antworten Sie innerhalb von 10 Sekunden mit einem Status 2xx. Sonst versucht Talkward es nach 1, 5 und 30 Minuten und nach 2 Stunden erneut. Antworten Sie mit 410, beendet Talkward den Webhook sofort; nach 50 Fehlschlägen in Folge ebenfalls. Aktive Webhooks sehen und beenden Sie auch unter Einstellungen › Erweiterungen › API.

Team-Chat und Meldungen

Nachricht in einen Team-Kanal

POST/api/v1/team/nachricht

Ihr System schreibt als Bot in einen Kanal des Team-Chats. Alle Mitglieder bekommen eine Mitteilung in der Talkward-App. Den Kanal gibt es vorher im Team-Chat. Die Antwort nennt geraete, die Zahl der Geräte, die die Mitteilung bekommen haben. Dieselbe Meldung nimmt Talkward weiterhin unter POST https://chat.talkward.app/api/integration/nachricht an.

Body

kanalstringPflicht
Name des Kanals, z. B. qm
textstringPflicht
Text der Meldung
titelstring
Überschrift der Mitteilung
linkstring
Ein Tipp auf die Mitteilung öffnet diese Seite
dringendboolean
true erreicht auch stumm geschaltete Mitglieder

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/team/nachricht" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kanal": "qm",
  "titel": "Wiegung fällig",
  "text": "Charge 4711 wiegen",
  "dringend": true
}'

const res = await fetch('https://chat.talkward.app/api/v1/team/nachricht', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kanal": "qm",
    "titel": "Wiegung fällig",
    "text": "Charge 4711 wiegen",
    "dringend": true
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/team/nachricht",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "kanal": "qm",
        "titel": "Wiegung fällig",
        "text": "Charge 4711 wiegen",
        "dringend": True,
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/team/nachricht', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'kanal' => 'qm',
        'titel' => 'Wiegung fällig',
        'text' => 'Charge 4711 wiegen',
        'dringend' => true,
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "geraete": 4
}

Meldung von Maschinen, Sensoren und Servern

POST/api/v1/meldungen

Ihr System meldet ein Ereignis, zum Beispiel einen Maschinenausfall, einen Wassersensor oder einen Serverausfall. Jede Meldung wird ein Gespräch im Kanal „Meldung“ und startet Automationen mit dem Auslöser „Meldung über die API“. Ob daraus ein kritischer Alarm wird, legen Sie in der Automation fest (Erweiterung Kritische Alarme). Talkward ist keine zertifizierte Alarmanlage und keine Notrufzentrale.

Body

titelstringPflicht
Kurzer Titel, höchstens 200 Zeichen
textstring
Beschreibung
quellestring
Gerät oder System, z. B. Wassersensor Lager; Vorgabe ist der Name des Schlüssels
schwerestring
info, warnung (Vorgabe) oder kritisch
schluesselstring
Meldungen derselben quelle mit gleichem Schlüssel landen im selben offenen Gespräch
markestring
Marke (key); ohne Angabe die erste Marke
datenobject
Werte für die Automation, dort als {{ereignis.daten.NAME}}

POST Anfrage

curl -X POST "https://chat.talkward.app/api/v1/meldungen" \
  -H "Authorization: Bearer $TALKWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "titel": "Wasser im Keller",
  "quelle": "Wassersensor Lager",
  "schwere": "kritisch",
  "schluessel": "keller",
  "daten": {
    "pegel_cm": 3
  }
}'

const res = await fetch('https://chat.talkward.app/api/v1/meldungen', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TALKWARD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "titel": "Wasser im Keller",
    "quelle": "Wassersensor Lager",
    "schwere": "kritisch",
    "schluessel": "keller",
    "daten": {
      "pegel_cm": 3
    }
  }),
});
const daten = await res.json();

import os, requests

res = requests.post(
    "https://chat.talkward.app/api/v1/meldungen",
    headers={"Authorization": f"Bearer {os.environ['TALKWARD_API_KEY']}"},
    json={
        "titel": "Wasser im Keller",
        "quelle": "Wassersensor Lager",
        "schwere": "kritisch",
        "schluessel": "keller",
        "daten": {
            "pegel_cm": 3,
        },
    },
)
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$res = $client->request('POST', 'https://chat.talkward.app/api/v1/meldungen', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('TALKWARD_API_KEY')],
    'json' => [
        'titel' => 'Wasser im Keller',
        'quelle' => 'Wassersensor Lager',
        'schwere' => 'kritisch',
        'schluessel' => 'keller',
        'daten' => [
            'pegel_cm' => 3,
        ],
    ],
]);
echo $res->getBody();

Antwort 200

{
  "ok": true,
  "neu": true,
  "gespraech": {
    "id": 130,
    "kanal": "meldung",
    "…": "…"
  }
}