home / skills / abdullahbeam / nexus-design-abdullah / hubspot-list-calls

hubspot-list-calls skill

safe

/00-system/skills/hubspot/hubspot-list-calls

This skill lists HubSpot call engagements from your CRM, returning recent call records and optional pagination to empower quick review.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-list-calls

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: hubspot-list-calls
description: "List call engagements from HubSpot CRM. Load when user says 'list calls', 'show calls', 'call history', 'hubspot calls'. Returns logged call records."
---

# List HubSpot Calls

**Specialized skill** for listing call engagements from HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Basic List (default 10 calls)
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_calls.py --json
```

### With Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_calls.py --limit 25 --json
```

### With Pagination
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_calls.py --after "cursor_value" --json
```

---

## Output Format

```json
{
  "results": [
    {
      "id": "14772074448",
      "properties": {
        "hs_call_title": "Discovery Call",
        "hs_call_body": "Discussed requirements and timeline...",
        "hs_call_direction": "OUTBOUND",
        "hs_call_duration": "1800000",
        "hs_call_status": "COMPLETED",
        "hs_timestamp": "2025-12-13T10:00:00Z"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

```
Found {count} calls:

1. Discovery Call
   Direction: Outbound
   Duration: 30 minutes
   Status: Completed
   Date: 2025-12-13 10:00
   Notes: Discussed requirements and timeline...
   ID: 14772074448

2. Follow-up Call
   Direction: Inbound
   ...
```

---

## Call Direction Values

| Value | Meaning |
|-------|---------|
| OUTBOUND | Made call |
| INBOUND | Received call |

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.calls.read` scope |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-log-call` - Log new call
- `hubspot-get-associations` - Get call's linked contacts

Overview

This skill lists call engagements from a HubSpot CRM account and returns the logged call records in a structured format. It provides a paginated JSON output plus a readable display summary showing title, direction, duration, status, date, notes, and ID. Use it to quickly review recent call history or to integrate call data into workflows.

How this skill works

The script queries HubSpot's calls endpoint after a pre-flight config check to verify authentication and scopes. It supports limit and pagination parameters and returns results with properties like title, body, direction, duration, status, and timestamp. Errors such as invalid token, missing scope, or rate limits are surfaced with recommended remedial steps.

When to use it

Review recent call activity for a contact or account
Export or sync call records to another system
Audit call outcomes and durations for reporting
Investigate specific call IDs or timestamps
Programmatically paginate through historical call logs

Best practices

Run the config check before listing to confirm authentication and scopes
Start with a small --limit for quick checks, increase when needed
Use --after cursor for reliable pagination in large datasets
Map hs_call_direction and hs_call_duration to user-friendly values in your UI
Handle 401/403/429 responses with retries and clear user messages

Example use cases

Quickly show the last 10 calls with default command for a sales review
Fetch 25 recent calls for a weekly performance report using --limit 25
Paginate through older calls programmatically with --after cursor values
Integrate results into a dashboard that displays call duration and status trends
Look up a specific call by ID after locating it in the list output

FAQ

What pre-check should I run before using this skill?

Run the config check script to confirm ai_action is proceed_with_operation and authentication scopes are present.

How do I request more than the default number of calls?

Use the --limit option to increase the number of returned calls.

How do I retrieve the next page of results?

Pass the cursor from paging.next.after into the --after parameter to fetch the next page.

What if I get a 403 or 429 error?

403 indicates a missing crm.objects.calls.read scope; update scopes and re-authenticate. 429 means rate limited—wait and retry with backoff.