Customers

Customers are automatically created when a new phone number interacts with your WhatsApp account. CubeConnect maintains a customer profile with contact information, tags, and conversation history.

Customer Model

Field	Type	Description
id	integer	Unique customer ID
phone	string	Phone number with country code
name	string	Customer name (from WhatsApp profile)
email	string	Email address (if collected)
metadata	object	Custom fields collected via conversation flows
tags	array	Customer tags for segmentation
status	string	active or blocked
total_conversations	integer	Number of conversations
first_conversation_at	datetime	First interaction timestamp
last_conversation_at	datetime	Most recent interaction

Customer Responses

When a customer interacts with a conversation flow, their responses are stored as CustomerResponse records:

Field	Type	Description
question_key	string	Field identifier (e.g., name, service_choice)
question_text	string	The question that was asked
response_value	string	Customer's answer
response_type	string	text, button, list, approval, reply
response_metadata	object	Additional context

Data Collection

Conversation flows can collect customer data using the save_key feature on steps. Each collected value is stored in:

1. Session Data (conversation_sessions.session_data) - Available during the active session
2. Customer Responses (customer_responses) - Persisted after session ends

Example Flow Data Collection

Step 1: "What is your name?" → save_key: "name"
Step 2: "What service do you need?" → save_key: "service"
Step 3: "Confirm your details" → Uses {{name}} and {{service}} variables

The collected data is available in:

• CRM Dashboard - View all customer responses
• Admin Approval Emails - Included in approval request notifications
• Webhook Events - Available in session data

Customer Tags

Tags can be used to segment customers:

{
  "tags": ["vip", "returning", "riyadh"]
}

Tags are managed from the CubeConnect CRM dashboard.

Search

Customers can be searched by name, phone number, or email from the Inbox:

GET /api/inbox/contacts/search?q=mohammed

Response:

{
  "contacts": [
    {
      "id": 1,
      "customer_id": 42,
      "name": "Mohammed Ali",
      "phone": "+966501234567",
      "source": "customer"
    }
  ]
}

The source field indicates whether the result is a customer (has previous conversations) or a contact (from imported contacts).