# Zipchat Sentiment Report

> Generate a sentiment analysis report from Zipchat conversations for a specific time period. Use this skill whenever someone asks to analyze Zipchat conversations, generate a sentiment report, check customer chat data, understand what customers are asking, or wants insights from Zipchat. Trigger even on casual phrases like "generate the Zipchat report", "analyze the conversations", "how did the ch…

- **Type:** Skill
- **Install:** `agentstack add skill-koodit-claude-skill-zipchat-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Koodit](https://agentstack.voostack.com/s/koodit)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Koodit](https://github.com/Koodit)
- **Source:** https://github.com/Koodit/claude-skill-zipchat/tree/main/skill

## Install

```sh
agentstack add skill-koodit-claude-skill-zipchat-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Zipchat Sentiment Report

Fetches conversations from your Zipchat account for a given date range, analyzes sentiment, and produces a structured report — all directly in the conversation.

## Step 1 — Credentials

Check for credentials in this order:

1. **Environment variables** (preferred):
   - `ZIPCHAT_API_KEY`
   - `ZIPCHAT_CHAT_ID`

2. **User-provided in conversation** — if env vars are not set, ask:
   > "To connect to your Zipchat account I need two things:
   > - **API Key** (find it in your Zipchat dashboard → Settings → Integrations → Backend API)
   > - **Chat ID** (the numeric ID of your chat, visible in the dashboard URL or in the same settings page)"

Once collected, use them for this session only. Never store credentials in files.

## Step 2 — Date range

If the user hasn't specified dates, ask:
> "What time period do you want to analyze? (e.g. 'last week', 'May 2026', or specific dates)"

Convert to ISO 8601 using today's date from the system context:
- "last week" → 7 days ago to today (e.g. today=2026-05-26 → `2026-05-19T00:00:00Z` / `2026-05-26T23:59:59Z`)
- "last month" → last 30 days
- "May 2026" → `2026-05-01T00:00:00Z` / `2026-05-31T23:59:59Z`
- Specific dates → append `T00:00:00Z` / `T23:59:59Z`

Always tell the user the exact period you are fetching before starting.

## Step 3 — Fetch data

Generate a unique temp file path to avoid conflicts with parallel sessions:

```bash
ZIPCHAT_TS=$(date +%s)
DATA_FILE="/tmp/zipchat_data_${ZIPCHAT_TS}.json"
PROGRESS_FILE="/tmp/zipchat_progress_${ZIPCHAT_TS}.txt"
```

Run the bundled script:

```bash
python3 /scripts/fetch_conversations.py \
  "" "" "" "" \
  2>"$PROGRESS_FILE" > "$DATA_FILE"
```

Read `$PROGRESS_FILE` to check how many conversations were found. If 0, warn the user — likely wrong date range or invalid credentials.

Use `$DATA_FILE` throughout the analysis. Delete both temp files after the report is produced.

**Technical note:** The script sets a browser-like User-Agent header. This is required — Zipchat's API sits behind Cloudflare, which blocks Python's default User-Agent.

## Step 4 — Analyze sentiment

Read `$DATA_FILE`. For each conversation, analyze user messages and assign:

- 🟢 **Positive** — satisfied tone, enthusiastic, grateful, productive conversation with a good outcome, high engagement
- 🟡 **Neutral** — informational query with no strong emotional markers, product/info request, neutral tone
- 🔴 **Negative** — frustration, unresolved technical issue, customer leaves, complaint about price/policy, discount not honored

Also consider:
- Conversation length: many messages = high engagement (positive signal)
- Escalation: does **not** automatically mean negative — often neutral or positive
- Final tone: how the conversation ends matters more than how it starts

Classify the **main topic** from the first user message and dominant subject:
- Product info / search
- Size & fit guidance
- Availability / out of stock
- Returns & exchanges
- Technical issues
- Pricing / discounts / promotions
- Shipping
- Orders / tracking
- Other

## Step 5 — Produce the report

Use this exact structure:

---

## Zipchat Sentiment Report
**Period:** [start] – [end] | **Chat ID:** [id] | **Conversations:** [N] | **Total messages:** [M]

### Sentiment Distribution

| Sentiment | Conversations | % |
|-----------|:---:|:---:|
| 🟢 Positive | N | X% |
| 🟡 Neutral | N | X% |
| 🔴 Negative | N | X% |

### Conversation Breakdown

| ID | Date | Msg | Esc | Sentiment | Topic | Notes |
|----|------|:---:|:---:|-----------|-------|-------|
| [id] | DD/MM | N | Yes/No | 🟢/🟡/🔴 | [topic] | [1-line summary] |

*(sort by date ascending)*

### Escalated Conversations

Only if any exist. For each: ID, sentiment, reason for escalation.

### Top Topics

Table with topic, conversation count, percentage.

### Recurring Products / Themes

Group conversations from different users that discuss the **same product or theme**. This is one of the most valuable parts of the report.

For each cluster (minimum 2 conversations):
- Cluster name (e.g. "Summer wool/polypropylene undershirts")
- List of conversations with date and detail
- Pattern observed (what they share, what need or problem emerges)

### Key Insights

Two sections:
- **Watch out** (negative signals / structural issues to fix)
- **What's working** (strengths to preserve)

Max 3-4 bullets per section. Concrete and actionable, not generic.

---

## Operational notes

- For large date ranges (>50 conversations), warn the user the fetch may take a few minutes
- API rate limit: 120 req/60s — the script doesn't explicitly handle it, but normal usage stays well below
- Bot messages may contain HTML (``, ``, etc.) — strip it mentally for sentiment analysis, it's not meaningful
- System greeting messages (e.g. "Hi, I'm [name], how can I help?") don't count toward sentiment
- If a conversation has 0 messages after fetch, it's likely an abandoned session — classify as Neutral, topic "Abandoned session"

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Koodit](https://github.com/Koodit)
- **Source:** [Koodit/claude-skill-zipchat](https://github.com/Koodit/claude-skill-zipchat)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-koodit-claude-skill-zipchat-skill
- Seller: https://agentstack.voostack.com/s/koodit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.