PATCH

Update Conversation

Updates the status, tags, or metadata of a conversation.

PATCHhttps://api.vantaxai.com/v1/conversations/{conversation_id}

Only include the fields you want to change. Sending `tags` or `metadata` replaces the existing value wholesale — read the conversation first and merge client-side if you need to append. Use this endpoint to triage threads (open → pending → closed), label them, and attach your own structured data.

Status workflow

`open` threads are awaiting attention, `pending` marks them as snoozed/waiting on the contact, and `closed` archives them. Closing a conversation also resets its `unread_count` to 0.

tags and metadata are replaced, not merged

Both `tags` and `metadata` overwrite the stored value entirely. To add a tag or a metadata key, GET the conversation first, merge the change into the existing value, then PATCH the full result.

Metadata shape

Use flat string-keyed/string-valued pairs (for example `crm_id`, `priority`, `source`). Metadata is searchable in the dashboard and echoed back on every conversation read.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Path Parameters

conversation_idstringrequired
The conversation to update.
example: conv_7b2e9a

Body Parameters

statusstringoptional
Move the conversation through your triage workflow.
openpendingclosed
example: closed
tagsstring[]optional
Replaces the conversation's tags with this exact set. Send an empty array to clear all tags.
example: ["vip", "billing"]
metadataobjectoptional
Arbitrary key/value pairs (string values) stored on the conversation. Replaces the existing metadata object.

Request

# Tagging — replace the conversation's tag set
curl -X PATCH https://api.vantaxai.com/v1/conversations/conv_7b2e9a \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "billing", "follow-up"]
  }'

# Metadata — attach your own structured data
curl -X PATCH https://api.vantaxai.com/v1/conversations/conv_7b2e9a \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_id": "deal_8842",
      "priority": "high"
    }
  }'

// Tagging: replaces the existing tags wholesale
const tagged = await fetch(
  "https://api.vantaxai.com/v1/conversations/conv_7b2e9a",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer vx_live_3fa9c2...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tags: ["vip", "billing", "follow-up"] }),
  }
);

// Metadata: attach your own structured data
const withMeta = await fetch(
  "https://api.vantaxai.com/v1/conversations/conv_7b2e9a",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer vx_live_3fa9c2...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      metadata: { crm_id: "deal_8842", priority: "high" },
    }),
  }
);
const { data: conversation } = await withMeta.json();

// Tagging: replaces the existing tags wholesale
await vantax.conversations.update("conv_7b2e9a", {
  tags: ["vip", "billing", "follow-up"],
});

// Metadata: attach your own structured data
const conversation = await vantax.conversations.update("conv_7b2e9a", {
  metadata: { crmId: "deal_8842", priority: "high" },
});

# Tagging: replaces the existing tags wholesale
vantax.conversations.update(
    "conv_7b2e9a",
    tags=["vip", "billing", "follow-up"],
)

# Metadata: attach your own structured data
conversation = vantax.conversations.update(
    "conv_7b2e9a",
    metadata={"crm_id": "deal_8842", "priority": "high"},
)

Response

{
  "success": true,
  "message": "Conversation updated successfully",
  "data": {
    "id": "conv_7b2e9a",
    "sub_account_id": "sub_8a1f4c2e",
    "channel": "whatsapp",
    "contact_id": "ct_19f3a0",
    "status": "closed",
    "tags": ["vip", "billing"],
    "metadata": {
      "source": "campaign_spring_2026"
    },
    "unread_count": 0,
    "last_message_at": "2026-06-10T11:42:00Z",
    "created_at": "2026-06-08T09:15:00Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "status", "message": "status must be one of: open, pending, closed" }
  ]
}

{ "success": false, "message": "Conversation not found" }