CallRail

通过托管的 OAuth 认证访问 CallRail API。追踪通话、管理追踪号码、分析通话数据，并使用标签进行组织。

快速开始

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

基础 URL

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

将{native-api-path}替换为实际的 CallRail API 端点路径。网关将请求代理到api.callrail.com并自动注入您的 OAuth 令牌。

认证

所有请求都要求在 Authorization 请求头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或在maton.ai
2. 创建账户前往
3. maton.ai/settings

复制您的 API 密钥

在https://ctrl.maton.ai管理您的CallRail OAuth连接

。

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=callrail&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

列出连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'callrail'}).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

创建连接

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

获取连接

{
  "connection": {
    "connection_id": "75364cb9-7116-4367-a707-1113d426f17d",
    "status": "ACTIVE",
    "creation_time": "2026-02-10T09:55:17.574212Z",
    "last_updated_time": "2026-02-10T09:55:34.693801Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "callrail",
    "metadata": {}
  }
}

响应：在浏览器中打开返回的URL

以完成OAuth授权。

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

删除连接

指定连接如果您有多个CallRail连接，请使用Maton-Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/callrail/v3/a.json')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '75364cb9-7116-4367-a707-1113d426f17d')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

请求头指定要使用哪一个：

如果省略，网关将使用默认的（最早创建的）活跃连接。

API参考

URL模式

/callrail/v3/a/{account_id}/{resource}.json

所有CallRail API端点都遵循此模式：账户ID以ACC开头，公司ID以呼叫ID以CAL开头，追踪器ID以TRK开头，用户ID以

USR

开头。

GET /callrail/v3/a.json

账户

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 1,
  "accounts": [
    {
      "id": "ACC019c46b8a0807fbdb81c8bf12af91cb3",
      "name": "My Account",
      "numeric_id": 518664017,
      "inbound_recording_enabled": false,
      "outbound_recording_enabled": false,
      "hipaa_account": false,
      "created_at": "2026-02-10 03:43:50 -0500"
    }
  ]
}

列出账户

GET /callrail/v3/a/{account_id}.json

响应：

获取账户

GET /callrail/v3/a/{account_id}/companies.json

公司

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 1,
  "companies": [
    {
      "id": "COM019c46b8a26376a9a4f29671dcdd49e9",
      "name": "My Company",
      "status": "active",
      "time_zone": "America/Los_Angeles",
      "created_at": "2026-02-10T08:43:51.280Z",
      "callscore_enabled": false,
      "lead_scoring_enabled": true,
      "callscribe_enabled": true
    }
  ]
}

列出公司

GET /callrail/v3/a/{account_id}/companies/{company_id}.json

响应：

获取公司

GET /callrail/v3/a/{account_id}/calls.json

呼叫

响应：

{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 1,
  "calls": [
    {
      "id": "CAL019c46b9fc277a7881e3728fea20869b",
      "answered": false,
      "customer_name": "John Doe",
      "customer_phone_number": "+18886757190",
      "direction": "inbound",
      "duration": 36,
      "recording": "https://api.callrail.com/v3/a/.../recording",
      "recording_duration": 36,
      "start_time": "2026-02-10T00:45:19.781-08:00",
      "tracking_phone_number": "+18017846712",
      "voicemail": true
    }
  ]
}

获取通话

GET /callrail/v3/a/{account_id}/calls/{call_id}.json

更新通话

PUT /callrail/v3/a/{account_id}/calls/{call_id}.json
Content-Type: application/json

{
  "customer_name": "John Smith",
  "note": "Follow up scheduled",
  "lead_status": "good_lead",
  "spam": false
}

可更新字段：

呼叫摘要

GET /callrail/v3/a/{account_id}/calls/summary.json

获取指定日期范围内的聚合呼叫统计信息。

查询参数：

响应：

{
  "start_date": "2026-02-03T00:00:00-0800",
  "end_date": "2026-02-10T23:59:59-0800",
  "time_zone": "Pacific Time (US & Canada)",
  "total_results": {
    "total_calls": 42
  }
}

通话时间序列

GET /callrail/v3/a/{account_id}/calls/timeseries.json

获取通话数据随时间变化的情况，用于图表和图形。

响应：

{
  "start_date": "2026-02-03T00:00:00-0800",
  "end_date": "2026-02-10T23:59:59-0800",
  "data": [
    {"key": "2026-02-03", "date": "2026-02-03", "total_calls": 5},
    {"key": "2026-02-04", "date": "2026-02-04", "total_calls": 8}
  ]
}

追踪器（追踪号码）

列出追踪器

GET /callrail/v3/a/{account_id}/trackers.json

响应：

{
  "page": 1,
  "per_page": 100,
  "total_records": 1,
  "trackers": [
    {
      "id": "TRK019c46b9f18174d68bb8d7985260a11f",
      "name": "Google My Business",
      "type": "source",
      "status": "active",
      "destination_number": "+18019234886",
      "tracking_numbers": ["+18017846712"],
      "sms_supported": true,
      "sms_enabled": true,
      "company": {
        "id": "COM019c46b8a26376a9a4f29671dcdd49e9",
        "name": "My Company"
      },
      "source": {"type": "google_my_business"},
      "call_flow": {
        "type": "basic",
        "recording_enabled": true,
        "destination_number": "+18019234886"
      }
    }
  ]
}

获取追踪器

GET /callrail/v3/a/{account_id}/trackers/{tracker_id}.json

标签

列出标签

GET /callrail/v3/a/{account_id}/tags.json

响应：

{
  "page": 1,
  "per_page": 100,
  "total_records": 6,
  "tags": [
    {
      "id": 7886733,
      "name": "Schedule requested",
      "tag_level": "account",
      "color": "orange3",
      "background_color": "gray1",
      "company_id": null,
      "status": "enabled"
    },
    {
      "id": 7886728,
      "name": "Opportunity",
      "tag_level": "company",
      "color": "gray1",
      "company_id": "COM019c46b8a26376a9a4f29671dcdd49e9",
      "status": "enabled"
    }
  ]
}

创建标签

POST /callrail/v3/a/{account_id}/tags.json
Content-Type: application/json

{
  "name": "New Tag",
  "tag_level": "account",
  "color": "blue1"
}

标签级别：

• 账户- 可供账户内所有公司使用
• 公司- 特定于一家公司（需要公司ID）

颜色： 灰色1、蓝色1、蓝色2、绿色1,绿色2,橙色1,橙色2,橙色3,红色1, 等。

更新标签

PUT /callrail/v3/a/{account_id}/tags/{tag_id}.json
Content-Type: application/json

{
  "name": "Updated Tag Name",
  "color": "green1"
}

删除标签

DELETE /callrail/v3/a/{account_id}/tags/{tag_id}.json

用户

列出用户

GET /callrail/v3/a/{account_id}/users.json

响应：

{
  "page": 1,
  "per_page": 100,
  "total_records": 1,
  "users": [
    {
      "id": "USR019c46b8a0557b2e85e5e1c651452509",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "role": "admin",
      "accepted": true,
      "created_at": "2026-02-10T03:43:50.798-05:00",
      "companies": [
        {"id": "COM...", "name": "My Company"}
      ]
    }
  ]
}

获取用户

GET /callrail/v3/a/{account_id}/users/{user_id}.json

集成

列出集成

GET /callrail/v3/a/{account_id}/integrations.json?company_id={company_id}

注意： company_id是必需的。

通知

列出通知

GET /callrail/v3/a/{account_id}/notifications.json

分页

CallRail 使用基于偏移量的分页：

GET /callrail/v3/a/{account_id}/calls.json?page=2&per_page=50

响应包括：

{
  "page": 2,
  "per_page": 50,
  "total_pages": 10,
  "total_records": 487,
  "calls": [...]
}

参数：

• page- 页码（默认值：1）
• per_page- 每页结果数（默认值：100，最大值：250）

对于通话端点，您还可以使用相对分页：

GET /callrail/v3/a/{account_id}/calls.json?relative_pagination=true

这会返回next_pageURL 和has_next_page布尔值，用于高效分页大型数据集。

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/callrail/v3/a/{account_id}/calls.json',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();
console.log(data.calls);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/callrail/v3/a/{account_id}/calls.json',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'per_page': 50, 'date_range': 'last_30_days'}
)
data = response.json()
for call in data['calls']:
    print(f"{call['customer_name']}: {call['duration']}s")

速率限制

超过限制会返回 HTTP 429。重试时请实现指数退避。

备注

• 账户ID以ACC
• 开头公司ID以
• COM开头
• 通话ID以CAL
• 开头追踪器ID以
• TRK开头
• 用户ID以
• USR
• 开头所有端点均以.json
• 结尾通信记录保留25个月或其他命令时，某些shell环境中$MATON_API_KEY可能无法正确展开

错误处理

故障排除：API密钥问题

1. 请检查MATON_API_KEY环境变量已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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

故障排除：无效的应用名称

1. 确保您的URL路径以callrail开头。例如：

• 正确示例：https://gateway.maton.ai/callrail/v3/a.json
• 错误示例：https://gateway.maton.ai/v3/a.json

资源

• CallRail API文档
• CallRail帮助中心 - API
• CallRail API速率限制
• Maton社区
• Maton支持