Tasks

Manage Stubsession

Manage stub sessions across multiple communication platforms.

The manage_stubsession task provides a unified interface for managing stub sessions across different communication platforms. A stub session links a conversation on a platform (like WhatsApp or Webchat) to a specific stub, enabling contextual, stateful interactions.

# Supported Platforms

• WhatsApp - Manage sessions by mobile number and profile
• Webchat - Manage sessions by session UUID

# Operations

Both platforms support two core operations:

• set - Create or update a session, linking it to a stub
• delete - Remove a session

# Quick Start

# WhatsApp Example

Set a WhatsApp session that expires after 24 hours with automatic feedback routing:

# Webchat Example

Set a webchat session for a user's active session:

# Common Parameters

These parameters apply to all platforms:

# platform

required

string

The communication platform to manage sessions for.

Options: "whatsapp", "webchat"

Default: null

# WhatsApp Platform

Manage WhatsApp stub sessions by mobile number and profile.

# WhatsApp Parameters

# whatsapp.operation

required

string

The operation to perform on the WhatsApp stubsession.

Options: "set", "delete"

Default: null

# whatsapp.mobile_number

required

string or number

The mobile number to manage the session for. The + prefix is automatically removed if present.

Default: null

# whatsapp.whatsapp_profile_name

required

string

The WhatsApp profile to use for this session. Use "stubber_public" to use the Stubber public WhatsApp profile.

Default: null

# whatsapp.stubref

optional

string

The stub to link to this session. Only relevant for set operations.

Default: ~~stub.stubref

# whatsapp.set_new_with_timeout_hours

optional

number

How many hours the session should remain active. After this time, the session will automatically expire.

Default: 24

# whatsapp.set_feedback_action

optional

string

The action name to trigger when a user responds in this session. This allows automatic routing of responses back to the active stub.

Default: "_update_from_whatsapp"

# WhatsApp Examples

# Setting a session with custom timeout

Create a session that expires after 48 hours:

# Setting a session with custom feedback action

Route responses to a specific action:

# Deleting a session

End an active WhatsApp session:

# Using the public Stubber profile

Set a session using the shared public profile:

# WhatsApp Result

When setting a session:

        {
  "success": true,
  "payload": {
    "message": "Session set for 27821234567",
    "session": {
      "active_stubref": "2025-09-03-ABCD",
      "feedback_action": "_update_from_whatsapp"
    }
  }
}

      

When deleting a session:

        {
  "success": true,
  "payload": {
    "message": "Session deleted for 27821234567"
  }
}

      

# Webchat Platform

Manage webchat stub sessions by session UUID.

# Webchat Parameters

# webchat.operation

required

string

The operation to perform on the webchat stubsession.

Options: "set", "delete"

Default: null

# webchat.sessionuuid

required

string

The webchat session UUID to manage.

Default: null

# webchat.stubref

optional

string

The stub to link to this session. Only relevant for set operations.

Default: ~~stub.stubref

# webchat.set_new_with_timeout_hours

optional

number

How many hours the session should remain active. After this time, the session will automatically expire.

Default: 24

# webchat.set_feedback_action

optional

string

The action name to trigger when a user responds in this session.

Note: This parameter is currently not supported by webchat but will be enabled in a future update.

Default: "_update_from_webchat"

# Webchat Examples

# Setting a webchat session

Create a webchat session with default settings:

# Setting a session with custom timeout

Create a webchat session that expires after 12 hours:

# Deleting a webchat session

End an active webchat session:

# Webchat Result

When setting a session:

        {
  "success": true,
  "payload": {
    "message": "Session set for a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "session": {
      "active_stubref": "2025-09-03-ABCD",
      "feedback_action": "_update_from_webchat"
    }
  }
}

      

When deleting a session:

        {
  "success": true,
  "payload": {
    "message": "Session deleted for a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

      

# Understanding Stub Sessions

A stub session creates a stateful connection between a communication platform and a specific stub. When a session is active:

1. Incoming messages from the user on that platform are automatically routed to the linked stub
2. The feedback action (if configured) determines which action is run when receiving an incoming message
3. Sessions expire automatically after the configured timeout period
4. Multiple sessions can exist for different platforms or users simultaneously