WhatsApp agentsWhatsApp leads

WhatsApp leads

Every customer chat on your WhatsApp numbers, as a lead you can categorize, hand over and close.

Each chat between a customer and one of your numbers is a conversation, and every conversation is a lead. A lead can carry a category (for example hot, warm, cold) that the AI decides from the chat, and that drives automatic follow-ups.

Conversations are created automatically when a customer messages your number or you message them, so there is no create endpoint. You can read, update and delete them.

Conversations older than your plan's history window are not returned.

Endpoints

GETList conversations/whatsapp/conversationsGETGet conversation/whatsapp/conversations/{id}PATCHUpdate conversation/whatsapp/conversations/{id}DELETEDelete conversation/whatsapp/conversations/{id}GETGet lead summary/whatsapp/leads/summary

The conversation object

idstring (uuid)
Conversation id.
tenant_idstring (uuid)
The workspace that owns the conversation.
whatsapp_account_idstring (uuid)
Your WhatsApp account the conversation is on.
phone_number_idstring
Meta phone number id of your number.
customer_numberstring
Customer's number, digits only, e.g. 919876543210.
customer_namestringnullable
Customer's WhatsApp profile name.
agent_idstring (uuid)nullable
Agent answering this conversation.
last_message_atstring (date-time)nullable
Time of the latest message.
last_message_previewstringnullable
Start of the latest message.
last_message_directionstringnullable
inbound or outbound.
unread_countinteger
Customer messages not yet read in the dashboard.
ai_pausedboolean
true when a person has taken over and the AI agent doesn't reply.
last_inbound_atstring (date-time)nullable
Time of the customer's last message. Free-form replies are only allowed within 24 hours of it.
opted_out_atstring (date-time)nullable
Set when the customer replied STOP to campaigns.
categorystringnullable
Lead category (e.g. hot, warm, cold), or null if undecided.
followup_stepinteger
How many follow-ups of the category's sequence have been sent.
trigger_delay_minutesintegernullable
Minutes a new customer message waits before the lead is re-categorized.
categorized_atstring (date-time)nullable
When the category was last decided.
statusstring
open or closed.
Allowed:openclosed
created_atstring (date-time)nullable
When the conversation started.
updated_atstring (date-time)nullable
When it last changed. Use as a sync cursor with updated_since.

{ "id": "d2c3b4a5-9687-4f1e-8d2c-3b4a59687f1e", "tenant_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "whatsapp_account_id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d", "phone_number_id": "109876543210987", "customer_number": "919876543210", "customer_name": "Vikram", "agent_id": "3f6c2b1e-8a4d-4c5e-9b2a-1d7e6f8a9b0c", "last_message_at": "2026-10-24T14:03:11.508Z", "last_message_preview": "Can you share the documents list?", "last_message_direction": "inbound", "unread_count": 1, "ai_paused": false, "last_inbound_at": "2026-10-24T14:03:11.508Z", "opted_out_at": null, "category": "hot", "followup_step": 0, "trigger_delay_minutes": 10, "categorized_at": "2026-10-24T14:03:11.508Z", "status": "open", "created_at": "2026-10-20T09:15:42.120Z", "updated_at": "2026-10-24T14:03:11.508Z" }

The conversation object

idstring (uuid)

Conversation id.

tenant_idstring (uuid)

The workspace that owns the conversation.

whatsapp_account_idstring (uuid)

Your WhatsApp account the conversation is on.

phone_number_idstring

Meta phone number id of your number.

customer_numberstring

Customer's number, digits only, e.g. 919876543210.

customer_namestringnullable

Customer's WhatsApp profile name.

agent_idstring (uuid)nullable

Agent answering this conversation.

last_message_atstring (date-time)nullable

Time of the latest message.

last_message_previewstringnullable

Start of the latest message.

last_message_directionstringnullable

inbound or outbound.

unread_countinteger

Customer messages not yet read in the dashboard.

ai_pausedboolean

true when a person has taken over and the AI agent doesn't reply.

last_inbound_atstring (date-time)nullable

Time of the customer's last message. Free-form replies are only allowed within 24 hours of it.

opted_out_atstring (date-time)nullable

Set when the customer replied STOP to campaigns.

categorystringnullable

Lead category (e.g. hot, warm, cold), or null if undecided.

followup_stepinteger

How many follow-ups of the category's sequence have been sent.

trigger_delay_minutesintegernullable

Minutes a new customer message waits before the lead is re-categorized.

categorized_atstring (date-time)nullable

When the category was last decided.

statusstring

open or closed.

Allowed:openclosed

created_atstring (date-time)nullable

When the conversation started.

updated_atstring (date-time)nullable

When it last changed. Use as a sync cursor with updated_since.