Contacts

Overview

Contacts represent WhatsApp users you communicate with. Each contact stores their phone number, profile information, and conversation history.

Note

Role-based access: Agents can only see and interact with contacts assigned to them. Admins and Managers can see all contacts.

List Contacts

Retrieve a paginated list of contacts.

GET /api/contacts

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
search	string	Search by profile name or phone number
tags	string	Filter by tags (comma-separated, matches contacts with any of the tags)

Response

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "phone_number": "1234567890",
        "name": "John Doe",
        "profile_name": "John Doe",
        "avatar_url": "https://...",
        "status": "active",
        "tags": ["vip", "support"],
        "metadata": {
          "plan": "premium",
          "company": "Acme Corp"
        },
        "last_message_at": "2024-01-01T12:00:00Z",
        "last_message_preview": "Hello there!",
        "unread_count": 0,
        "assigned_user_id": "880e8400-e29b-41d4-a716-446655440000",
        "whatsapp_account": "default_account",
        "last_inbound_at": "2024-01-01T11:59:00Z",
        "service_window_open": true,
        "marketing_opt_out": false,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

Get Contact

Retrieve a single contact by ID.

GET /api/contacts/{id}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "1234567890",
    "name": "John Doe",
    "profile_name": "John Doe",
    "avatar_url": "https://...",
    "status": "active",
    "tags": ["vip", "support"],
    "metadata": {
      "plan": "premium",
      "company": "Acme Corp"
    },
    "last_message_at": "2024-01-01T12:00:00Z",
    "last_message_preview": "Hello there!",
    "unread_count": 0,
    "assigned_user_id": "880e8400-e29b-41d4-a716-446655440000",
    "whatsapp_account": "default_account",
    "last_inbound_at": "2024-01-01T11:59:00Z",
    "service_window_open": true,
    "marketing_opt_out": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Create Contact

Create a new contact.

POST /api/contacts

Request Body

Field	Type	Required	Description
phone_number	string	Yes	Phone number of the contact
profile_name	string	No	Profile/display name of the contact
whatsapp_account	string	No	Default WhatsApp account name
tags	array	No	Array of tags for the contact
metadata	object	No	Custom metadata fields

{
  "phone_number": "1234567890",
  "profile_name": "John Doe",
  "whatsapp_account": "default_account",
  "tags": ["vip"],
  "metadata": {
    "plan": "premium"
  }
}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "1234567890",
    "name": "John Doe",
    "profile_name": "John Doe",
    "avatar_url": "",
    "status": "active",
    "tags": ["vip"],
    "metadata": {
      "plan": "premium"
    },
    "last_message_at": null,
    "last_message_preview": "",
    "unread_count": 0,
    "assigned_user_id": null,
    "whatsapp_account": "default_account",
    "last_inbound_at": null,
    "service_window_open": false,
    "marketing_opt_out": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Update Contact

Update an existing contact.

PUT /api/contacts/{id}

Request Body

Field	Type	Description
profile_name	string	Updated profile/display name
whatsapp_account	string	Updated default WhatsApp account name
tags	array	Updated array of tags
metadata	object	Updated custom metadata object
assigned_user_id	uuid	Assign to a user ID
clear_assigned_agent	boolean	Set to true to unassign

{
  "profile_name": "John Smith",
  "tags": ["vip", "churn-risk"],
  "metadata": {
    "plan": "premium",
    "custom_field": "updated_value"
  }
}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "1234567890",
    "name": "John Smith",
    "profile_name": "John Smith",
    "avatar_url": "",
    "status": "active",
    "tags": ["vip", "churn-risk"],
    "metadata": {
      "plan": "premium",
      "custom_field": "updated_value"
    },
    "last_message_at": "2024-01-01T12:00:00Z",
    "last_message_preview": "Hello there!",
    "unread_count": 0,
    "assigned_user_id": null,
    "whatsapp_account": "default_account",
    "last_inbound_at": "2024-01-01T11:59:00Z",
    "service_window_open": true,
    "marketing_opt_out": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T12:05:00Z"
  }
}

Delete Contact

Delete a contact and all associated data.

DELETE /api/contacts/{id}

Response

{
  "status": "success",
  "data": null
}

Assign Contact

Assign a contact to a team member.

Caution

This endpoint requires Admin or Manager role.

PUT /api/contacts/{id}/assign

Request Body

{
  "user_id": "880e8400-e29b-41d4-a716-446655440000"
}

To unassign a contact, set user_id to null:

{
  "user_id": null
}

Response

{
  "status": "success",
  "data": {
    "message": "Contact assigned successfully",
    "assigned_user_id": "880e8400-e29b-41d4-a716-446655440000"
  }
}

Mark Contact as Read

Mark all incoming messages from a contact as read and clear unread count.

POST /api/contacts/{id}/mark-read

Response

{
  "status": "success",
  "data": {
    "status": "ok"
  }
}

Tip

Use the metadata field to store custom data like customer IDs, order numbers, or any business-specific information. Metadata is displayed automatically in the Contact Info panel in the chat view.

Contact Metadata

The metadata field is a freeform JSON object that can hold any structured data. It is displayed in the Contact Info panel alongside tags and session data.

Supported Data Types

Different value types are rendered differently in the panel:

Type	Display
String, number	Key-value row
Boolean	Yes / No badge
Object	Collapsible section with key-value rows
Array of objects	Collapsible table with column headers
Array of primitives	Inline badges

Example

{
  "metadata": {
    "plan": "premium",
    "age": 30,
    "active": true,
    "address": {
      "city": "Mumbai",
      "state": "Maharashtra",
      "zip": "400001"
    },
    "orders": [
      { "id": "ORD-001", "amount": 1500, "status": "delivered" },
      { "id": "ORD-002", "amount": 2300, "status": "pending" }
    ],
    "interests": ["fitness", "tech", "travel"]
  }
}

This renders as:

• General section — plan, age, and active as key-value rows (boolean shown as a badge)
• Address section — collapsible key-value pairs for city, state, zip
• Orders section — collapsible table with Id, Amount, Status columns
• Interests section — inline badges: fitness, tech, travel

Nesting Depth

The panel supports one level of nesting. Top-level keys are organized as follows:

Top-level value	Rendered as
Primitive (string, number, boolean)	Row in the General section
Object	Its own collapsible section with key-value rows
Array of objects	Its own collapsible section with a table
Array of primitives	Its own collapsible section with badges

Values inside a nested object or array are always displayed as flat text. If a nested object contains another object, the inner value is shown as a raw JSON string. For example:

{
  "metadata": {
    "address": {
      "city": "Mumbai",
      "location": { "lat": 19.07, "lng": 72.87 }
    }
  }
}

Here city displays as Mumbai, but location displays as {"lat":19.07,"lng":72.87}.

Caution

Keep metadata flat or one level deep for the best display. Deeply nested structures will fall back to raw JSON strings in the panel.

Note

Keys are automatically formatted for display: snake_case and camelCase are converted to title case (e.g. first_name → “First Name”, lastName → “Last Name”).

Get Session Data

Retrieve chatbot session data for a contact, including collected variables and panel configuration.

GET /api/contacts/{id}/session-data

Response

{
  "status": "success",
  "data": {
    "session_id": "uuid",
    "flow_id": "uuid",
    "flow_name": "Customer Support Flow",
    "session_data": {
      "customer_name": "John Doe",
      "customer_email": "john@example.com",
      "order_id": "ORD-12345",
      "order_status": "shipped"
    },
    "panel_config": {
      "sections": [
        {
          "id": "customer",
          "label": "Customer Info",
          "columns": 1,
          "collapsible": true,
          "default_collapsed": false,
          "order": 1,
          "fields": [
            {"key": "customer_name", "label": "Name", "order": 1},
            {"key": "customer_email", "label": "Email", "order": 2}
          ]
        },
        {
          "id": "order",
          "label": "Order Details",
          "columns": 2,
          "collapsible": true,
          "default_collapsed": true,
          "order": 2,
          "fields": [
            {"key": "order_id", "label": "Order ID", "order": 1},
            {"key": "order_status", "label": "Status", "order": 2}
          ]
        }
      ]
    }
  }
}

Response Fields

Field	Type	Description
session_id	uuid	The chatbot session ID
flow_id	uuid	The flow that collected the data
flow_name	string	Name of the flow
session_data	object	Key-value pairs of collected variables
panel_config	object	Panel display configuration from the flow

Note

This endpoint returns data from the contact’s most recent chatbot session. The panel_config comes from the flow that was active during that session.