# Schnellstart

> Mache deinen ersten API-Aufruf in unter 5 Minuten. Du liest nur, deshalb kann nichts versehentlich geändert oder gesendet werden, und ein leeres Konto funktioniert.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/quickstart/

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.

```bash norun
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**

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

**Python**

```python
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())
```

**TypeScript**

```typescript
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):


```json
{
  "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**

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

**Python**

```python
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())
```

**TypeScript**

```typescript
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):


```json
{
  "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**

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

**Python**

```python
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())
```

**TypeScript**

```typescript
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):


```json
{
  "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](https://docs.smartchat.marketing/de/api/) nennt das Recht, das er braucht. Siehe [alle Rechte](https://docs.smartchat.marketing/de/api/permissions/).

## 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](https://docs.smartchat.marketing/de/guides/create-a-contact/).
2. Eine **Vorschau** zeigt, wer einen Newsletter bekäme, und sendet nichts: [`get_newsletter_send_preview`](https://docs.smartchat.marketing/en/api/reference/newsletters/get_newsletter_send_preview/).
3. Das Senden von Nachrichten kommt zuletzt. Lies zuerst [Sicher senden](https://docs.smartchat.marketing/de/security/). Aufrufe, die senden, brauchen den Header `Idempotency-Key` ([warum](https://docs.smartchat.marketing/de/concepts/idempotency/)).
4. Um Bescheid zu bekommen, wenn etwas passiert, richte einen [Webhook](https://docs.smartchat.marketing/de/guides/set-up-a-webhook/) ein.

## Wenn etwas scheitert

| Du siehst | Code | Was du tun kannst |
|---|---|---|
| 401 | [`authentication_required`](https://docs.smartchat.marketing/de/errors/#authentication_required) | Sende den Header `Authorization: Bearer <key>`. |
| 401 | [`api_key_invalid`](https://docs.smartchat.marketing/de/errors/#api_key_invalid) | Prüfe, ob du den ganzen Schlüssel kopiert hast. |
| 403 | [`insufficient_scope`](https://docs.smartchat.marketing/de/errors/#insufficient_scope) | Dem Schlüssel fehlt ein Recht. Die Antwort nennt es in `required_scope`. Lege einen neuen Schlüssel mit mehr Rechten an. |
| 404 | [`not_found`](https://docs.smartchat.marketing/de/errors/#not_found) | Prüfe die Adresse. |
| 429 | [`rate_limited`](https://docs.smartchat.marketing/de/errors/#rate_limited) | Warte die Sekunden aus dem Header `Retry-After`. |

Jede Antwort hat einen Header `Request-Id`. Gib ihn dem [Support](https://docs.smartchat.marketing/de/support/), wenn du Hilfe brauchst.