Twynko per API steuern

Mit der Twynko-API verbindest du Twynko mit deinen anderen Programmen, zum Beispiel n8n, Make, Zapier, deinem Shop oder CRM. Damit legst du automatisch Kontakte an, setzt Tags und Merkmale (z.B. „Kunde“ oder eine Bestellnummer), listest deine Flows auf und startest sie. Die API steuert deine Automationen, sie baut keine Flows. Flows erstellst du weiterhin im Editor.

Den Rückweg, also Daten von Twynko an deinen Shop oder dein CRM, übernimmt der Flow-Baustein „An Webhook senden“, siehe Beitrag „Daten an einen Webhook senden“. Damit bekommt dein System auch die Instagram-ID eines Kontakts, mit der du ihn danach über die API ansprichst.

Der API-Zugang ist ab dem Pro-Tarif verfügbar. Im Free-Tarif siehst du unter Einstellungen nur den Hinweis zum Upgrade. Den API-Bereich sieht außerdem nur der Inhaber des Kontos.

1. API-Key erstellen

1. 1
   API-Bereich öffnen

   Geh in Einstellungen und öffne den Tab „API“.
2. 2
   Key anlegen

   Klick auf „Key erstellen“ und gib ihm einen Namen, z.B. „Zapier“.
3. 3
   Sofort kopieren

   Dein Key (beginnt mit twk_) wird genau einmal angezeigt. Kopiere ihn direkt, wir speichern nur einen verschlüsselten Hash. Verlierst du ihn, erstellst du einfach einen neuen. Nicht mehr benötigte Keys deaktivierst du jederzeit über „Widerrufen“.

2. So rufst du die API auf

Jede Anfrage geht an die Basis-Adresse und braucht deinen Key im Header. Ein erster Test prüft Key und Tarif gleichzeitig:

Basis-URL:  https://api.twynko.de/api/v1
Header:     Authorization: Bearer twk_dein-key

curl -H "Authorization: Bearer twk_dein-key" \
  https://api.twynko.de/api/v1/me

Die Antwort sieht so aus:

{ "organization_id": "...", "tier": "pro",
  "plan_status": "active", "rate_limit_hourly": 1000 }

Wie viele Anfragen sind erlaubt? Pro Stunde und Key, gestaffelt nach Tarif: Pro 1.000, Super 5.000, Ultra 15.000. Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Bei Überschreitung kommt 429.

3. Kontakte ansprechen

Kontakte werden über ihre Instagram-User-ID (ig_user_id) angesprochen, die Zahl, die Instagram dem Kontakt gibt, nicht Twynkos interne ID.

4. Tags

Ein Tag, das es schon gibt, setzt du in jedem Tarif. Schickst du einen neuen Namen, legt Twynko das Tag dabei an. Das zählt gegen die Tag-Grenze deines Tarifs, genau wie in der Oberfläche: Pro 0, Super 20, Ultra unbegrenzt. Ist die Grenze erreicht, antwortet die API mit 403 tag_limit_reached und der Kontakt bleibt unverändert.

5. Merkmale (Custom Fields)

Merkmale sind typisierte Zusatzfelder (text, number, boolean, date). Anders als Tags muss ein Merkmal erst angelegt sein, bevor du einen Wert setzt, im UI unter „Merkmale“ oder per API. Auch hier gilt die Grenze deines Tarifs: Pro 0, Super 10, Ultra unbegrenzt. Darüber kommt 403 custom_field_limit_reached.

6. Beispiel: Kauf im Shop

Der typische Shop-Fall ist „Kauf → Tag setzen“: Nach einer Bestellung bekommt der Kontakt das Tag kunde. Später erkennt dein Flow daran, wer schon gekauft hat, und du findest alle Käufer im Posteingang. Tags gibt es ab dem Super-Tarif, leg kunde am besten vorher unter „Tags“ an.

curl -X POST \
  -H "Authorization: Bearer twk_dein-key" \
  -H "Content-Type: application/json" \
  -d '{"tag":"kunde"}' \
  https://api.twynko.de/api/v1/subscribers/<ig_user_id>/tags

Warum kein Danke-Flow direkt nach dem Kauf? Eine DM darf nur raus, wenn der Kontakt dir in den letzten 24 Stunden geschrieben hat. Zwischen der letzten Nachricht auf Instagram und dem Kauf liegt meist mehr als ein Tag, dann läuft der Flow zwar, aber die Nachricht bleibt liegen. Ein Tag dagegen wird immer gesetzt.

7. Einen Flow starten

Du löst einen veröffentlichten Flow für einen Kontakt aus. Die flow_id holst du dir aus der Liste deiner Flows:

curl -H "Authorization: Bearer twk_dein-key" \
  https://api.twynko.de/api/v1/flows

{ "flows": [ { "id": "<flow-uuid>", "name": "Guide per DM",
    "status": "active", "trigger_type": "comment_post", ... } ] }

Die Liste ist nur zum Lesen: Flows anlegen oder ändern geht per API nicht, das machst du im Editor. Starten kannst du nur Flows mit "status": "active".

curl -X POST \
  -H "Authorization: Bearer twk_dein-key" \
  -H "Content-Type: application/json" \
  -d '{"flow_id":"<flow-uuid>"}' \
  https://api.twynko.de/api/v1/subscribers/<ig_user_id>/trigger-flow

Ob die Nachrichten angekommen sind, steht in delivered: all (alles raus), partial (ein Teil) oder none (nichts). Bei none nennt reason den Grund, meistens outside_24h_window. Das Feld triggered sagt nur, dass der Flow gelaufen ist, nicht, dass eine DM ankam.

{ "triggered": true, "delivered": "none",
  "reason": "outside_24h_window", "flow_id": "...", "ended": true,
  "sends": [ { "kind": "message", "sent": false,
               "reason": "blocked_24h_window" } ] }

8. Häufige Fehlermeldungen

Datenschutz: Gibst du über die API personenbezogene Kontaktdaten an ein anderes System weiter (z.B. ein KI-Tool oder externes CRM), bist du dafür selbst verantwortlich und brauchst ggf. einen eigenen Auftragsverarbeitungsvertrag (AVV) mit dem Anbieter.