Skip to main content

Campaigns: Orchestrate large-scale, multi-stage communication sequences

Campaigns enable you to orchestrate large-scale, multi-stage communication sequences with your contacts using one or more agents. While a single agent can only handle one conversation at a time, campaigns allow you to:

  • Communicate with thousands of contacts automatically
  • Plan multi-stage communication sequences (email → WhatsApp → phone call)
  • Schedule messages at specific times
  • Track results across all communications
  • Apply business logic to determine next actions

Prerequisites​

Before setting up campaigns, ensure you have:

  • At least one configured AI agent
  • Necessary integrations set up (WhatsApp, email, etc.)
  • Contact data prepared in CSV or JSON format
  • Basic understanding of Python for strategy development

Key Concepts​

Campaign Structure​

A campaign consists of three main components:

  1. Stages - Define the communication steps and channels
  2. Strategies - Python code that controls campaign logic
  3. Contacts - The people you're communicating with

Stages​

Stages represent different steps in your communication sequence. Each stage can use a different:

  • Communication channel (email, WhatsApp, phone)
  • Agent configuration
  • Message template

Example sequence:

  1. Email notification
  2. WhatsApp message (if no response)
  3. Phone call (if still no response)
  4. Final email reminder

Strategies​

Strategies are Python scripts that control how your campaign operates. They handle:

  • When to send communications
  • Which stage to move contacts to
  • How to process conversation results
  • Business logic and decision-making

Contacts​

Contacts are the people your campaign communicates with. Each contact has:

  • System fields: Name, email, phone, Object ID, External ID
  • Campaign Parameters: Data imported with the contact
  • Campaign Results: Information collected during the campaign

Campaign Interface​

Campaign Sections​

When you open a campaign, you'll see three main tabs:

1. Stages Tab​

View and manage your communication stages:

  • Stage name and description
  • Communication channel
  • Assigned agent
  • Edit and reorder stages

2. Strategies Tab​

Manage Python scripts that control campaign behavior:

  • Strategy name and type
  • Python code file
  • Function to execute
  • View, edit, or delete strategies

3. Contacts Tab​

Monitor and manage campaign contacts:

  • Contact information
  • Current stage
  • Communication count
  • Campaign parameters and results

Creating Campaign Stages​

The Stages screen allows you to configure steps for processing a contact group: define the stage name and description, select a communication channel using a previously configured AI agent, and apply additional settings based on the selected channel.

Adding a Stage​

  1. Navigate to Stages tab
  2. Click "+Add Stage"
  3. Configure stage settings:
    • Name: Descriptive stage name
    • Description: Purpose of this stage
    • Channel: Select communication method
    • Agent: Choose the agent for this stage
    • Template: Message template (channel-specific)

Available Channels​

  • Email Notification: One-way email messages
  • Email Communication: Two-way email conversations
  • WhatsApp: WhatsApp Business messaging
  • SIP/Twilio: Voice phone calls
  • Human: Manual human agent handling
  • No Communication: Final campaign stage

Channel Configuration Examples​

Email Notification Stage

Use case: One-way email messages for notifications, reminders, or announcements.

Required fields: Integration, Email subject, Email template

  1. From the main Campaign screen, click on the desired campaign to access its settings
  2. Go to the Stages screen and click "+Add Stage"
  3. In the "Create Stage" modal window, fill in the following fields:
    1. Name – Name of the stage (include sequence number for clarity)
    2. Description – Short description of the campaign stage
    3. Channel – Select Email Notification
    4. Integration – Choose the integration used to send the email
    5. Email subject – Subject line of the email
    6. Email template – Email body template
  4. Click "Save" to save the stage
How to configure a stage with an AI agent via email communication

Use case: Two-way email conversations where the AI agent can respond to replies and engage in back-and-forth communication.

Required fields: Agent, Email subject, Email template

  1. Navigate to the campaign's settings and open the Stages screen
  2. Click "+Add Stage"
  3. Fill in the following fields:
    1. Name
    2. Description
    3. Channel – Select Email Communication
    4. Agent – Choose the configured AI agent
    5. Email subject
    6. Email template
  4. Click "Save"
How to configure a stage handled by a human employee

Use case: Manual handling by human agents for complex cases that require personal attention or escalation.

Required fields: None (only basic stage information)

  1. Navigate to the campaign's settings and open the Stages screen
  2. Click "+Add Stage"
  3. Fill in the following fields:
    1. Name
    2. Description
    3. Channel – Select Human
  4. Click "Save"
How to configure a stage with an AI agent via MessageBird (WhatsApp)

Use case: WhatsApp Business messaging through MessageBird platform with template-based communications.

Required fields: Agent, Project ID, Version, Start state

  1. Open the campaign settings and go to Stages
  2. Click "+Add Stage"
  3. Fill in:
    1. Name
    2. Description
    3. Channel – Select MessageBird (WhatsApp)
    4. Agent
    5. Project ID – Template project ID from Bird (Bird Portal → Developer → Channels → WhatsApp → Templates Management)
    6. Version – Template version
    7. Start state – AI Agent's initial state in the workflow
  4. Click "Save"
How to configure a stage with an AI agent via WhatsApp (Meta)

Use case: Direct WhatsApp Business messaging through Meta's platform using approved message templates.

Required fields: Agent, Start state, Template Name

  1. Open campaign settings → Stages → "+Add Stage"
  2. Fill in:
    • Name – Include sequence number for clarity
    • Description – Purpose of this stage
    • Channel – Select Email Notification
    • Integration – Choose email integration
    • Email subject – Subject line
    • Email template – Email body template
  3. Click "Save"
How to configure a stage with an AI agent via Telegram

Use case: Messaging through Telegram for regions where it's the preferred communication channel.

Required fields: Agent

  1. Open campaign settings → Stages → "+Add Stage"
  2. Fill in:
    1. Name
    2. Description
    3. Channel – Select Telegram
    4. Agent
  3. Click "Save"
How to configure a stage with an AI agent via SIP telephony

Use case: Voice calls using Session Initiation Protocol for direct phone communication.

Required fields: Agent

  1. Open campaign settings → Stages → "+Add Stage"
  2. Fill in:
    1. Name
    2. Description
    3. Channel – Select SIP (Session Initiation Protocol)
    4. Agent
  3. Click "Save"
How to configure a stage with an AI agent via Twilio

Use case: Voice calls through Twilio platform for scalable phone communication.

Required fields: Agent, Start state

  1. Open campaign settings → Stages → "+Add Stage"
  2. Fill in:
    1. Name
    2. Description
    3. Channel – Select Twilio
    4. Agent
    5. Start state – Defined in the Strategies code during campaign setup
  3. Click "Save"
How to configure a final campaign stage

Use case: Terminal stage that ends the campaign sequence without further communication.

Required fields: Start state

  1. Go to the campaign's settings → Stages → "+Add Stage"
  2. Fill in:
    1. Name
    2. Description
    3. Channel – Select No Communication
    4. Start state – Defined in Strategies code
  3. Click "Save"
How to configure alternative stage settings

Use case: Set up alternate communication paths with weighted probabilities to create A/B testing scenarios or channel fallbacks.

Required fields: Label, Weight, Channel-specific settings

Additional configurations allow setting up alternate communication paths — for example, using different channels with weighted probabilities to adjust the default scenario.

To add an alternative configuration:

  1. While on the "Create Stage" or "Edit Stage" screen, click "+Add"
  2. In the new entry, fill in:
    1. Label – Name of the alternative configuration
    2. Weight – Weight that determines how often the alternative replaces the default
    3. Channel – Choose the communication channel and follow the instructions specific to that channel

Working with Strategies​

Strategies implement business logic for automated communication sequences. They're written in Python and can reference campaign entities and integrate with external services.

Strategy Types​

Campaigns use three types of strategies, executed at different times:

1. Data Load Strategy​

When executed: When importing new contacts

Purpose:

  • Initialize contact data
  • Plan initial communications
  • Handle duplicate contacts

Basic structure:

async def run(contact: Contact, existing_contact: Contact | None, logger, **kwargs) -> Contact:
    # Check if contact already exists
    if existing_contact is not None:
        # Handle existing contact logic
        pass
    
    # Plan first communication
    first_comm = Communication(
        name="Initial Message",
        stage_name="First Contact",
        start_date=datetime.now() + timedelta(hours=1),
        # ... other settings
    )
    contact.communications.append(first_comm)
    
    # Set initial stage
    contact.current_stage = "First Contact"
    
    return contact

2. Aggregation Strategy​

When executed: After a communication session ends

Purpose:

  • Process conversation results
  • Determine next actions
  • Schedule follow-up communications

Basic structure:

async def run(contact: Contact, session_results: dict | None, logger, **kwargs) -> Contact:
    # Mark current communication as completed
    for comm in contact.communications:
        if comm.flagged:
            comm.status.status = CommunicationStatus.COMPLETED
    
    # Check conversation outcome
    outcome = session_results.get("OutcomeStatus", "NO_RESPONSE")
    
    # Plan next action based on outcome
    if outcome == "NO_RESPONSE":
        # Schedule follow-up
        next_comm = Communication(
            name="Follow-up",
            stage_name="Second Attempt",
            start_date=datetime.now() + timedelta(days=1),
            # ... other settings
        )
        contact.communications.append(next_comm)
    
    return contact

3. Contact Answer Intermediate Analysis Strategy​

When executed: After each agent response during a conversation

Purpose:

  • Monitor ongoing conversations
  • Update contact status in real-time
  • Make decisions during long conversations

Basic structure:

async def on_agent_answer(contact: Contact, message: Message, **kwargs) -> Contact | None:
    # Update last interaction time
    contact.internal_data["last_message_time"] = datetime.now()
    
    # Check message content and update stage if needed
    if "promise to pay" in message.content.lower():
        contact.current_stage = "Payment Promised"
    
    return contact

Strategy Development​

Strategies can:

  • Access and modify contact data
  • Schedule new communications
  • Update campaign results
  • Call external APIs
  • Apply business logic

Managing Contacts​

The Contacts screen provides tools to manage the group of contacts that your campaign will interact with.

Importing Contacts​

  1. Click Upload new contacts in Contacts tab
  2. Prepare your file (CSV or JSON format)
  3. Upload the file

Required Contact Fields​

Your import file must include these fields:

FieldDescriptionExample
nameContact's full nameJohn Smith
emailEmail addressjohn@example.com
phonePhone number with country code+1234567890
object_idUnique identifier for the campaign subjectCONTRACT-123
external_idUnique identifier for the personUSER-456

CSV file example​

Object_id,External_ID,Name,Email,Phone,add_param1,add_param2
123,123,John Doe,john@example.com,+1234567890,12,"Additional data"
456,456,Jane Smith,jane@example.com,+0987654321,34,"More data"

JSON file example​

{"Object_id": "123", "External_ID": "123", "Name": "John Doe", "Email": "john@example.com", "Phone": "+1234567890"}
{"Object_id": "456", "External_ID": "456", "Name": "Jane Smith", "Email": "jane@example.com", "Phone": "+0987654321"}

Additional Fields​

You can include any additional fields needed for your campaign:

  • Due dates
  • Amount owed
  • Account numbers
  • Custom attributes

These become available as Campaign Parameters in your strategies.

Contact Status Tracking​

Each contact shows:

  • Current Stage: Where they are in the campaign
  • Communications: Number of messages sent/received
  • Parameters: Imported data
  • Results: Collected information

Click the communication count to see detailed communication history.

Campaign Workflow Example​

Here's how a typical debt collection campaign might work:

  1. Import contacts with debt information
  2. Data Load Strategy schedules initial email
  3. Email sent through Email Notification stage
  4. No response after 3 days
  5. Aggregation Strategy schedules WhatsApp message
  6. WhatsApp conversation begins
  7. Customer promises to pay
  8. Intermediate Analysis updates status
  9. Aggregation Strategy schedules reminder
  10. Campaign completes when payment confirmed

Best Practices​

Campaign Design​

  • Start simple: Begin with 2-3 stages and expand as needed
  • Test thoroughly: Use test contacts before full deployment
  • Monitor regularly: Check campaign progress daily
  • Document logic: Comment your strategy code clearly

Stage Configuration​

  • Clear naming: Use descriptive stage names
  • Logical flow: Order stages by priority and timing
  • Agent specialization: Use different agents for different channels if necessary
  • Template variety: Avoid repetitive messaging

Contact Management​

  • Data quality: Ensure contact information is accurate
  • Batch sizing: Import contacts in manageable batches
  • Regular updates: Re-import to update contact information
  • Result tracking: Monitor campaign results for optimization

Strategy Guidelines​

  • Error handling: Always include try-catch blocks
  • Logging: Use logger for debugging
  • Time zones: Consider contact time zones for scheduling
  • Business hours: Respect communication time restrictions

Monitoring Campaign Performance​

Using Sessions​

Access detailed conversation records:

  1. Navigate to Sessions
  2. Filter by campaign agent
  3. Review conversation quality
  4. Analyze collected results

Optimization​

Based on performance data:

  • Adjust message timing
  • Modify stage sequences
  • Update agent instructions
  • Refine strategy logic

Common Issues & Solutions​

Communications not sending

Causes: Stage misconfiguration, inactive agent, integration issues

Solutions:

  • Check stage configuration
  • Verify agent is active
  • Review strategy logs
  • Confirm channel integration
Contacts stuck in stage

Causes: Aggregation strategy logic issues, session completion problems

Solutions:

  • Check aggregation strategy logic
  • Verify session completion
  • Review error logs
  • Test with single contact
Import failures

Causes: Missing required fields, incorrect data formats, file encoding issues

Solutions:

  • Validate required fields
  • Check data formats
  • Verify file encoding
  • Review error messages
Strategy debugging issues

Causes: Logic errors, missing error handling, insufficient logging

Solutions:

  1. Use logger extensively in strategies
  2. Test with small contact batches
  3. Monitor strategy execution logs
  4. Add defensive programming practices

Common Examples​

Pre-Collection Campaign​

Remind customers about upcoming payments:

  1. Email reminder 7 days before due date
  2. WhatsApp message 3 days before
  3. Phone call on due date
  4. Follow-up email if payment missed

Sales Outreach Campaign​

Qualify and nurture leads:

  1. Initial email introduction
  2. WhatsApp follow-up for interested leads
  3. Phone call to qualified prospects
  4. Email nurture sequence for not-ready leads

Customer Feedback Campaign​

Collect satisfaction data:

  1. Email survey invitation
  2. WhatsApp reminder for non-responders
  3. Phone call for VIP customers
  4. Thank you email for participants

FAQ​

How do I connect WhatsApp to my campaign?

To use WhatsApp in campaigns, you need to:

  1. Register WhatsApp Business API through Meta Business Account
  2. Create WhatsApp integration in Flametree:
    • Go to Integrations → WhatsApp → Add
    • Fill in Bot Token, Application ID, Phone Number ID, etc.
  3. Configure WhatsApp stage in your campaign:
    • Select WhatsApp channel
    • Choose your agent
    • Set template name and start state

For detailed setup instructions, see the WhatsApp registration guide in the FAQ section.

What file formats are supported for contact import?

Supported formats for contact import:

  • CSV: Comma-separated values with headers
  • JSON: JSON Lines format (one JSON object per line)

Both formats must include required fields: name, email, phone, object_id, external_id.

How do I debug strategy execution issues?

To debug strategy issues:

  1. Use extensive logging in your Python strategies
  2. Test with small batches of contacts first
  3. Monitor strategy execution logs in the campaign interface
  4. Add defensive programming practices like try-catch blocks
  5. Check agent status - ensure it's not in "Error" state
Can I use the same agent across multiple campaign stages?

Yes, you can use the same agent across multiple stages. However, consider:

  • Agent specialization: Different agents for different channels may be more effective
  • Workflow states: Ensure the agent's workflow supports all required states
  • Load balancing: One agent handles one conversation at a time
What happens if a contact doesn't respond to communications?

Non-responsive contacts are handled by your Aggregation Strategy:

  1. Strategy checks session results after each communication
  2. If no response detected, it can schedule follow-up communications
  3. You can set maximum retry limits and timeouts
  4. Eventually move contact to final stage or mark as unsuccessful