Zipchat Sentiment Report

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

1. 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:

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

Run the bundled script:

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
• Source: Koodit/claude-skill-zipchat
• License: MIT

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