WhatsApp - seven.io API

Nutzen Sie diese API zum Versand von WhatsApp-Nachrichten über die WhatsApp Business API (WABA). Sie können Template-Nachrichten, Freitext-Nachrichten, Medien (Bild, Video, Audio, Dokument, Sticker), Standorte, Kontakte und interaktive Nachrichten senden. Reaktionen werden über den Events-Endpunkt gesendet.

Um diesen Endpunkt nutzen zu können, muss Ihr API-Schlüssel den waba-Scope aktiviert haben. Außerdem benötigen Sie eine registrierte WhatsApp Business Absendernummer.

POST/api/waba/messages

Nachricht senden

Senden Sie eine WhatsApp-Nachricht an einen Empfänger. Sie können Template-Nachrichten, Freitext-Nachrichten, Medien (Bild, Video, Audio, Dokument, Sticker), Standorte, Kontakte und interaktive Nachrichten (Buttons, Listen) senden.

Pflichtparameter

Name
from
Type
string
Description
Ihre registrierte WhatsApp Business Absendernummer im internationalen Format (z.B. 4915112345678).
Name
to
Type
string
Description
Empfänger-Rufnummer im internationalen Format (z.B. 4917612345678).

Template-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie template für den Versand einer genehmigten WhatsApp Template-Nachricht.
Name
template
Type
string
Description
Der Name des genehmigten WhatsApp-Templates (z.B. hello_world).
Name
language
Type
string
Description
Sprachcode des Templates (z.B. de, en).
Name
components
Type
object
Optional
Optional
Description
Template-Parameterwerte. Enthält optionale Arrays für header, body und buttons. Die Werte sind positionell und ersetzen {{1}}, {{2}}, usw. im Template.

components

object

Template-Komponenten-Parameter

Name
header
Type
array
Optional
Optional
Description
Werte für Header-Platzhalter. Für Text-Header geben Sie Strings an. Für Bild-Header geben Sie eine URL an.
Name
body
Type
array
Optional
Optional
Description
Werte für Body-Platzhalter. Jeder Eintrag ersetzt die entsprechende {{n}}-Variable.
Name
buttons
Type
array
Optional
Optional
Description
Button-Parameterwerte. Jeder Eintrag ist ein Objekt mit type, sub_type und parameters.

Freitext-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie text oder lassen Sie es weg. Der Nachrichtentext wird innerhalb eines 24-Stunden-Konversationsfensters gesendet.
Name
text
Type
string
Description
Der Nachrichtentext. Kann nur innerhalb eines aktiven 24-Stunden-Konversationsfensters gesendet werden.

Bild-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie image.
Name
url
Type
string
Description
Öffentliche URL der Bilddatei (JPEG, PNG).
Name
caption
Type
string
Optional
Optional
Description
Optionale Beschriftung für das Bild.

Video-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie video.
Name
url
Type
string
Description
Öffentliche URL der Videodatei (MP4, 3GPP).
Name
caption
Type
string
Optional
Optional
Description
Optionale Beschriftung für das Video.

Audio-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie audio.
Name
url
Type
string
Description
Öffentliche URL der Audiodatei (MP3, OGG, AMR, AAC).

Dokument-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie document.
Name
url
Type
string
Description
Öffentliche URL der Dokumentdatei (PDF, DOC usw.).
Name
filename
Type
string
Description
Der dem Empfänger angezeigte Dateiname.
Name
caption
Type
string
Optional
Optional
Description
Optionale Beschriftung für das Dokument.

Sticker-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie sticker.
Name
url
Type
string
Description
Öffentliche URL der Sticker-Datei (WebP). Statische Sticker: 512x512px, max 100KB. Animierte Sticker: 512x512px, max 500KB.

Standort-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie location.
Name
latitude
Type
number
Description
Breitengrad des Standorts.
Name
longitude
Type
number
Description
Längengrad des Standorts.
Name
name
Type
string
Optional
Optional
Description
Name des Standorts.
Name
address
Type
string
Optional
Optional
Description
Adresse des Standorts.

Kontakte-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie contacts.
Name
contacts
Type
array
Description
Array von Kontaktobjekten. Jeder Kontakt muss ein name-Objekt (mit first_name und optionalem last_name) und ein phones-Array (jeweils mit phone und optionalem type: cell, main, iphone, home, work) enthalten.

Interaktive Button-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie interactive.
Name
interactive_type
Type
string
Description
Setzen Sie button.
Name
body
Type
string
Description
Dem Benutzer angezeigter Nachrichtentext.
Name
buttons
Type
array
Description
Array von 2-3 Button-Objekten, jeweils mit id (eindeutiger Bezeichner) und title (Anzeigetext, max 20 Zeichen).
Name
header
Type
string
Optional
Optional
Description
Optionaler Kopfzeilentext.
Name
footer
Type
string
Optional
Optional
Description
Optionaler Fußzeilentext.

Interaktive Listen-Nachricht Parameter

Name
type
Type
string
Description
Setzen Sie interactive.
Name
interactive_type
Type
string
Description
Setzen Sie list.
Name
body
Type
string
Description
Dem Benutzer angezeigter Nachrichtentext.
Name
button_text
Type
string
Description
Text auf dem Listen-Button.
Name
sections
Type
array
Description
Array von Sektionsobjekten, jeweils mit title und rows (Array von Zeilenobjekten mit id, title und optionaler description).
Name
header
Type
string
Optional
Optional
Description
Optionaler Kopfzeilentext.
Name
footer
Type
string
Optional
Optional
Description
Optionaler Fußzeilentext.

Optionale Parameter

Name
delay
Type
timestamp
Optional
Optional
Description
Datum/Zeit für zeitversetzten Versand. Format: JJJJ-MM-TT hh:mm:ss oder Unix-Timestamp.
Name
ttl
Type
integer
Optional
Optional
Description
Gibt die Gültigkeitsdauer der Nachricht in Minuten an. Der Standard liegt bei 2880, also 48 Stunden.
Name
label
Type
string
Optional
Optional
Description
Eigenes Label für Statistiken. Max. 100 Zeichen, erlaubte Zeichen: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Klick- und Performance-Tracking für im Nachrichtentext gefundene URLs aktivieren. Damit wird gleichzeitig der URL-Kürzer aktiviert.
Name
foreign_id
Type
string
Optional
Optional
Description
Ihre eigene ID für diese Nachricht. Wird bei Statusbericht-Callbacks zurückgegeben. Max. 64 Zeichen, erlaubte Zeichen: a-z, A-Z, 0-9, .-_@.

Template-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "hello_world",
      "language": "de"
    }'

Antwort

{
    "success": "100",
    "total_price": 0.0735,
    "balance": 123.45,
    "debug": "false",
    "sms_type": "WA",
    "messages": [
        {
            "id": "12345678",
            "sender": "4915112345678",
            "recipient": "4917612345678",
            "text": "{\"type\":\"template\",\"template\":\"hello_world\",\"language\":\"de\",\"rendered\":{\"body\":\"Hallo Welt!\"}}",
            "encoding": "gsm",
            "label": null,
            "parts": 1,
            "udh": null,
            "is_binary": false,
            "price": 0.0735,
            "channel": "WA",
            "success": true,
            "error": null,
            "error_text": null
        }
    ]
}

Template mit Parametern

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "order_confirmation",
      "language": "de",
      "components": {
        "body": ["Max Mustermann", "ORD-12345"],
        "buttons": [
          {
            "type": "button",
            "sub_type": "url",
            "parameters": [{"type": "text", "text": "ORD-12345"}]
          }
        ]
      }
    }'

Freitext-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "text": "Danke für Ihre Nachricht, wir kümmern uns darum!"
    }'

Bild-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "image",
      "url": "https://example.com/photo.jpg",
      "caption": "Sehen Sie sich dieses Bild an!"
    }'

Video-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "video",
      "url": "https://example.com/video.mp4",
      "caption": "Sehen Sie sich dieses Video an"
    }'

Audio-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "audio",
      "url": "https://example.com/audio.mp3"
    }'

Dokument-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "document",
      "url": "https://example.com/rechnung.pdf",
      "filename": "rechnung.pdf",
      "caption": "Ihre Rechnung"
    }'

Sticker-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "sticker",
      "url": "https://example.com/sticker.webp"
    }'

Standort-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "location",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "name": "Eiffelturm",
      "address": "5 Avenue Anatole France, 75007 Paris"
    }'

Kontakte-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "contacts",
      "contacts": [
        {
          "name": {"first_name": "Max", "last_name": "Mustermann"},
          "phones": [{"phone": "+491234567890", "type": "cell"}]
        }
      ]
    }'

Interaktive Button-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "button",
      "body": "Wie können wir Ihnen helfen?",
      "header": "Support",
      "footer": "Tippen Sie auf einen Button",
      "buttons": [
        {"id": "btn_sales", "title": "Vertrieb"},
        {"id": "btn_support", "title": "Support"},
        {"id": "btn_other", "title": "Sonstiges"}
      ]
    }'

Interaktive Listen-Nachricht

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "list",
      "header": "Unsere Produkte",
      "body": "Durchsuchen Sie unsere Produktkategorien:",
      "footer": "Wählen Sie eine Option",
      "button_text": "Optionen anzeigen",
      "sections": [
        {
          "title": "Elektronik",
          "rows": [
            {"id": "phone_1", "title": "Smartphones", "description": "Neueste Modelle"},
            {"id": "laptop_1", "title": "Laptops", "description": "Business & Gaming"}
          ]
        }
      ]
    }'

Template-Komponenten

Die components-Struktur unterstützt drei optionale Arrays: header, body und buttons. Die Werte sind positionell und ersetzen {{1}}, {{2}}, usw. im Template.

Header-Parameter

Text-Header: Geben Sie String-Werte für Text-Platzhalter an
Bild-Header: Geben Sie eine URL zum Bild an

Body-Parameter

Geben Sie String-Werte an, die {{1}}, {{2}}, usw. im Template-Body ersetzen.

Button-Parameter

Für URL-Buttons mit dynamischen Suffixen geben Sie ein Array von Button-Objekten an:

Name
type
Type
string
Description
Immer button.
Name
sub_type
Type
string
Description
Der Button-Typ, z.B. url.
Name
parameters
Type
array
Description
Array von Parameter-Objekten mit type- und text-Eigenschaften.

Header + Body + Buttons

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "appointment_reminder",
    "language": "de",
    "components": {
        "header": ["Terminbestätigung"],
        "body": ["Max Mustermann", "15.02.2026", "14:00 Uhr", "Dr. Schmidt"],
        "buttons": [
            {
                "type": "button",
                "sub_type": "url",
                "parameters": [{"type": "text", "text": "abc123"}]
            }
        ]
    }
}

Bild-Header + Body

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "product_available",
    "language": "de",
    "components": {
        "header": ["https://example.com/product.jpg"],
        "body": ["Premium Widget"]
    }
}

DELETE/api/waba/messages/{id}

Nachricht löschen

Löschen Sie eine geplante WhatsApp-Nachricht, bevor sie versendet wurde.

Name
id
Type
string
Description
Die ID der zu löschenden Nachricht. Wird als URL-Pfadparameter übergeben.

Bereits versendete Nachrichten können nicht gelöscht werden. WhatsApp unterstützt keinen Nachrichtenrückruf.

Anfrage

DELETE

/api/waba/messages/{id}

curl -X DELETE https://gateway.seven.io/api/waba/messages/12345678 \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL"

Antwort (Erfolg)

{
    "success": true
}

Antwort (bereits gesendet)

{
    "error_code": 400,
    "error_message": "Message already sent. WhatsApp does not support message revocation."
}

Antwort (nicht gefunden)

{
    "code": 404,
    "message": "Page not found",
    "errors": []
}

POST/api/waba/events

Event senden

Senden Sie Konversations-Events wie Lesebestätigungen, Tipp-Indikatoren oder Reaktionen an einen WhatsApp-Kontakt.

Events können nur für Nachrichten der letzten 7 Tage gesendet werden. Ältere Konversationen sind nicht mehr für die Event-Zustellung berechtigt.

Mindestens einer der Parameter to oder msg_id muss angegeben werden, um die Zielkonversation oder Nachricht zu identifizieren.

Lese-/Tipp-Event Parameter

Name
from
Type
string
Description
Ihre registrierte WhatsApp Business Absendernummer.
Name
to
Type
string
Optional
Optional
Description
Empfänger-Rufnummer im internationalen Format. Mindestens to oder msg_id muss angegeben werden.
Name
event
Type
string
Description
Der Event-Typ. Verfügbare Werte: read, is_typing.
Name
msg_id
Type
string
Optional
Optional
Description
Explizite Nachrichten-ID, die als gelesen markiert werden soll. Mindestens to oder msg_id muss angegeben werden.

Reaktions-Event Parameter

Name
event
Type
string
Description
Setzen Sie reaction.
Name
msg_id
Type
string
Description
Die WhatsApp-Nachrichten-ID der Nachricht, auf die reagiert werden soll.
Name
emoji
Type
string
Description
Das Emoji für die Reaktion (z.B. 👍). Senden Sie einen leeren String, um die Reaktion zu entfernen.

Lesebestätigung

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "read"
    }'

Tipp-Indikator

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "is_typing"
    }'

Reaktion

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "reaction",
      "msg_id": "123456789",
      "emoji": "👍"
    }'

Antwort

{
    "success": true
}

Fehlerantwort

{
    "success": false,
    "error_code": 400,
    "error_message": "Invalid WhatsApp sender number"
}

Fehlerantworten

Name
100
Description
Nachricht wurde vom Gateway angenommen und wird versendet.
Name
7002001
Description
Keine aktive Konversation. Freitext-Nachrichten können nur innerhalb eines aktiven 24-Stunden-Konversationsfensters gesendet werden. Verwenden Sie eine Template-Nachricht, um eine Konversation zu starten.
Name
400
Description
Ungültige Anfrage. Kann auf eine ungültige Absendernummer, ungültige Empfängernummer oder andere Validierungsfehler hinweisen.
Name
404
Description
Nachricht nicht gefunden. Die angegebene Nachrichten-ID existiert nicht oder gehört nicht zu Ihrem Account.
Name
900
Description
Authentifizierung ist fehlgeschlagen. Bitte prüfen Sie den in der Authentifizierung verwendeten API-Schlüssel.
Name
902
Description
Der API-Schlüssel hat kein Zugriffsrecht auf diesen Endpunkt. Stellen Sie sicher, dass der waba-Scope aktiviert ist.