Zum Inhalt springen
ASKO.CLOUDDocs

REST-API

Alle Endpunkte unter /api/v1 mit Beispielen.

Basis-URL: https://coexistence.asko.cloud/api/v1. Alle Antworten sind JSON. Erfolgreiche Antworten enthalten data, Fehler ein error-Objekt (siehe Fehler). Jede Antwort trägt eine X-Request-Id – bitte bei Supportanfragen angeben.

Konto

GET /me – Ihr Kundenkonto und die Berechtigungen des verwendeten Schlüssels.

Nummern

GET /numbers – alle verbundenen Nummern mit connection_status (connected, degraded, disconnected, pending), Qualitätsbewertung, Versandlimit und Synchronisationsstatus.

GET /numbers/{phone_number_id}?refresh=true – eine Nummer; mit refresh=true wird der Live-Status bei Meta abgefragt.

Nachrichten senden

POST /numbers/{phone_number_id}/messages – der Body ist ein Cloud-API-Nachrichtenobjekt; messaging_product setzen wir automatisch.

Text:

{ "to": "491701234567", "type": "text", "text": { "body": "Ihre Bestellung ist unterwegs." } }

Vorlage:

{
  "to": "491701234567",
  "type": "template",
  "template": {
    "name": "bestellung_versendet",
    "language": { "code": "de" },
    "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "4711" }] }]
  }
}

Bild per Link, Antwort auf eine Nachricht:

{ "to": "491701234567", "type": "image", "image": { "link": "https://example.com/bild.jpg" }, "context": { "message_id": "wamid.…" } }

Unterstützte Typen: text, image, audio, video, document, sticker, location, contacts, interactive, template, reaction. Die Antwort enthält die wamid der gesendeten Nachricht; den Zustellstatus erhalten Sie per Webhook (messages → statuses).

POST /numbers/{phone_number_id}/messages/read – { "message_id": "wamid.…", "typing_indicator": true } markiert eine Nachricht als gelesen und zeigt optional „schreibt…“ an.

Medien

POST /numbers/{phone_number_id}/media – multipart/form-data mit Feld file. Liefert { "id": "…" }, die Sie z. B. als image.id senden. Grenzen von Meta: Bilder 5 MB, Audio/Video 16 MB, Dokumente 100 MB, Sticker 500 KB.

GET /numbers/{phone_number_id}/media/{media_id} – lädt eine empfangene Datei herunter (die id steht im Webhook, z. B. messages[0].image.id).

Vorlagen

  • GET /numbers/{id}/templates?status=APPROVED&name=…&limit=…&after=… – Vorlagen des WhatsApp Business Kontos
  • POST /numbers/{id}/templates – neue Vorlage zur Prüfung einreichen (Meta-Format: name, language, category, components)
  • GET /numbers/{id}/templates/{template_id} – Status und ggf. Ablehnungsgrund
  • DELETE /numbers/{id}/templates?name=…[&template_id=…] – Vorlage löschen

Beispiel:

{
  "name": "termin_erinnerung",
  "language": "de",
  "category": "UTILITY",
  "components": [{ "type": "BODY", "text": "Hallo {{1}}, wir erinnern an Ihren Termin am {{2}}.", "example": { "body_text": [["Max", "12.05."]] } }]
}

Synchronisation (Coexistence)

POST /numbers/{id}/sync mit { "type": "contacts" } oder { "type": "history" } – überträgt Kontakte bzw. bis zu sechs Monate Chatverlauf aus der App per Webhook. Nur einmal pro Verbindung und nur innerhalb von 24 Stunden nach dem Verbinden möglich. Ist beim Verbinden bereits ein passender Webhook aktiv, starten beide automatisch.

Unternehmensprofil

GET /numbers/{id}/profile und POST /numbers/{id}/profile mit about, address, description, email, websites (max. 2), vertical.

Webhooks

  • GET /webhooks, POST /webhooks (url, events, phone_number_id, description) – das Geheimnis wird einmalig zurückgegeben
  • GET|PATCH|DELETE /webhooks/{id}
  • POST /webhooks/{id}/rotate-secret – neues Geheimnis
  • POST /webhooks/{id}/test – signiertes Testereignis senden
  • GET /webhooks/{id}/deliveries?status=failed – Zustellprotokoll (nur Metadaten)

POST /connect-links mit optional label, external_ref, redirect_url, expires_in_hours (Standard 168), auto_sync (Standard true) liefert eine url, die Sie an Ihren Kunden schicken können. Nach erfolgreicher Verbindung wird – falls angegeben – zu redirect_url?status=connected&phone_number_id=…&external_ref=… weitergeleitet. GET /connect-links listet den Status, DELETE /connect-links/{id} widerruft einen Link.

Zugangsdaten für direkte Integrationen

GET /numbers/{id}/credentials (Scope credentials:read) liefert das Meta-Zugangstoken, die phone_number_id und die WABA-ID – z. B. für den WhatsApp-Knoten in n8n. Dieser Scope wird nur auf Anfrage freigeschaltet; jeder Abruf wird protokolliert.