WhatsApp agentsWhatsApp leads

Update conversation

Closes or reopens a conversation, pauses or resumes the AI agent on it, or sets its lead category.

PATCH/v2/whatsapp/conversations/{id}

Setting a different category restarts that category's follow-up sequence from the first step. Send "category": null to make the lead undecided again.

Authorization

Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <api_key>, where <api_key> is a key from Account Settings → API keys in your dashboard.

Path parameters

idstring (uuid)required
The conversation's id.

Request body

application/json

statusstring
Close or reopen.
Allowed:openclosed
ai_pausedboolean
true stops the AI agent replying so a person can take over.
categorystringnullable
One of the categories set up for this number on the Follow-ups page.
trigger_delay_minutesinteger
Minutes (≥ 1) a new customer message waits before the lead is re-categorized.

Response

The updated conversation object.

Show all 21 fieldsHide fields

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.

curl --request PATCH \ --url 'https://api.tarangnow.com/v2/whatsapp/conversations/d2c3b4a5-9687-4f1e-8d2c-3b4a59687f1e' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{ "category": "warm", "ai_paused": true }'

{ "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": true, "last_inbound_at": "2026-10-24T14:03:11.508Z", "opted_out_at": null, "category": "warm", "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" }

Request body

application/json

statusstring

Close or reopen.

Allowed:openclosed

ai_pausedboolean

true stops the AI agent replying so a person can take over.

categorystringnullable

One of the categories set up for this number on the Follow-ups page.

trigger_delay_minutesinteger

Minutes (≥ 1) a new customer message waits before the lead is re-categorized.

Response

The updated conversation object.

Show all 21 fieldsHide fields

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.