Conversations

Conversations represent active messaging threads between your WhatsApp account and customers. CubeConnect automatically manages conversation sessions, tracks the 24-hour messaging window, and logs all messages.

Conversation Model

Field	Type	Description
id	integer	Unique conversation session ID
conversation_flow_id	integer	Associated conversation flow
whatsapp_account_id	integer	WhatsApp account ID
customer_phone	string	Customer phone number
current_step_id	integer	Current step in the conversation flow
session_data	object	Collected data from the conversation
started_at	datetime	Session start time
last_interaction_at	datetime	Last customer interaction
expires_at	datetime	Session expiration time
is_completed	boolean	Whether the flow has completed

24-Hour Messaging Window

WhatsApp enforces a 24-hour messaging window. You can send free-form text messages only within 24 hours of the customer's last message.

Customer sends message → Window opens (24 hours)
        ↓
Within 24h: Send text, media, interactive messages
        ↓
After 24h: Only pre-approved templates allowed

Checking Window Status

The CRM API provides a session status endpoint to check the current window:

GET /api/crm/{customer}/session-status

Response:

{
  "window_active": true,
  "last_inbound_at": "2026-02-26T14:00:00Z",
  "expires_at": "2026-02-27T14:00:00Z",
  "remaining_minutes": 1380,
  "templates": []
}

When the window is expired:

{
  "window_active": false,
  "last_inbound_at": "2026-02-24T10:00:00Z",
  "expires_at": "2026-02-25T10:00:00Z",
  "remaining_minutes": 0,
  "templates": [
    {
      "id": 1,
      "name": "order_confirmation",
      "language": "ar",
      "body": "Your order {{1}} is confirmed. Total: {{2}}",
      "param_count": 2
    }
  ]
}

Message Types

Messages within a conversation can be:

Type	Direction	Description
text	Both	Plain text
image	Both	Images (JPEG, PNG, WebP)
video	Both	Videos (MP4)
audio	Both	Audio/voice notes
document	Both	Files (PDF, etc.)
template	Outbound	Pre-approved templates
interactive	Outbound	Buttons and lists
location	Inbound	GPS coordinates
sticker	Inbound	Sticker images
reaction	Both	Emoji reactions

Message Statuses

Each outbound message goes through these statuses:

Status	Description
queued	Message accepted by CubeConnect
sent	Sent to WhatsApp Cloud API
delivered	Delivered to recipient's device
read	Read by recipient
failed	Delivery failed

Conversation Categories

WhatsApp categorizes conversations for pricing:

Category	Description	Initiated By
SERVICE	Customer-initiated support	Customer
MARKETING	Promotional messages	Business (template)
UTILITY	Transactional updates	Business (template)
AUTHENTICATION	Verification codes	Business (template)

INFO

CubeConnect automatically determines the conversation category based on the message type and template category.