Schnellstart

Du brauchst dafür weniger als 5 Minuten. Du liest nur Daten. Es wird nichts geändert und keine Nachricht gesendet. Es funktioniert mit einem leeren Konto.

#Bevor du anfängst

• Du hast ein SmartChat Konto und kannst dich in der App unter https://app.smartchat.marketing anmelden.
• Du bist Admin des Kontos. Nur Admins können API-Schlüssel anlegen. Wenn du es nicht bist, bitte einen Admin darum.
• Du hast ein Terminal mit curl. Für die Python-Beispiele brauchst du Python 3 und das Paket requests (pip install requests). Für die TypeScript-Beispiele brauchst du Node.js 18 oder neuer.

#1. Einen Schlüssel mit der Stufe Read anlegen

1. Melde dich in der App unter https://app.smartchat.marketing an.
2. Öffne Einstellungen, dann Integrationen, dann API-Schlüssel, und wähle Neuen Schlüssel anlegen.
3. Gib dem Schlüssel einen Namen, zum Beispiel Quickstart. Wähle die Stufe Read (sie ist vorangehakt).
4. Wähle Schlüssel anlegen und kopiere den Schlüssel. Du siehst ihn nur einmal. Ein Schlüssel beginnt mit sc_live_.

Du kannst einen Schlüssel auch im Chat der SmartChat AI anlegen: Die AI wählt die Rechte für dich.

Speichere den Schlüssel in einer Umgebungsvariable. Schreibe einen Schlüssel nie in Code, in einen Chat oder in eine öffentliche Datei.

export SMARTCHAT_API_KEY="paste-your-key-here"

Füge die ganze Zeile, die du kopiert hast, anstelle von paste-your-key-here ein. Die Zeile muss jetzt mit sc_live_ beginnen. Bekommst du später "401", prüfe das zuerst.

Die Beispiele auf dieser Seite rufen https://api.smartchat.marketing/v1 auf. Arbeitest du gegen eine andere Adresse, ersetze sie.

#2. Die Verbindung prüfen

Dieser Aufruf braucht kein Recht. Er zeigt dein Konto, deinen Schlüssel und seine Rechte.

curl "https://api.smartchat.marketing/v1/me" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/me",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/me", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (200):

{
  "object": "me",
  "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "account": {
    "object": "account",
    "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
    "name": "Casa Olivo"
  },
  "key": {
    "object": "api_key",
    "id": "key_1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6",
    "name": "Quickstart",
    "prefix": "sc_live_ab12"
  },
  "auth_type": "api_key",
  "environment": "live",
  "scopes": [
    "contacts:read",
    "sends:read",
    "inbox:read",
    "templates:read",
    "newsletters:read",
    "followups:read",
    "automations:read",
    "landing:read",
    "ai:settings_read",
    "knowledge:read",
    "media:read",
    "settings:read",
    "webhooks:read",
    "connections:read",
    "stats:read",
    "team:read",
    "account:read"
  ],
  "rate_limits": {
    "read": 120,
    "write": 120,
    "send": 120,
    "bulk": 120,
    "upload": 120
  },
  "api_version": "2026-10-25"
}

Siehst du den Namen deines Kontos, funktioniert der Schlüssel. Bekommst du einen Fehler, sieh dir die Tabelle am Ende dieser Seite an.

#3. Dein Konto ansehen

Dieser Aufruf braucht das Recht account:read (Teil der Stufe Read).

curl "https://api.smartchat.marketing/v1/account/overview?include=setup,credits" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/account/overview",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    params={
        "include": "setup,credits",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/account/overview?include=setup,credits", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (200):

{
  "object": "account_overview",
  "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Casa Olivo",
  "language": "en",
  "created_at": "2026-10-25T09:41:07Z",
  "setup": {
    "whatsapp_connected": true,
    "whatsapp_display_number": "+39 06 1234 5678",
    "test_phone_set": true,
    "business_profile_present": true
  },
  "credits": {
    "balance": 2400
  }
}

#4. Deine Kontakte lesen

Dieser Aufruf braucht das Recht contacts:read (Teil der Stufe Read).

curl "https://api.smartchat.marketing/v1/contacts?query=mia&limit=2" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/contacts",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    params={
        "query": "mia",
        "limit": "2",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.smartchat.marketing/v1/contacts?query=mia&limit=2", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (200):

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
      "name": "Mia Muster",
      "phone": "+4915112345678",
      "email": "mia@example.com",
      "language": "en",
      "status": "unconfirmed",
      "optin_whatsapp": "none",
      "optin_whatsapp_at": null,
      "purpose": "marketing",
      "source": "api",
      "tags": [],
      "tag_details": [],
      "created_at": "2026-10-25T09:41:07Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/contacts"
}

Eine leere Liste ("data": []) ist für ein neues Konto die richtige Antwort. Es ist nichts falsch. Das Beispiel oben sucht nach dem Namen mia; dein Konto antwortet mit deinen eigenen Kontakten.

Kommt bei Schritt 3 oder 4 die Antwort 403, wurde dein Schlüssel mit einzelnen Rechten statt mit der Stufe Read angelegt. Füge account:read und contacts:read hinzu oder lege einen neuen Schlüssel mit der Stufe Read an.

#5. Ansehen, was dein Schlüssel darf

Die Liste scopes in der Antwort von Schritt 2 zeigt die Rechte des Schlüssels. Jeder Aufruf in der API-Referenz nennt das Recht, das er braucht. Siehe alle Rechte.

#Als Nächstes: schreiben, Vorschau, dann senden

1. Um etwas anzulegen oder zu ändern, brauchst du einen Schlüssel mit der Stufe Draft oder höher. Probiere Einen Kontakt anlegen.
2. Eine Vorschau zeigt, wer einen Newsletter bekäme, und sendet nichts: get_newsletter_send_preview.
3. Das Senden von Nachrichten kommt zuletzt. Lies zuerst Sicher senden. Aufrufe, die senden, brauchen den Header Idempotency-Key (warum).
4. Um Bescheid zu bekommen, wenn etwas passiert, richte einen Webhook ein.

#Wenn etwas scheitert

Jede Antwort hat einen Header Request-Id. Gib ihn dem Support, wenn du Hilfe brauchst.