Skip to main content

Python-Based Campaigns

Python-based campaigns give you full control over how the system processes contacts. You define campaign stages — each tied to a communication channel and an AI agent — and write Python strategies that run at key points: when contacts are imported, after a conversation ends, or after each agent message. This makes Python campaigns suitable for complex multi-step sequences.

info

If you don't need custom Python logic, use flow-based campaigns instead — they cover the majority of campaign scenarios without programming. For a comparison of both types, see Campaigns: Overview.

Prerequisites​

Before setting up a Python-based campaign, ensure you have:

  • At least one configured AI agent
  • Required integrations set up: WhatsApp, email, or other channels you plan to use
  • Contact data prepared in CSV or JSON format
  • Python development experience

Campaign Interface​

When you open the Campaigns section, the interface is divided into two main areas: the campaign list on the left and the analytics panel on the right.

By default, the list is filtered to show only Running campaigns. You can switch to the All tab at the top to view campaigns in any status.

(Note: This default Running filter is also applied to the AI Agents section).

Campaign Analytics Panel​

When you select a campaign from the list, the right panel displays an out-of-the-box performance overview and baseline analytics. This allows you to evaluate effectiveness without requiring custom reports. Depending on the campaign data, this panel provides:

  • Metrics overview: Total contacts, Processed contacts, Completion Rate, and Success Rates.
  • Visual charts: Stage Distribution by Period and Status Distribution by Period.
  • Quick access to View Deep Analysis for more granular, LLM-based insights.

Campaign Statuses​

Each campaign has a global status that defines its current state:

  • CREATED: The campaign is created, but contact processing hasn't started or no contacts are loaded.
  • CONFIGURED: The campaign is fully set up and ready to run.
  • RUNNING: The campaign is actively processing contacts and sending communications.
  • STOPPED: The campaign was manually stopped. Processing is paused.
  • FINISHED: The campaign has completed. All contacts have received a final result.
  • ERROR: The campaign cannot proceed due to a technical or logical error.

Campaign Configuration Tabs​

When you open a specific campaign for editing, you can navigate through four main tabs:

1. Stages Tab​

View and manage your communication stages. The list displays:

  • Name: Stage name and description.
  • Configs: Communication channel and assigned agent.
  • Options to edit, delete, or add new stages.

2. Strategies Tab​

Manage Python scripts that control campaign behavior:

  • Name: Strategy name.
  • Type: Strategy type (for example, DATA_LOAD, AGGREGATION).
  • Options to view code, edit, or delete strategies.

3. Contacts Tab​

Monitor and manage campaign contacts. You can upload new contacts or download existing ones. The table includes:

  • Contact Details: Name, Email, Phone.
  • Current stage: Where the contact is currently located in the workflow.
  • Communications: Number of communication attempts made.
  • Outcome: The current business status of the contact (for example, Positive, Success, Negative, Uncertain).

4. Settings Tab​

Manage global campaign configurations:

  • LLM Settings: Select the language model for the campaign.
  • YAML Analytics: Set up YAML configurations for Deep Analysis.
  • Campaign Results: Define custom result fields (Code, Name, Description) to be collected during the campaign.

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 the 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)
  4. Click Save to apply the changes

Available Channels​

A channel represents the communication method used with clients.

  • Email Notification: One-way email messages
  • Email Communication: Two-way email conversations
  • Human: Manual human agent handling
  • MessageBird (WhatsApp): Two-way WhatsApp messaging via MessageBird
  • MessageBird Webhook (WhatsApp): Incoming WhatsApp messages via Webhook
  • Mobile Push: Push notifications sent to a mobile phone
  • No Communication: Final campaign stage
  • SIP/Twilio: Voice phone calls
  • Telegram: Telegram messaging
  • WhatsApp: WhatsApp Business messaging

Channel Configuration Examples​

How to configure a stage with an AI Agent via Email Notification

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

Required fields: Integration, Email subject, Email template

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. In the Create Stage modal window, fill in the following fields:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel — Select Email Notification
    • Integration – Select the integration used to send the email
    • Email subject – Subject line of the email
    • Email input type — Select the editor mode:
      • Default: Standard rich text editor. Best for simple, text-based emails.
      • HTML: Raw HTML code editor. Use this to paste custom HTML templates (for example, for newsletters or branded designs) to ensure exact rendering without automatic formatting wrappers
    • Email template - Email body template
    • Email template preview — Preview of how your email will look like in client's inbox
  4. Click Save to apply the changes
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. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in the following fields:
    • Name – Name of the stage: include sequence number for clarity
    • Description – Short description of the campaign stage and its purpose
    • Channel — Select Email Communication
    • Agent – Select a configured AI Agent
      • Agent with integration — if you have integration configured
      • Agent with channel — if channels are configured, choose the Agent with channel from the dropdown list. Then, in Agent channel, select the channel the agent will communicate through
    • Email subject — Subject line of the email
    • Email input type — Select the editor mode:
      • Default: Standard rich text editor. Best for simple, text-based emails.
      • HTML: Raw HTML code editor. Use this to paste custom HTML templates (for example, for newsletters or branded designs) to ensure exact rendering without automatic formatting wrappers
    • Email template - Email body template
    • Email template preview — Preview of how your email will look like in client's inbox
  4. Click Save to apply the changes
How to configure a stage handled by a Human agent

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

Required fields: None (only basic stage information)

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in the following fields:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select Human
    • Agent — Select agent's role
  4. Click Save to apply the changes
How to configure a stage with an AI Agent via Infobip
  1. Open the campaign settings and go to Stages
  2. Click +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select Infobip
    • Agent — Select a configured AI Agent
    • Agent channel — Select the channel the agent will communicate through
    • Start phrase – AI Agent's initial phrase in the workflow
  4. Click Save to apply the changes
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. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select MessageBird (Whatsapp)
    • Agent – Select a configured AI Agent
    • Version – Template version
    • Start state – AI Agent's initial state in the workflow
  4. Click Save to apply the changes
How to configure a stage with an AI Agent via MessageBird Webhook (WhatsApp)

Use case: WhatsApp Business messaging through MessageBird Webhook

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select MessageBird Webhook (Whatsapp)
    • Agent – Select a configured AI Agent
    • Agent channel — Select the channel the agent will communicate through
  4. Click Save to apply the changes
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: Start state, Template Name

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select WhatsApp
    • Agent – Select a configured AI Agent
    • Start state – AI Agent's initial state in the workflow
    • Template Name – Meta approved message template (Meta Business Manager > WhatsApp > Message Templates)
  4. Click Save to apply the changes
How to configure a stage with Mobile Push

Use case: AI Agent should be configured to send push notifications. To configure push notifications go to Agent > View agent > find Advanced at right sidebar > press + at Set push notification configuration

Required fields: none

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select Mobile Push
    • Agent — Select a configured AI Agent
  4. Click Save to apply the changes
How to configure a stage with an AI agent via Telegram

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

Required fields: Agent

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select Telegram
    • Agent – Select a configured AI Agent
      • Agent with integration — If you have integration configured, choose the Agent with integration from the dropdown list
      • Agent with channel — if channels are configured, choose the Agent with channel from the dropdown list. Then, in Agent channel, select the channel the agent will communicate through
    • Start phrase – AI Agent's initial phrase in the workflow. It is defined in the Strategies code during campaign setup
  4. Click Save to apply the changes
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. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select SIP (Session Initiation Protocol)
    • Agent — Select a configured AI Agent
  4. Click Save to apply the changes
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. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select Twilio
    • Agent — Select a configured AI Agent
    • Start state – AI Agent's initial state in the workflow. Defined in the Strategies code during campaign setup
  4. Click Save to apply the changes
How to configure a final campaign stage

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

Required fields:

  1. From the main Campaign screen, choose the campaign you wish to view
  2. Navigate to Stages > +Add Stage
  3. Fill in:
    • Name – Name of the stage (include sequence number for clarity)
    • Description – Short description of the campaign stage and its purpose
    • Channel – Select No Communication
  4. Click Save to apply the changes
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. Enable the A/B Testing toggle in the upper right corner.
  3. In the new entry, fill in:
    • Label – Name of the alternative configuration
    • Weight – Weight that determines how often the alternative replaces the default
    • Channel – Choose the communication channel and follow the instructions specific to that channel
  4. Click Save to apply the changes

Working with Strategies​

Strategies implement business logic for automated communication sequences. Strategies are 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
object_idUnique identifier for the campaign subjectCONTRACT-123
external_idUnique identifier for the personUSER-456
nameContact's full nameJohn Smith
emailEmail addressjohn@example.com
phonePhone number with country code+1234567890

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're in the campaign
  • Communications: Number of messages sent/received
  • Parameters: Imported data
  • Results: Collected information

Click the communication count to see detailed communication history.

A communication may be marked as MISSED if it was not started at the intended time. The platform automatically starts communications only within their planned time window. If that moment is missed, the communication is not started later to avoid sending outdated or irrelevant messages.

Managing Campaign Settings​

The Settings tab includes three configuration sections: LLM Settings, YAML Analytics, Campaign Results. These sections help set up analytics for the campaign.

LLM Settings​

Click Select and, from the dropdown list, choose the LLM to use in your campaign.

YAML Analytics​

Click Set YAML analytics to upload a YAML file that defines the metrics to be collected during the campaign — for example, client satisfaction, interest, and other indicators. The file also includes settings such as the analytics duration and how the results should be displayed. Read more about how to configure a YAML in the Deep Analysis article.

These metrics will then be displayed in the Analytics > Deep Analysis section.

The available options are:

  • Upload YAML — Upload a new or an updated YAML file
  • Download YAML — Download the YAML file currently used by the campaign. If the button is inactive, no YAML file is uploaded for this campaign
  • Status:
    • Done — The YAML file is uploaded, and the scheduled analysis is complete
    • Progress — The analysis is still running. In this case, an active Stop button appears — click it if you need to stop the running analysis
  • Recalculate — Runs instant analytics if you have uploaded an updated YAML file and want to apply the new metrics to previous sessions. This action applies all changes from the updated YAML file: new or updated metrics, calculation algorithms, and other instructions
  • Continue calculation — Recalculates only the new metrics from the updated YAML file for previous sessions
note

The number of days for which Recalculate and Continue calculation process the metrics is defined in the Depth parameter of the YAML file.

Campaign Results​

In this section, define the results you wish to display for your campaign collected through the Strategies. These results will be displayed in the 360 View section.

Campaign results consist of:

Default Result Fields​

All campaigns include two built-in result fields that provide a consistent way to track campaign completion and outcome status. These fields are created automatically and do not require configuration.

ResultFlag​

A boolean field indicating whether the campaign result has been achieved. Possible values:

  • true — campaign result achieved
  • false — campaign result not achieved
  • null — campaign result not yet determined
ResultDatetime​

A date and time field that indicates when the campaign result is determined. The value updates whenever the result changes. The field is populated only when ResultFlag is set to true or false and remains null when the result is not yet determined.

These fields ensure consistent tracking, reporting, and automation logic across all campaigns.

Custom result fields​

In addition to the default fields, you can define custom results to display specific metrics collected from your strategies.

To add custom results:

To add the results you wish to display:

  • Click +Add results in the section
  • Add Code — session_results field from the Strategies to be displayed in 360 View > Results.
  • Add Name of the metric
  • Add Description — A brief description of the metric's purpose

Custom results are displayed in 360 View > Results alongside the default result fields.

Campaign Workflow Example​

Here is 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

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

Was this article helpful?