Core Concepts

Contacts and segments

Store customer contact records and group them into segments for workflows.

Contacts

Contacts belong to a workspace and include phone number, display name, email, status, tags, and metadata.

Use contacts when operators need history, tags, inbox context, or campaign segmentation.

Contacts are dashboard/customer-session resources under `/api/customer/contacts`. Public send APIs do not require contacts, but they respect blocked, unsubscribed, and archived contact state when a matching receiver exists.

Segments

Segments group contacts manually or through filters. Campaigns can launch to segment contacts, and analytics can show campaign performance by workspace.

Use segments carefully for operational customer workflows. Keep consent, status, and blocking rules respected before sending.

Contacts and segments API routes

Use these routes from the authenticated customer dashboard or trusted customer portal code. They are not public API-key send endpoints.

POST/api/customer/contacts

Create a contact in the current workspace.

Create contact

json

{
  "phone_number": "212612345678",
  "display_name": "Sara Customer",
  "email": "sara@example.com",
  "status": "active",
  "tags": ["vip", "appointments"],
  "metadata": {
    "crm_id": "crm_123"
  }
}

POST/api/customer/segments

Create a segment for campaigns and automation workflows.

Create segment

json

{
  "name": "VIP customers",
  "description": "Customers tagged as VIP",
  "filter": {
    "tags": ["vip"],
    "status": "active"
  }
}

PUT/api/customer/segments/{segment_id}/contacts

Replace manual segment contact assignments.

Need help?

Use Book Integration Help if you want setup help for OTP or automated customer messaging.

Next steps

Quickstart

A practical path from empty workspace to a working server-side integration.

Authentication and access

HookMessage separates customer API keys, dashboard sessions, and internal platform access.

Workspaces

A workspace is the tenant boundary for every customer resource.

Senders and sessions

A sender is the WhatsApp number used to deliver messages for a workspace.