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.