Pipedrive
Agenten starten, wenn sich Deals, Leads, Personen, Organisationen, Aktivitäten oder Notizen in Pipedrive ändern, und ihre Ergebnisse als Notiz festhalten.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | pipedrive |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ pipedrive mit der Firmendomain und dem API-Token eines Nutzers |
| Bridge | Nicht unterstützt |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jedes passende Event startet alle verknüpften Agenten. |
| Während der Pause | Events erhalten 200 und starten keine Runs. Outbound sendet nichts. |
Einrichtung
Öffne in Pipedrive oben rechts deinen Kontonamen, dann Company settings → Personal preferences → API, und kopiere das API-Token. Verbindungen handeln als der Nutzer, dem das Token gehört; siehe API-Token und Nutzer.
Klicke in connic unter Projekt-Settings → Connections auf New connection und wähle Pipedrive. Den Kontozugang kannst du auch im Formular der Verbindung über die Auswahl unter Connection anlegen. Gib einen Name ein, unter Company domain den Teil vor
.pipedrive.comin deiner Pipedrive-Adresse und unter API token das Token. Klicke auf Create connection.Öffne den Agenten. Klicke im Connector Flow für Events zu Datensätzen auf Add inbound connector oder für Notizen auf Add outbound connector. Klicke dann auf Create New Connector und wähle Pipedrive.
Wähle den Modus, Inbound (Record events) oder Outbound (Notes), und unter Connection den Kontozugang. Bei Inbound wählst du außerdem Records und Event. Klicke auf Create. Eine Inbound-Verbindung legt dabei ihren Webhook in Pipedrive an, eine Outbound-Verbindung prüft das API-Token. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.
Konfiguration
Die Felder einer Pipedrive-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Erforderlich | pipedrive. |
| mode | string | Erforderlich | inbound oder outbound. Dashboard: Mode. |
| connection | string | Erforderlich | Inbound und Outbound. Name oder ID eines Pipedrive-Kontozugangs. Dashboard: Connection. |
| config | object | Optional | Einstellungen der Pipedrive-Verbindung. Outbound-Verbindungen haben keine. |
| record_type | string | Optional | Inbound. Die Datensätze, deren Änderungen Runs starten: deal, lead, person, organization, activity oder note. Dashboard: Records.Standard: deal |
| action | string | Optional | Inbound. create, change, delete oder any für alle drei. Dashboard: Event.Standard: create |
| ignore_api_changes | boolean | Optional | Inbound. Überspringt Änderungen über die Pipedrive-API, auch die Notizen deiner Agenten, damit diese keine neuen Runs starten. Schalte es aus, wenn auch Änderungen anderer Integrationen Runs starten sollen. Dashboard: Ignore API changes.Standard: true |
Firmendomain und API-Token gehören zum Kontozugang, nicht zur Verbindung.
Erzeugte Werte
connic setzt diese Werte, wenn du die Verbindung speicherst.
| Wert | Modi | Beschreibung |
|---|---|---|
| Webhook | Inbound | Der Webhook der Verbindung in Pipedrive. connic legt ihn beim Speichern der Verbindung an, du musst ihn also nicht in Pipedrive einrichten. |
| Webhook-Passwort | Inbound | Das Passwort für HTTP Basic Auth, das Pipedrive bei jeder Zustellung mitsendet und connic prüft. |
Agent-Input
Modi: Inbound
Eine Inbound-Verbindung startet einen Run für jeden verknüpften Agenten, sobald ein Datensatz ihres Typs angelegt, geändert oder gelöscht wird, wie es ihr Event vorgibt. Der Run erhält:
{
"event": "deal.create",
"record_type": "deal",
"action": "create",
"record_id": "128",
"title": "Rollout bei Acme",
"url": "https://acme.pipedrive.com/deal/128",
"user_id": "1043",
"change_source": "app",
"conversation_id": "pipedrive:acme/deal/128",
"raw": { ... }
}eventverbindetrecord_typeundaction, alsocreate,changeoderdelete.record_idist die ID des Datensatzes in Pipedrive, bei Leads eine UUID.titleist der Titel des Deals oder Leads, der Name der Person oder Organisation oder der Betreff der Aktivität.urlverlinkt Deals, Leads, Personen und Organisationen in Pipedrive und ist bei gelöschten Datensätzen leer.user_idist der Pipedrive-Nutzer, der die Änderung vorgenommen hat, undchange_sourceistappoderapi.conversation_idbleibt für alle Events eines Datensatzes gleich. Soll dein Agent die früheren Events als Verlauf kennen, setze in seiner YAMLsession.key: input.conversation_id. Von sich aus schaltet der Connector keine Sessions ein.rawenthält den vollständigen Webhook-Payload, so wie Pipedrive ihn gesendet hat:datamit dem Datensatz,previousmit den alten Werten geänderter Felder oder beim Löschen mit dem gelöschten Datensatz, undmetamit den Angaben zum Event.
Stellt Pipedrive dasselbe Event erneut zu, startet kein weiterer Run. Der Inbound-Modus antwortet nicht von selbst: Für eine Notiz verknüpfst du den Agenten mit einer Outbound-Pipedrive-Verbindung, die denselben Kontozugang nutzt; siehe Outbound-Zustellung.
API-Token und Nutzer
Ein API-Token handelt als der Pipedrive-Nutzer, dem es gehört. Notizen deiner Agenten erscheinen unter diesem Nutzer, und der Webhook der Verbindung sendet nur Datensätze, die dieser Nutzer sehen darf. Jeder Nutzer hat ein Token pro Firma. Erstellst du in Pipedrive ein neues, ersetzt es das alte; trag es dann im Kontozugang ein. Ein eigener Pipedrive-Nutzer für deine Agenten hält ihre Notizen von denen echter Personen getrennt.
Ist ignore_api_changes an, starten Änderungen über die Pipedrive-API keine Runs, egal wer sie vornimmt. Dazu gehören die Notizen von Outbound-Verbindungen, so starten sich Agenten nicht selbst.
Pipedrive-Webhook
Modi: Inbound
Beim Speichern einer Inbound-Verbindung legt connic in Pipedrive einen Webhook für ihre Datensätze und ihr Event an. Jede Verbindung hat ihren eigenen Webhook, mehrere Verbindungen können also dieselben Datensätze beobachten, etwa eine pro Environment. Du findest die Webhooks in Pipedrive unter Settings → Tools and apps → Webhooks.
Pipedrive signiert keine Webhooks. connic erzeugt deshalb für jeden Webhook ein Passwort für HTTP Basic Auth und prüft es bei jeder Zustellung. Änderst du Datensätze, Event oder Kontozugang, legt connic einen neuen Webhook an und entfernt den alten. Hat Pipedrive den Webhook gelöscht, legt connic beim nächsten Speichern ebenfalls einen neuen an. Löschst du die Verbindung, entfernt connic ihren Webhook.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-Pipedrive-Verbindung legt bei jeder Nutzung eine Notiz an: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Dabei gilt die erste zutreffende Regel:
- Nennt die Ausgabe oder der Payload
deal_id,lead_id,person_idoderorg_id, gehört die Notiz zu diesen Datensätzen. Eine Notiz kann zu mehreren davon gehören. - Kam der Run über eine Inbound-Pipedrive-Verbindung mit demselben Kontozugang, gehört die Notiz zum Deal, Lead, zur Person oder Organisation, aus der der Run stammt. Bei einer Aktivität oder Notiz ist es der Datensatz, zu dem sie gehört.
- Sonst schlägt die Zustellung fehl, ebenso bei einem Run, den ein gelöschter Datensatz gestartet hat.
Automatische Ausgabe
Eine automatische Verknüpfung hält die finale Ausgabe des Runs fest. Klartext wird zur Notiz. Bei einem JSON-Objekt kommt der Text aus body, text, message, response oder output, in dieser Reihenfolge, und die IDs der Datensätze lassen sich mitgeben. Absätze und Zeilenumbrüche des Texts bleiben in der Notiz erhalten.
{
"body": "Acme nutzt heute 40 Lizenzen und hat nach SSO gefragt.\n\nNächster Schritt: Sicherheitsübersicht bis Freitag schicken."
}Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt body, Pflicht und nicht leer, und optional deal_id, lead_id, person_id und org_id. IDs von Leads sind UUIDs, die anderen ganze Zahlen. Andere Felder werden abgelehnt.
{
"body": "Folgetermin für Donnerstag vereinbart.",
"deal_id": 128
}Zustellung und Wiederholungen
Bremst Pipedrive eine Notiz per Rate Limit aus, wartet connic und sendet erneut. Die Runs der Verbindung zeigen jede Zustellung mit der ID der Notiz und ihren Datensätzen oder mit dem Fehler.
Limits und Fehler
| Limit | Wert |
|---|---|
| Antwort an Pipedrive | Pipedrive wartet 10 Sekunden auf eine Antwort. connic antwortet sofort und startet die Agenten danach. |
| Fehlgeschlagene Zustellungen | Pipedrive versucht eine Zustellung dreimal erneut, nach 3, 30 und 150 Sekunden. |
| Gesperrter Webhook | Nach 10 Zustellungen, die schon beim ersten Versuch scheitern, sperrt Pipedrive den Webhook für 30 Minuten. Events aus dieser Zeit gehen verloren. |
| Gelöschter Webhook | Pipedrive löscht einen Webhook, der 3 Tage in Folge keine erfolgreiche Zustellung hatte. Speichere die Verbindung erneut, dann legt connic einen neuen an. |
| Webhooks pro Nutzer | 40 je Pipedrive-Nutzer. Dazu zählt jede Inbound-Verbindung, die das API-Token dieses Nutzers verwendet. |
| API-Anfragen | Pipedrive begrenzt die Anfragen pro API-Token und Tag, je nach Tarif. Bremst Pipedrive eine Notiz per Rate Limit aus, wartet connic und sendet erneut. |
| Länge einer Notiz | Etwa 100.000 Zeichen. |
Anfragen mit fehlenden oder falschen Zugangsdaten erhalten 401. Eine Verbindung lässt sich nicht speichern, wenn Pipedrive die Firmendomain oder das API-Token ablehnt oder der Nutzer des Tokens keinen weiteren Webhook anlegen darf. Eine Zustellung schlägt fehl, wenn Pipedrive die Notiz ablehnt, etwa weil der Datensatz nicht existiert oder der Nutzer des Tokens ihn nicht sehen darf.