Pipedrive CRM 集成：管理销售漏斗 - Openclaw Skills

什么是 Pipedrive CRM 集成？

Pipedrive 技能通过 Maton 网关使用托管 OAuth，为与 Pipedrive API 交互提供了一个流线型接口。它允许开发人员将强大的 CRM 能力集成到他们的 AI 智能体中，而无需手动处理令牌刷新或复杂的身份验证流。此集成专为高性能销售环境设计，在这些环境中，对交易漏斗和联系人管理的程序化访问至关重要。

通过利用 Openclaw Skills 库中的此 Pipedrive 集成，您可以以编程方式管理整个销售漏斗。网关架构确保您对原生 Pipedrive API 的请求被安全代理，同时自动注入必要的授权令牌，使构建自动化销售助手和数据同步工具变得前所未有的简单。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/pipedrive-api

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install pipedrive-api

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 pipedrive-api。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Pipedrive CRM 集成 应用场景

• 在 CRM 工作流中自动化潜在客户创建和人员管理。
• 以编程方式跟踪销售交易进度并根据外部触发器更新阶段。
• 调度和管理销售活动，如电话、会议和任务。
• 搜索特定的客户组织或备注，为 AI 智能体提供上下文。
• 在 Pipedrive 与其他外部平台或自定义数据库之间同步销售数据。

Pipedrive CRM 集成 工作原理

1. 开发人员设置 MATON_API_KEY 环境变量以通过 Maton 网关进行身份验证。
2. 通过 Maton 控制面板建立并授权 Pipedrive OAuth 连接。
3. AI 智能体将请求发送到 Maton 网关 URL (https://gateway.maton.ai/pipedrive/...) 而不是原生 API。
4. 网关识别用户并自动将有效的 OAuth 令牌注入请求头。
5. 请求被转发到官方 Pipedrive API，响应以标准 JSON 格式返回给智能体。

Pipedrive CRM 集成 配置指南

要开始使用 Openclaw Skills 的这项技能，请按照以下步骤操作：

1. 登录 maton.ai 并从设置页面获取您的 API 密钥。
2. 设置您的环境变量：

export MATON_API_KEY="YOUR_API_KEY"

3. 创建 Pipedrive 连接以授权 OAuth 访问：

# 使用 Python 发起连接的示例
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'pipedrive'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

4. 在浏览器中打开返回的 URL 以完成 Pipedrive 授权。

Pipedrive CRM 集成 数据架构与分类体系

该技能与 Pipedrive 的原生数据结构交互。以下是核心实体的基本元数据分类：

实体	描述	关键字段
交易 (Deals)	销售机会	title, value, status, stage_id, org_id
人员 (Persons)	联系人信息	name, email[], phone[], visible_to
组织 (Organizations)	公司实体	name, address, visible_to
活动 (Activities)	日历事件/任务	subject, type, due_date, deal_id
备注 (Notes)	记录注释	content, deal_id, person_id
漏斗 (Pipelines)	销售工作流	name, active, order_nr

name: pipedrive
description: |
  Pipedrive API integration with managed OAuth. Manage deals, persons, organizations, activities, and pipelines. Use this skill when users want to interact with Pipedrive CRM. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Pipedrive

Access the Pipedrive API with managed OAuth authentication. Manage deals, persons, organizations, activities, pipelines, and more for sales CRM workflows.

Quick Start

# List deals
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/pipedrive/{native-api-path}

Replace {native-api-path} with the actual Pipedrive API endpoint path. The gateway proxies requests to api.pipedrive.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Pipedrive OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=pipedrive&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'pipedrive'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "pipedrive",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Pipedrive connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Deals

List Deals

GET /pipedrive/api/v1/deals

Query parameters:

• status - Filter by status: open, won, lost, deleted, all_not_deleted
• filter_id - Filter ID to use
• stage_id - Filter by stage
• user_id - Filter by user
• start - Pagination start (default 0)
• limit - Items per page (default 100)
• sort - Sort field and order (e.g., add_time DESC)

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals?status=open&limit=50')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Deal

GET /pipedrive/api/v1/deals/{id}

Create Deal

POST /pipedrive/api/v1/deals
Content-Type: application/json

{
  "title": "New Enterprise Deal",
  "value": 50000,
  "currency": "USD",
  "person_id": 123,
  "org_id": 456,
  "stage_id": 1,
  "expected_close_date": "2025-06-30"
}

Update Deal

PUT /pipedrive/api/v1/deals/{id}
Content-Type: application/json

{
  "title": "Updated Deal Title",
  "value": 75000,
  "status": "won"
}

Delete Deal

DELETE /pipedrive/api/v1/deals/{id}

Search Deals

GET /pipedrive/api/v1/deals/search?term=enterprise

Persons (Contacts)

List Persons

GET /pipedrive/api/v1/persons

Query parameters:

• filter_id - Filter ID
• start - Pagination start
• limit - Items per page
• sort - Sort field and order

Get Person

GET /pipedrive/api/v1/persons/{id}

Create Person

POST /pipedrive/api/v1/persons
Content-Type: application/json

{
  "name": "John Doe",
  "email": ["[email protected]"],
  "phone": ["+1234567890"],
  "org_id": 456,
  "visible_to": 3
}

Update Person

PUT /pipedrive/api/v1/persons/{id}
Content-Type: application/json

{
  "name": "John Smith",
  "email": ["[email protected]"]
}

Delete Person

DELETE /pipedrive/api/v1/persons/{id}

Search Persons

GET /pipedrive/api/v1/persons/search?term=john

Organizations

List Organizations

GET /pipedrive/api/v1/organizations

Get Organization

GET /pipedrive/api/v1/organizations/{id}

Create Organization

POST /pipedrive/api/v1/organizations
Content-Type: application/json

{
  "name": "Acme Corporation",
  "address": "123 Main St, City, Country",
  "visible_to": 3
}

Update Organization

PUT /pipedrive/api/v1/organizations/{id}
Content-Type: application/json

{
  "name": "Acme Corp International"
}

Delete Organization

DELETE /pipedrive/api/v1/organizations/{id}

Activities

List Activities

GET /pipedrive/api/v1/activities

Query parameters:

• type - Activity type (e.g., call, meeting, task, email)
• done - Filter by completion (0 or 1)
• user_id - Filter by user
• start_date - Filter by start date
• end_date - Filter by end date

Get Activity

GET /pipedrive/api/v1/activities/{id}

Create Activity

POST /pipedrive/api/v1/activities
Content-Type: application/json

{
  "subject": "Follow-up call",
  "type": "call",
  "due_date": "2025-03-15",
  "due_time": "14:00",
  "duration": "00:30",
  "deal_id": 789,
  "person_id": 123,
  "note": "Discuss contract terms"
}

Update Activity

PUT /pipedrive/api/v1/activities/{id}
Content-Type: application/json

{
  "done": 1,
  "note": "Completed - customer agreed to terms"
}

Delete Activity

DELETE /pipedrive/api/v1/activities/{id}

Pipelines

List Pipelines

GET /pipedrive/api/v1/pipelines

Get Pipeline

GET /pipedrive/api/v1/pipelines/{id}

Stages

List Stages

GET /pipedrive/api/v1/stages

Query parameters:

• pipeline_id - Filter by pipeline

Get Stage

GET /pipedrive/api/v1/stages/{id}

Notes

List Notes

GET /pipedrive/api/v1/notes

Query parameters:

• deal_id - Filter by deal
• person_id - Filter by person
• org_id - Filter by organization

Create Note

POST /pipedrive/api/v1/notes
Content-Type: application/json

{
  "content": "Meeting notes: Discussed pricing and timeline",
  "deal_id": 789,
  "pinned_to_deal_flag": 1
}

Users

List Users

GET /pipedrive/api/v1/users

Get Current User

GET /pipedrive/api/v1/users/me

Code Examples

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`
};

// List open deals
const deals = await fetch(
  'https://gateway.maton.ai/pipedrive/api/v1/deals?status=open',
  { headers }
).then(r => r.json());

// Create a deal
await fetch(
  'https://gateway.maton.ai/pipedrive/api/v1/deals',
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: 'New Deal',
      value: 10000,
      currency: 'USD'
    })
  }
);

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# List open deals
deals = requests.get(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    params={'status': 'open'}
).json()

# Create a deal
response = requests.post(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    json={
        'title': 'New Deal',
        'value': 10000,
        'currency': 'USD'
    }
)

Notes

• IDs are integers
• Email and phone fields accept arrays for multiple values
• visible_to values: 1 (owner only), 3 (entire company), 5 (owner's visibility group), 7 (entire company and visibility group)
• Deal status: open, won, lost, deleted
• Use start and limit for pagination
• Custom fields are supported via their API key (e.g., abc123_custom_field)
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with pipedrive. For example:

• Correct: https://gateway.maton.ai/pipedrive/api/v1/deals
• Incorrect: https://gateway.maton.ai/api/v1/deals

Resources

• Pipedrive API Overview
• Deals
• Persons
• Organizations
• Activities
• Pipelines
• Stages
• Notes
• Maton Community
• Maton Support