COD CRM Customer Management

Customer Management Skill

This skill helps you effectively manage customer records in the COD (Cash on Delivery) CRM system for Algerian e-commerce operations.

When to Use This Skill

Use this skill whenever the user needs to:

• Search for customers by name, phone, wilaya, group, or tag
• Create new customer profiles
• Update existing customer information
• Look up a customer by their phone number
• View a customer's order history
• Check which groups or tags a customer belongs to
• Delete customer records (with safety checks)

Core Concepts

Algerian Context

This CRM is designed for Algerian e-commerce, so understanding the local context is important:

• Phone Numbers: Algerian mobile numbers follow the format 0[5-7]XXXXXXXX (10 digits starting with 05, 06, or 07)
• Wilayas: Algeria has 58 administrative divisions (wilayas), numbered 1-58. Each customer must be assigned to a wilaya.
• Communes: Subdivisions within wilayas. These are optional but help with delivery routing.

Customer Data Structure

Each customer record contains:

• Basic info: name, phone (required), phone2 (optional)
• Location: wilayaId (1-58, required), communeId (optional), address (optional)
• Metrics: totalOrders, totalSpent, lastOrderAt (auto-calculated)
• Relationships: groups (for segmentation), tags (for categorization)

Available Tools

You have access to 8 customer management tools. Here's how to use them effectively:

1. listCustomers - Discovery and Search

Use this when the user wants to browse customers or find multiple matches.

Good for:

• "Show me all customers in Algiers" (wilayaId: 16)
• "Find customers in the VIP group"
• "Search for customers named Ahmed"
• "List customers with the 'high-value' tag"

Parameters:

• wilayaId: Filter by wilaya (1-58)
• search: Search in name or phone (partial match works)
• groupId: Filter by customer group UUID
• tagId: Filter by customer tag UUID
• limit: Max results (default 50, max 100)
• offset: For pagination

Example:

{
  "wilayaId": 16,
  "search": "ahmed",
  "limit": 20
}

What you get back: A list with basic info: id, name, phone, wilaya, commune, totalSpent, totalOrders, lastOrderAt

2. getCustomerDetails - Full Profile

Use this when you need complete information about a specific customer.

Good for:

• "Show me everything about customer X"
• "What's the full profile for this customer?"
• Getting address details and recent orders

Parameters:

• customerId: The UUID of the customer

What you get back: Full customer record plus their 10 most recent orders

3. findCustomerByPhone - Quick Lookup

Use this for fast phone-based lookups. This is often the most natural way to find a customer since phone numbers are unique identifiers.

Good for:

• "Find the customer with phone 0551234567"
• "Look up 0661234567"
• When a user provides a phone number in any context

Parameters:

• phone: Algerian phone number (0[5-7]XXXXXXXX)

Pro tip: If the user gives you a phone number in any format, normalize it first. Remove spaces, dashes, or country codes (+213). The format must be exactly 10 digits starting with 05, 06, or 07.

4. createNewCustomer - Registration

Use this to register new customers in the system.

Required fields:

• name: Full name
• phone: Primary phone (must be unique, format: 0[5-7]XXXXXXXX)
• wilayaId: Number from 1-58

Optional fields:

• phone2: Secondary phone
• communeId: UUID of the commune
• address: Full address string

Important validations:

• Phone numbers must match the Algerian format exactly
• wilayaId must be between 1 and 58
• The phone number must not already exist in the system

Error handling: If you get a duplicate phone error, suggest using findCustomerByPhone to retrieve the existing record instead.

Example:

{
  "name": "Ahmed Benali",
  "phone": "0551234567",
  "wilayaId": 16,
  "address": "123 Rue Didouche Mourad, Alger Centre"
}

5. updateCustomerProfile - Modifications

Use this to update existing customer information. Only include fields you want to change.

Parameters:

• customerId: UUID of the customer to update
• updates: Object with fields to modify

Updatable fields:

• name: New name
• phone: New primary phone
• phone2: New secondary phone (or null to clear)
• wilayaId: New wilaya (1-58)
• communeId: New commune UUID (or null to clear)
• address: New address (or null to clear)

Important:

• If updating the phone number, it must not be used by another customer
• All validation rules apply (phone format, wilaya range)

Example:

{
  "customerId": "abc-123-def",
  "updates": {
    "address": "New address here",
    "phone2": null  // Clear secondary phone
  }
}

6. getCustomerOrderHistory - Order Tracking

Use this to see all orders placed by a customer.

Good for:

• "Show me all orders from this customer"
• "What has customer X ordered?"
• Checking order patterns or history

Parameters:

• customerId: UUID of the customer

What you get back: List of orders with: id, orderNumber, status, totalPrice, createdAt, wilaya, commune

7. getCustomerMemberships - Segmentation Info

Use this to see which groups and tags are assigned to a customer.

Good for:

• "What groups is this customer in?"
• "Show me this customer's tags"
• Understanding customer segmentation

Parameters:

• customerId: UUID of the customer

What you get back:

• groups: Array of customer groups with details
• tags: Array of customer tags with details
• groupCount: Number of groups
• tagCount: Number of tags

8. deleteCustomer - Removal (Use with Caution)

Use this to permanently delete a customer record. This is a destructive operation with safety checks.

Safety rules:

• Cannot delete customers who have orders
• This is permanent - no undo

Good for:

• Removing test/duplicate records
• Cleaning up customers with no order history

Parameters:

• customerId: UUID of the customer to delete

Error handling: If the customer has orders, the tool will tell you how many. Suggest archiving or tagging instead of deletion.

Common Workflows

Workflow 1: New Customer Registration

When a user wants to add a new customer:

1. Gather required info: name, phone, wilayaId
2. Validate the phone format (0[5-7]XXXXXXXX)
3. Call createNewCustomer with the data
4. If you get a duplicate phone error, use findCustomerByPhone to show the existing record
5. Confirm success and show the new customer ID

Workflow 2: Customer Lookup

When a user asks about a customer:

1. If they provide a phone number: Use findCustomerByPhone first (fastest)
2. If they provide a name: Use listCustomers with search parameter
3. If they provide a customer ID: Use getCustomerDetails directly
4. If multiple matches: Show the list and ask which one they meant