Contacts

Overview

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

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.

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"
  }
}

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