Guides
Start typing to search…

Message lifecycle

RCS Studio follows a request-response lifecycle pattern similar to web page processing. Each incoming message triggers a series of well-defined stages that load context, process data, execute operations, render templates, and send responses to users.

Lifecycle stages

Stage 1: Message reception & state resolution

When a message arrives at the agent server, the system determines which state should handle the message.

What happens:

  • The webhook receives a user message with agentId and senderPhoneNumber
  • The system resolves the next state based on:
    • User's current context state
    • Message content (text or suggestions)
    • Default state configuration
Example
{
    "senderPhoneNumber": "+19177337159",
    "messageId": "be0ed04a-ff3c-4a1a-8c64-9235fb4f9073",
    "text": "Start",
    "agentId": "brian_s_test_agent_autfxz7t_agent"
}

Stage 2: Context loading

The user's conversation context is loaded from the context store using the composite key of Agent ID + MSISDN (phone number).

Example
{
  agentId: string;
  sessionId: string;
  msisdn: string;
  lastState?: string;
  currentMessage?: UserMessage;
  parameters: any;  // Accumulated data from operations
  messages: UserMessage[];  // Message history
  input?: StateInput;  // Input configuration from last state
}

Key Points:

  • Context persists between messages
  • TTL ensures automatic cleanup of expired sessions
  • Parameters accumulate data from operations across states

Stage 3: Input processing

The from path in input assignments specifies where to extract data from the conversation context. The system supports two methods for accessing data:

  1. Dot Notation - Simple property access (default)\
  2. JSONPath Expressions - Complex queries (paths starting with $)

Use simple dot notation to access nested properties in the context.

Example: If you want to extract the user's text message, use:

from: "currentMessage.text"

This would extract "Hello" from a message where the user typed "Hello".

Common Paths:

  • currentMessage.text: The user's message text
  • currentMessage.suggestionResponse.postbackData.value: Data from a button click
  • parameters: A pointer to the currentMessage.suggestionResponse.postbackData, overwritten on each message
  • msisdn: User's phone number
  • lastState: Previous state name

How values are extracted

When using dot notation, the system directly accesses the property. If the path doesn't exist, it returns undefined.

Context structure

The context available for extraction includes:

  • currentMessage - The message being processed (text, messageId, sendTime, location, userFile, suggestionResponse)
  • parameters - This is a copy of the currentMessage.suggestionResponse.postbackData
  • agentId - Current agent identifier
  • sessionId - Conversation session ID
  • msisdn - User's phone number
  • messages - Array of conversation history
  • lastState - Name of the previous state
Validation

After extraction, values can be validated:

 {
   "from": "currentMessage.text",
   "to": "userEmail",
   "validation": {
       "required": true,
       "pattern": "(email regex pattern)"
   }
 }

If validation fails, an error is stored in the context and can trigger error handling.

Common use cases
  • Extracting user text: currentMessage.text
  • Getting suggestion selection: currentMessage.suggestionResponse.postbackData
  • Accessing stored data: parameters.savedValue
  • Using previous operation results: parameters.apiResponse.customerId

The from path provides flexible data extraction from the conversation context. Use dot notation for simple property access and JSONPath for complex queries. The extracted values flow into your state's logic, enabling dynamic conversation flows based on user input and accumulated context data.

Stage 4: Operation execution

Operations are executed sequentially, fetching data from external systems and storing results in the context.

Execution process
  1. Load connector configuration
  2. Retrieve authentication credentials
  3. Substitute template variables with context values
  4. Execute API call
  5. Apply JSONPath if specified to extract specific data
  6. Store result at contextKey in context parameters

Stage 5: Template loading & rendering

The message template is loaded and merged with the accumulated context data using LiquidJS templating.

  • Context data is accessible via the context object

Stage 6: Message transmission

The rendered message is sent to the user via the RCS/RBM API.

Final processing
  1. Context data is merged with template
  2. URLs in the message are encoded
  3. Read receipts and typing indicators are sent if configured
  4. Message is transmitted via Vibes RBM API
  5. Context is updated with new input and saved

Complete example flow

User sends Start
1. Message Reception:
 - Incoming: {text: "Start", agentId: "agent_123", msisdn: "+1234567890"}
 - Resolved state: "Welcome"

2. Context Loading:
 - Load existing or create new context for agent_123 + +1234567890

3. Input Processing:
 - No input configuration for "Welcome" state
 - Skip to operations

4. Operation Execution:
 - Execute: GET /api/customer/+1234567890
 - Store result: context.data.customer = {name: "John", tier: "Gold"}

5. Message Transmission:
 - Send rendered message to user
 - Update and Save context with TTL

Error handling

The lifecycle includes error handling at each stage:

  1. State Resolution Errors: Falls back to default state
  2. Validation Errors: Stored in context as context.validationError
  3. Operation Failures: Logged, operation skipped, continues flow
  4. Template Errors: Returns error message to user

Updated about 1 month ago