> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivi.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Sessions

> Control when an inactive messaging chat becomes a new conversation for agent context and reporting.

Messaging providers usually keep one chat open for the same person or group indefinitely. Without
a separate boundary, an agent can treat requests from different days as one conversation, carry old
context into unrelated work, and combine those requests in reports.

**Conversation sessions** give each chat a practical lifespan. When VIVI identifies a new
conversation, the agent starts with fresh session context while the earlier conversation remains
available in history and reporting.

<CardGroup cols={2}>
  <Card title="Cleaner agent context" icon="message-dots">
    Unrelated requests do not accumulate forever in the context used for the next response.
  </Card>

  <Card title="More meaningful reports" icon="chart-line">
    Conversation counts, duration, message averages, satisfaction, and resolution describe separate
    customer sessions instead of one lifetime chat.
  </Card>
</CardGroup>

## Where sessions apply

Conversation sessions are always active for these channel contexts:

| Channel context         | Session scope                                                      | Manual reset  |
| ----------------------- | ------------------------------------------------------------------ | ------------- |
| **WhatsApp**            | One session timeline for each channel and customer number          | Send `/new`   |
| **SMS**                 | One session timeline for each real SMS channel and customer number | Not available |
| **Teams personal chat** | One session timeline for the personal chat                         | Send `/new`   |
| **Teams group chat**    | One shared session timeline for the whole group chat               | Not available |

Team channel reply threads do not use these settings. Each root post already provides a visible
conversation boundary in a Team channel.

<Note>
  In a Teams group chat, all participants share the same session. After a session changes, recent
  group messages can still provide immediate chat context when the agent is mentioned.
</Note>

## Default timing

Every eligible channel uses the following defaults unless you select custom timing:

<CardGroup cols={2}>
  <Card title="Review after 30 minutes" icon="hourglass-half">
    After at least 30 minutes of inactivity, VIVI can start a new session when the previous request
    was complete and the returning message is an independent request.
  </Card>

  <Card title="Always start fresh after 24 hours" icon="calendar-day">
    After at least 24 hours of inactivity, the next inbound message always starts a new session.
  </Card>
</CardGroup>

The 30-minute value is a **review threshold**, not an automatic timeout. VIVI uses the relationship
between the previous conversation and the returning message to avoid splitting a clarification,
expected answer, or delayed “thank you” into a false second conversation.

### How VIVI chooses a session

<Tabs>
  <Tab title="Before the review threshold">
    The message remains in the current session. This grace period keeps quick follow-ups together,
    even when the previous answer appeared complete.
  </Tab>

  <Tab title="Between the thresholds">
    If the previous request still has an open question, promised action, handoff, or failed operation,
    the message remains in the current session.

    If the previous request was complete, VIVI checks how the new message relates to it. A genuinely
    independent request starts a new session. A continuation, clarification, correction, reopening,
    closing acknowledgment, or uncertain message remains in the current session.
  </Tab>

  <Tab title="At or after the fresh-session threshold">
    The message starts a new session before the agent responds. This upper limit prevents context and
    reporting sessions from growing indefinitely.
  </Tab>
</Tabs>

If VIVI cannot confidently determine that a message is a new request, it preserves the current
session. This favors continuity over removing context too early.

## Examples

The examples below use the default 30-minute review threshold and 24-hour fresh-session threshold.

<AccordionGroup>
  <Accordion title="A delayed closing acknowledgment stays with the prior conversation" icon="check">
    1. **Customer:** “Can I return an item after 30 days?”
    2. **Agent:** “Yes. You can return it within 60 days with proof of purchase.”
    3. More than 30 minutes, but less than 24 hours, pass.
    4. **Customer:** “Thanks, that is all.”
    5. **Agent:** “You’re welcome.”

    The thank-you is a closing acknowledgment, so all five messages remain in one session.
  </Accordion>

  <Accordion title="An independent request starts a new conversation" icon="arrow-right-arrow-left">
    1. **Customer:** “What are your support hours?”
    2. **Agent:** “Support is available Monday through Friday, 9 AM to 5 PM.”
    3. More than 30 minutes, but less than 24 hours, pass.
    4. **Customer:** “What is 2 + 2?”

    The new question is independent from the completed support-hours request. VIVI starts a new
    session before the agent answers it.
  </Accordion>

  <Accordion title="An expected answer continues an open workflow" icon="link">
    1. **Customer:** “I need help changing my delivery address.”
    2. **Agent:** “I can help. What is your order number?”
    3. More than 30 minutes, but less than 24 hours, pass.
    4. **Customer:** “The order number is 12345.”

    The agent was waiting for the order number, so the answer remains in the same session.
  </Accordion>

  <Accordion title="A quick new question stays in the grace period" icon="bolt">
    1. **Customer:** “What is your return policy?”
    2. **Agent:** “Items can be returned within 60 days with proof of purchase.”
    3. Less than 30 minutes pass.
    4. **Customer:** “What if I lost the receipt?”

    Messages below the review threshold remain together, so the agent can use the return-policy
    context naturally.
  </Accordion>

  <Accordion title="A message after the upper threshold always starts fresh" icon="clock-rotate-left">
    1. **Customer:** “Where can I download my invoices?”
    2. **Agent:** “Open Billing, then select Invoices and Download.”
    3. At least 24 hours pass.
    4. **Customer:** “Can you help me reset my password?”

    VIVI starts a new session before the agent responds, regardless of the previous completion state.
  </Accordion>
</AccordionGroup>

## Configure session timing

You can keep the default timing or configure a policy for an individual channel.

<Steps>
  <Step title="Open the channel">
    In your workspace, go to **Agents → Channels** and select a WhatsApp, SMS, or MS Teams & Copilot
    channel.
  </Step>

  <Step title="Open Conversation sessions">
    Expand the **Conversation sessions** section on the channel details page.
  </Step>

  <Step title="Choose the timing mode">
    Select **Use default timing** to review after 30 minutes and always start fresh after 24 hours.

    Select **Use custom timing** to configure channel-specific thresholds and optional completion
    guidance.
  </Step>

  <Step title="Configure custom values">
    * **Review after inactivity:** The minimum inactive time before VIVI can separate a completed
      request from an independent returning request. Minimum: 1 minute.
    * **Always start fresh after:** The inactive time that always creates a new session. It must be
      greater than the review threshold and cannot exceed 10,080 minutes (7 days).
    * **Completion guidance:** Optional business-specific guidance, up to 4,000 characters, that
      helps VIVI recognize whether work is still open.
  </Step>

  <Step title="Save the channel">
    Select **Save** or **Save changes**, depending on the channel page. The new policy applies to
    future activity on that channel.
  </Step>
</Steps>

<Warning>
  **Use default timing** does not disable conversation sessions. Sessions are always active on
  eligible channels; this choice resets the channel to the default 30-minute and 24-hour values.
</Warning>

## Write useful completion guidance

Completion guidance describes business conditions that VIVI cannot infer from general conversation
rules. Write it as plain operational guidance. You do not need to mention models, classifiers,
threads, or “standard completion rules.”

Good examples include:

* “A booking is complete only after the customer receives a confirmation number.”
* “A delivery-address change remains open while the agent is waiting for the order number or the new
  address.”
* “A support request remains open until a promised human handoff is confirmed.”
* “If a payment or booking tool fails, keep the request open until it succeeds or the customer
  decides not to continue.”

<Note>
  Completion guidance controls conversation boundaries. It does not replace the agent prompt or
  instruct the agent how to answer customers.
</Note>

## Start fresh manually

In a WhatsApp or Teams personal chat, send:

```text theme={null}
/new
```

VIVI immediately starts a fresh session for the next request. The prior messages are preserved for
history and reporting, but the agent no longer uses them as session context.

The command is not available in SMS, Teams group chats, or Team channels.

## Outbound messages and WhatsApp follow-ups

An outbound or proactive message uses the active session. If the chat has already reached the upper
inactivity threshold, VIVI starts a fresh session before it stores the outbound context. The
customer's reply then continues from the same session as the message they received.

For WhatsApp campaigns, VIVI preserves enough context for the agent to understand the first delayed
reply, even if the upper threshold starts a fresh session before that reply arrives.

A WhatsApp follow-up belongs to the session that scheduled it. If that session changes before the
follow-up is sent, VIVI cancels the old reminder so a check-in from a previous conversation does not
appear in a new one.

## Reporting behavior

Each rotated session is treated as a separate conversation in reports and summaries. As a result:

* Conversation counts reflect customer sessions instead of lifetime provider chats.
* Duration and messages-per-conversation describe the individual session.
* Satisfaction, resolution, containment, and topic analysis apply to the relevant session.
* Earlier sessions remain available through their existing conversation history.

After this feature is enabled, conversation-level metrics may differ from older periods because one
long-lived provider chat can now produce multiple meaningful sessions.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why did a message stay in the same session after the review threshold?" icon="circle-question">
    The review threshold does not force a reset. VIVI keeps the session when work is incomplete or
    when the returning message continues, clarifies, corrects, reopens, or closes the prior request.
  </Accordion>

  <Accordion title="Why does VIVI check the previous reply and the next message?" icon="messages">
    A completed answer alone does not reveal what the customer will say next. For example, “Thanks”
    and an unrelated new request can both arrive after a completed answer and the same pause. VIVI
    uses both signals to avoid creating a separate conversation for a closing acknowledgment.
  </Accordion>

  <Accordion title="Does session detection add response latency?" icon="gauge-high">
    Most messages do not need an additional boundary check. VIVI performs one before the agent runs
    only when a completed conversation returns between the two thresholds. Messages below the review
    threshold, open conversations, manual resets, and messages at or above the upper threshold do not
    need that check.
  </Accordion>

  <Accordion title="Can conversation sessions be disabled?" icon="toggle-on">
    No. Eligible messaging channels always use conversation sessions. You can choose the default
    timing or configure channel-specific timing and completion guidance.
  </Accordion>
</AccordionGroup>

## Related channels

<CardGroup cols={3}>
  <Card title="MS Teams & Copilot" icon="microsoft" href="/documentation/core-concepts/channels/ms-teams">
    Personal and group chat behavior, installation, and proactive messaging.
  </Card>

  <Card title="SMS Channel" icon="message-sms" href="/documentation/core-concepts/channels/sms">
    SMS setup, consent, compliance, and messaging behavior.
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/documentation/core-concepts/channels/whatsapp">
    WhatsApp setup, messaging, and campaigns.
  </Card>
</CardGroup>