Skip to main content
PATCH
/
conversations
/
{id}
Update a conversation
curl --request PATCH \
  --url https://api.getfernand.com/conversations/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status": "OPENED",
  "snooze_until": "<string>",
  "agent_id": 123,
  "agent_email": "<string>",
  "subject": "<string>",
  "contact_id": 123
}
'
{
  "id": 12345,
  "contact_id": 789,
  "subject": "Question about billing",
  "status": "OPENED",
  "last_update": "2026-01-21T14:30:00Z",
  "tags": [
    1,
    5,
    12
  ],
  "recipients": [
    {
      "id": 12345,
      "contact_id": 789,
      "kind": "cc",
      "conversation_id": 456
    }
  ],
  "agent_id": 42,
  "channel_id": 1,
  "snooze_until": "2026-01-22T09:00:00Z",
  "cursor": "cur_1234567890"
}
Updates properties of a specific conversation. Status changes and agent assignments trigger automated workflows and notifications. Only changed fields need to be included in the request.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Path Parameters

​
id
integer<int64>
required

ID of the conversation to update.

Body

application/json
​
status
enum<string>

New status for the conversation (requires conversation.status permission).

Available options:
OPENED,
CLOSED,
SPAM,
SNOOZED
​
snooze_until
string

When status is SNOOZED, specifies when to unsnooze. Formats:

  • "5m", "+30" (minutes from now)
  • "tomorrow", "monday", "tuesday", etc. (next occurrence at 9am)
  • "one week", "one month" (relative periods)
  • ISO 8601 timestamp (absolute time)
​
agent_id
integer<int64> | null

ID of agent to assign. Use null to unassign (requires conversation.assign permission).

​
agent_email
string

Email of agent to assign (alternative to agent_id, requires conversation.assign permission).

​
subject
string

New subject line for the conversation (requires conversation.update permission).

Maximum string length: 80
​
contact_id
integer<int64>

ID of an existing recipient to set as the primary contact.

Response

Conversation updated successfully.

​
id
integer<int64>
required

Unique identifier for the conversation

Example:

12345

​
contact_id
integer<int64>
required

ID of the primary contact who initiated the conversation

Example:

789

​
subject
string
required

Subject line of the conversation, derived from the first message or manually set

Maximum string length: 250
Example:

"Question about billing"

​
status
enum<string>
required

Current status of the conversation

Available options:
OPENED,
CLOSED,
SPAM,
SNOOZED
Example:

"OPENED"

​
last_update
string<date-time>
required

ISO 8601 timestamp of the last incoming message in the conversation

Example:

"2026-01-21T14:30:00Z"

​
tags
integer<int32>[]
required

Array of tag IDs associated with this conversation

Example:
[1, 5, 12]
​
recipients
object[]
required

Array of recipients in the conversation (to, cc, bcc)

​
agent_id
integer<int64> | null

ID of the agent assigned to this conversation, or null if unassigned

Example:

42

​
channel_id
integer<int64> | null

ID of the channel through which this conversation is conducted

Example:

1

​
snooze_until
string<date-time> | null

ISO 8601 timestamp indicating when a snoozed conversation should reappear, or null if not snoozed

Example:

"2026-01-22T09:00:00Z"

​
cursor
string | null

Pagination cursor for retrieving the next page of conversations in a list

Example:

"cur_1234567890"