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 name or phone number
account_id	string	Filter by WhatsApp account

Response

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "phone_number": "+1234567890",
        "name": "John Doe",
        "profile_name": "John",
        "avatar_url": "https://...",
        "account_id": "uuid",
        "assigned_to": "uuid",
        "last_message_at": "2024-01-01T12:00:00Z",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 20,
    "total_pages": 5
  }
}

Get Contact

Retrieve a single contact by ID.

GET /api/contacts/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "phone_number": "+1234567890",
    "name": "John Doe",
    "profile_name": "John",
    "avatar_url": "https://...",
    "account_id": "uuid",
    "assigned_to": "uuid",
    "metadata": {
      "custom_field": "value"
    },
    "last_message_at": "2024-01-01T12:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Create Contact

Create a new contact.

POST /api/contacts

Request Body

{
  "phone_number": "+1234567890",
  "name": "John Doe",
  "account_id": "uuid",
  "metadata": {
    "custom_field": "value"
  }
}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "phone_number": "+1234567890",
    "name": "John Doe",
    "account_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update Contact

Update an existing contact.

PUT /api/contacts/{id}

Request Body

{
  "name": "John Smith",
  "metadata": {
    "custom_field": "updated_value"
  }
}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "phone_number": "+1234567890",
    "name": "John Smith",
    "metadata": {
      "custom_field": "updated_value"
    },
    "updated_at": "2024-01-01T12:00: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": "uuid"
}

To unassign a contact, set user_id to null:

{
  "user_id": null
}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "assigned_to": "uuid",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

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.