List Lead Conversations — DeltaLead REST API Endpoint

Retrieve all conversations tracked by DeltaLead across every connected channel — WhatsApp, Facebook, Instagram, email, and phone. Each conversation record ties back to a lead and reflects the current state of that exchange: open, closed, or transferred to a human advisor. Filter by lead ID to pull the conversation history for a specific contact, or filter by status to monitor all open threads that need attention.

Endpoint

GET https://platform-api.deltalead.ai/v1/conversations

Query Parameters

integer

default:"20"

Maximum number of conversations to return per page. Accepts values between 1 and 100.

string

Opaque pagination cursor from the previous response’s pagination.next_cursor field. Omit to start from the first page.

string

Filter conversations to a specific lead. Pass a lead ID such as lead_abc123 to retrieve every conversation thread belonging to that contact.

string

Filter by the channel on which the conversation is taking place. Accepted values: whatsapp, facebook, instagram, email, phone.

string

Filter by conversation status. Accepted values: open, closed, transferred.

Example Request

cURL

curl 'https://platform-api.deltalead.ai/v1/conversations?lead_id=lead_abc123&status=open' \
  -H "X-API-Key: YOUR_API_KEY"

Response

A successful request returns HTTP 200 OK with a data array of conversation objects and a pagination object.

Example response

{
  "data": [
    {
      "id": "conv_xyz789",
      "lead_id": "lead_abc123",
      "channel": "whatsapp",
      "status": "open",
      "created_at": "2024-03-10T14:22:05Z",
      "updated_at": "2024-03-11T09:05:33Z",
      "last_message_at": "2024-03-11T09:05:33Z"
    },
    {
      "id": "conv_mno321",
      "lead_id": "lead_abc123",
      "channel": "phone",
      "status": "closed",
      "created_at": "2024-03-09T11:00:00Z",
      "updated_at": "2024-03-09T11:08:42Z",
      "last_message_at": "2024-03-09T11:08:42Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Response Fields

array

Array of conversation objects matching the applied filters.

string

Unique identifier for the conversation, prefixed with conv_.

string

ID of the lead this conversation belongs to.

string

Channel on which the conversation is taking place. One of whatsapp, facebook, instagram, email, phone.

string

Current status of the conversation. One of:

open — active conversation, AI agent or human is engaged
closed — conversation ended, no further messages expected
transferred — handed off from AI agent to a human sales advisor

string

ISO 8601 timestamp of when the conversation was opened.

string

ISO 8601 timestamp of the most recent change to the conversation record.

string

ISO 8601 timestamp of the most recent message or event in this conversation.

integer

Total number of conversations matching the applied filters.

boolean

true if additional pages exist.

string | null

Pass this value as cursor to fetch the next page. null when has_more is false.

Overview

Leads

Conversations

Agents

Webhooks

List Lead Conversations — DeltaLead REST API Endpoint

Endpoint

Query Parameters

Example Request

Response

Response Fields

​Endpoint

​Query Parameters

​Example Request

​Response

​Response Fields

Endpoint

Query Parameters

Example Request

Response

Response Fields