Update a session

Use .update() to change the name or application metadata of a session:

const session = await orcha.supportAgent.update(sessionId, {
  name: "Escalated order ord_1001",
  metadata: {
    priority: "urgent",
    assignedTeam: "fulfillment",
  },
});

The returned value is the updated SessionSnapshot.

Update one fieldCopy Anchor Link

Metadata is merged, so you only need to send fields that changed:

const session = await orcha.supportAgent.update(sessionId, {
  metadata: {
    priority: "resolved",
  },
});

console.log(session.metadata);
// {
//   customerId: "cus_123",  Existing value remains.
//   priority: "resolved",   Supplied value is updated.
// }

Use null as an application-level empty value:

await orcha.supportAgent.update(sessionId, {
  metadata: {
    assignedTeam: null,
  },
});

This sets the value to null; it does not remove the key.

API referenceCopy Anchor Link

update(
  sessionId: string,
  update: {
    name?: string;
    metadata?: Record<string, string | number | boolean | null>;
  },
): Promise<SessionSnapshot>

• sessionId — the existing session to update.
• name — replaces the current display name.
• metadata — shallowly merges supplied keys into existing metadata.
• At least one of name or metadata is required.
• Metadata values must be strings, finite numbers, booleans, or null.
• The promise resolves with the complete updated snapshot.

Every successful update appends a durable session.updated event. Updating name or metadata does not start a run, send a model request, or alter the conversation.

Do not store secrets in session metadata.