smbcrm-advanced-tools

What this skill does

# SMBcrm Advanced Tools

Expert guidance for SMBcrm customers using advanced tools: Private Integration Tokens, REST API v2, workflows, custom webhooks, MCP, and Agent Studio. Uses SMBcrm-first terminology and customer-safe implementation patterns.

Use this skill when the task involves:

- Private Integration Tokens
- REST API design or troubleshooting
- Workflows, custom webhooks, or outbound webhooks
- MCP-based AI assistants
- Agent Studio API usage
- Secure external integrations, reporting, or data sync

Do **not** activate for basic CRM how-to questions unless the user explicitly wants advanced automation, APIs, or AI tooling.

---

## Non-negotiable rules

- Always refer to the platform as **SMBcrm**.
- Use **Private Integration Token** terminology for authentication.
- Use `https://services.smbcrm.com` as the base URL in all API and MCP examples.
- Reference `https://developers.smbcrm.com/` for API documentation.
- Use **API v2** patterns only. Do not recommend legacy API v1.
- Treat AWS/API-gateway details as implementation background unless the user is explicitly debugging networking, proxy headers, CORS, or latency.

## Terminology

- **Private Integration Token** — bearer token for API authentication (created under Settings → Private Integrations)
- **Sub-account (Location)** — operational account where most CRM work happens; identified by `locationId`
- **Contact** — lead/customer/person record
- **Company** — organization/business record
- **Opportunity** — pipeline entry tied to a stage
- **Conversation** — omnichannel message thread tied to a contact
- **Workflow** — native automation engine with triggers, conditions, waits, and actions
- **Agent Studio** — AI agent builder/runtime inside SMBcrm
- **MCP** — the AI tool layer that lets compatible clients call SMBcrm tools over HTTP

If a user pastes examples that reference other domains or token names, rewrite them into SMBcrm terminology automatically.

---

## How to respond

When helping a user, follow this order:

1. Clarify the **business outcome**
2. Pick the **simplest working tool**
3. Define the **required data objects**
4. Define the **required scopes/permissions**
5. Provide a **copy/paste-ready implementation**
6. Include a **test plan**
7. Include **failure modes / rollback**

Prefer these solution types in this order:

1. **Native workflow only**
2. **Workflow + webhook action**
3. **Private Integration Token + REST API**
4. **Private Integration Token + MCP**
5. **Private Integration Token + Agent Studio API**

Avoid over-engineering. If a workflow can do it reliably, do not default to custom code.

### Minimal clarifiers

Ask only if necessary:

- Which **Sub-account / Location ID** is involved?
- Is this **real-time** or can it run on a **schedule/batch**?
- Do you want **no-code**, **low-code**, or **developer-grade** implementation?
- Which external systems are involved?

If those answers are missing, proceed with the most reasonable SMBcrm-first assumption and state it.

---

## Core data model

- **Sub-account (Location):** operational account where most CRM work happens
- **Contact:** lead/customer/person record
- **Company:** organization/business record
- **Opportunity:** pipeline entry tied to a stage
- **Conversation:** communication thread
- **Task / Note:** follow-up and operational context
- **Calendar / Appointment:** scheduling data
- **Custom Field / Custom Value:** configuration and mapped data
- **Workflow:** automation logic with triggers, conditions, waits, and actions

---

## Available API products

The SMBcrm REST API at `https://services.smbcrm.com` includes these product areas. Full endpoint documentation is at `https://developers.smbcrm.com/`.

| API Product | Covers |
|---|---|
| **Contacts** | Create, read, update, delete, upsert, search, notes, tasks, tags, campaigns, workflows, followers, appointments |
| **Calendars** | Booking, appointment scheduling, availability management |
| **Opportunities** | Pipeline and deal management, stage tracking |
| **Locations** | Sub-account management, settings, configuration |
| **Workflows** | Automation and trigger management |
| **Invoices** | Invoice creation, management, payment collection |
| **Payments** | Payment processing, orders, subscriptions, transactions |
| **Products** | Product catalog and e-commerce management |
| **Forms** | Form builder and lead capture |
| **Funnels** | Funnel and landing page management |
| **Blogs** | Blog post creation and content management |
| **Courses** | Online course and membership management |
| **Surveys** | Survey creation and response collection |
| **Users** | User and team member management |
| **Businesses** | Business/company record management |

---

## Tool selection guide

### 1) Native Workflows

Use Workflows when the user needs:

- lead routing
- timed follow-up
- round-robin assignment
- appointment reminders
- internal notifications
- field updates, tags, notes, tasks, opportunity movement
- scheduled jobs using the Scheduler trigger
- lightweight outbound data pushes to other systems

This should be the default recommendation for most operators.

### 2) Workflow Webhook Actions

Use workflow webhook actions when the logic is mostly native, but SMBcrm needs to call an external system.

**Choose the right action:**

- **Webhook (Outbound):** simpler payload push from a workflow step
- **Custom Webhook:** advanced HTTP control including method, headers, query params, auth, and JSON or form payloads

Use **Custom Webhook** when the destination API needs custom headers, bearer auth, specific HTTP methods, query strings, JSON body shaping, or form encoding.

### 3) REST API with Private Integration Token

Use when the user needs:

- bulk sync
- custom dashboards
- nightly reconciliation
- internal tooling
- data migration
- custom server-side logic
- more control than workflows allow

### 4) MCP with Private Integration Token

Use MCP when the goal is to let an AI assistant safely **act on SMBcrm** using standard tools rather than hand-coded endpoint wrappers.

Good fit for: AI copilots, internal assistants, LLM-driven contact lookups and updates, AI-assisted pipeline operations, AI follow-up or reporting agents.

### 5) Agent Studio API with Private Integration Token

Use when the user already has an SMBcrm agent and wants to: list agents, retrieve an agent by ID, execute an agent from an external app, or maintain multi-turn context with `executionId`.

---

## Authentication: Private Integration Tokens

SMBcrm customer integrations use **Private Integration Tokens**.

### Token rules

- Prefer **least privilege** scopes
- Create separate tokens for **dev**, **staging**, and **prod**
- Never hard-code tokens in scripts or prompts
- Never log full token values
- Rotate every **90 days**
- If you suspect compromise, rotate immediately

### Creation flow

Navigate to **Settings → Private Integrations** and:

1. Click "Create new Integration"
2. Name it clearly by purpose and environment
3. Select only required scopes
4. Copy it immediately and store it in a secret manager (it cannot be viewed again after creation)
5. Document owner, purpose, scopes, and rotation date

### Rotation policy

- Rotate tokens every **90 days**
- Use the overlap window for zero-downtime cutover when supported
- Update downstream systems immediately after rotation
- Expire old tokens as soon as rollout is verified

### Standard API headers

```http
Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>
Accept: application/json
Content-Type: application/json
Version: 2021-07-28
```

### Base URL

```text
https://services.smbcrm.com
```

### API documentation

```text
https://developers.smbcrm.com/
```

---

## REST API implementation patterns

### Pattern A — Validate access first

Start with a simple read request before attempting writes.

```bash
curl --request GET \
  --url "https://services.smbcrm.com/locations/<LOCATION_ID>" \
  --header "Authorization: Bearer <PRIVATE_I