Skip to main content
The Start function runs when a conversation begins, before the greeting plays. Use it to initialize conversation state, read SIP headers, or make API calls.

​
Key features

  • Synchronous execution: Completes before the greeting plays
  • Context preparation: Stores data for use throughout the conversation

​
Use cases

The Start function can:

​
1. Read connection metadata

  • Capture metadata about the user’s connection—SIP headers for voice, URL parameters or session data for webchat.
  • Example use case: Determine the hotel site or business branch based on telephony headers (voice) or URL parameters (webchat).

​
2. Retrieve date and time

  • Initialize state with the current date, time, or day of the week for timestamping or scheduling logic.
  • Example use case: Preload available time slots for scheduling queries or confirm user-requested dates.

​
3. Makes API calls

  • Fetch external data such as user preferences, account information, or customer records.
  • Example use case: Retrieve and preload personalized data to enhance the conversation’s responsiveness and user experience.

​
4. Choose a language provider

​
Implementation example

Below is a Python implementation of the Start function: 
import datetime as dt
import re

def start_function(conv: Conversation):
    # Retrieve the current date and time
    now = dt.datetime.now()
    conv.state.current_date = now.strftime("%A %d-%m-%Y")
    conv.state.current_weekday = now.strftime("%A")
    conv.state.current_time = now.strftime("%H:%M")

    # Initialize state variables
    conv.state.available_times = None
    conv.state.user_bookings = None
    conv.state.phone_number = None

    # Extract the phone number from SIP headers
    from_header = conv.sip_headers.get('From', '')
    match = re.search(r"sip:(.+?)@", from_header)
    if match:
        conv.state.phone_number = match.group(1)

    # Return an empty string to indicate successful execution
    return str()

​
Best practices for Start function design

  1. Efficient execution: Ensure the function completes quickly to minimize delays in starting the conversation.
  2. Error handling:
    • Handle missing or malformed data and avoids runtime errors.
    • Provide fallbacks for incomplete or invalid information (like missing SIP headers).
  3. State initialization:
    • Predefine and initialize all state variables needed for the conversation to avoid undefined behaviors.
  4. Contextual relevance:
    • Only include setup steps that are directly relevant to the conversation’s purpose.
    • Avoid overloading the Start function with unnecessary logic.

​
Examples: Adding context and personalization

Use the Start function to personalize conversations with user data from SIP headers (voice), URL parameters (webchat), API calls, or stored Variables.

​
Multiple voice agents

Full article: Multi-voice A single deployment can use multiple voice agents. A range of voices acts as a major retention boost for repeat users, because each voice has its own personality and will handle enquiries in subtly different ways.

​
Dynamic user identification

Use information like the user’s phone number (voice), session data (webchat), or metadata to greet them personally and acknowledge their history with your business. Example:
  • “Hello, John! Thank you for calling. How can we assist you today?”
  • “Hi! It looks like you’re calling about your recent order. Would you like to discuss that today?”

​
Personalized recommendations

Make an API call to reference user preferences or interaction history to suggest products, services, or solutions tailored to the user’s needs. Example:
  • “Based on your recent purchases, we think you might like our new line of wireless headphones!”
  • “I see you’ve been interested in our premium package. Would you like to learn more about its benefits?”

​
Preloading relevant context

Prepare scheduling information or past bookings to streamline conversations and save time for the user. Example:
  • “Your last appointment was on January 3rd. Would you like to book another one?”
  • “I see there’s an available time slot tomorrow at 2 PM. Should I reserve that for you?”

​
Customized support based on account details

Retrieve account-specific information, such as subscription plans or recent activity, to provide targeted assistance. Example:
  • “It looks like you’re on our Gold Membership plan. Let me share some exclusive offers with you.”
  • “I see you recently opened a support ticket. Would you like an update on its status?”