Filtering Interactions

The interactions endpoint supports powerful filtering options to help you retrieve exactly the data you need. This guide covers common use cases with practical examples.

Filter Parameters

Parameter	Type	Description
`channel`	string	`voice` or `whatsapp`
`type`	string	Interaction type (varies by channel)
`outcome`	string	Filter by outcome (comma-separated for multiple, e.g., `APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED`)
`clinic_id`	string	Specific clinic UUID
`date_from`	string	Start date (ISO 8601, e.g., `2024-01-15`)
`date_to`	string	End date (ISO 8601, e.g., `2024-01-31`)
`search`	string	Search phone numbers (partial match, e.g., `555` matches `+1-555-123-4567`)

Common Use Cases

Get All WhatsApp Inbound Messages

Retrieve all incoming WhatsApp conversations from patients:

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=INBOUND" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=INBOUND',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'channel': 'whatsapp',
        'type': 'INBOUND'
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Get Voice Campaign Outbound Calls

Retrieve all outbound calls from campaigns (e.g., no-show recovery, reactivation):

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=CAMPAIGN_OUTBOUND" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=CAMPAIGN_OUTBOUND',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'channel': 'voice',
        'type': 'CAMPAIGN_OUTBOUND'
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Get All Appointment Reminders

Retrieve WhatsApp appointment reminder conversations:

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?type=APPOINTMENT_REMINDER" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?type=APPOINTMENT_REMINDER',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'type': 'APPOINTMENT_REMINDER'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Get All Inbound Calls

Retrieve all incoming voice calls:

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=INBOUND" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=INBOUND',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'channel': 'voice',
        'type': 'INBOUND'
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Get Interactions for a Date Range

Retrieve interactions within a specific date range:

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?date_from=2024-01-01&date_to=2024-01-31" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?date_from=2024-01-01&date_to=2024-01-31',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'date_from': '2024-01-01',
        'date_to': '2024-01-31'
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Get Interactions by Outcome

Filter by specific outcomes (e.g., new bookings):

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'outcome': 'APPOINTMENT_BOOKED'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Filter by Clinic

Get interactions for a specific clinic:

curl -X GET "https://api.getdoppel.ai/api/v1/interactions?clinic_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?clinic_id=550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'clinic_id': '550e8400-e29b-41d4-a716-446655440000'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Combine Multiple Filters

You can combine multiple filters for precise queries:

# Get WhatsApp campaign messages from January 2024 for a specific clinic
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=CAMPAIGN_OUTBOUND&date_from=2024-01-01&date_to=2024-01-31&clinic_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const params = new URLSearchParams({
  channel: 'whatsapp',
  type: 'CAMPAIGN_OUTBOUND',
  date_from: '2024-01-01',
  date_to: '2024-01-31',
  clinic_id: '550e8400-e29b-41d4-a716-446655440000'
});

const response = await fetch(
  `https://api.getdoppel.ai/api/v1/interactions?${params}`,
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'channel': 'whatsapp',
        'type': 'CAMPAIGN_OUTBOUND',
        'date_from': '2024-01-01',
        'date_to': '2024-01-31',
        'clinic_id': '550e8400-e29b-41d4-a716-446655440000'
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Pagination

When dealing with large datasets, use pagination:

# Get page 2 with 50 items per page
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?page=2&limit=50" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

Iterating Through All Pages

async function getAllInteractions(apiKey, filters = {}) {
  const interactions = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const params = new URLSearchParams({
      ...filters,
      page: page.toString(),
      limit: '100'
    });

    const response = await fetch(
      `https://api.getdoppel.ai/api/v1/interactions?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );

    const data = await response.json();
    interactions.push(...data.data.interactions);

    hasMore = data.meta.has_more;
    page++;
  }

  return interactions;
}

// Usage: Get all WhatsApp inbounds
const allWhatsAppInbounds = await getAllInteractions('dpl_live_YOUR_API_KEY', {
  channel: 'whatsapp',
  type: 'INBOUND'
});

import requests

def get_all_interactions(api_key, **filters):
    interactions = []
    page = 1
    has_more = True

    while has_more:
        response = requests.get(
            'https://api.getdoppel.ai/api/v1/interactions',
            params={**filters, 'page': page, 'limit': 100},
            headers={'Authorization': f'Bearer {api_key}'}
        )
        data = response.json()

        interactions.extend(data['data']['interactions'])
        has_more = data['meta']['has_more']
        page += 1

    return interactions

# Usage: Get all voice campaign outbounds
all_campaign_calls = get_all_interactions(
    'dpl_live_YOUR_API_KEY',
    channel='voice',
    type='CAMPAIGN_OUTBOUND'
)

Search by Phone Number

Use the search parameter to find interactions by phone number. Search uses partial matching - any phone number containing your search term will be returned.

# Search for interactions with phone numbers containing "555"
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?search=555" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

# Search for a specific phone number (URL-encode the + as %2B)
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?search=%2B34612345678" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

// Search for partial phone number
const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?search=555',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

// Search for specific phone number
const response2 = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?search=' + encodeURIComponent('+34612345678'),
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

# Search for partial phone number
response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'search': '555'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

# Search for specific phone number
response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'search': '+34612345678'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

The search parameter is case-insensitive and matches any part of the phone number. For example, search=555 will match +1-555-123-4567, 555-1234, etc.

Multi-Outcome Filtering

Filter interactions by multiple outcomes at once using comma-separated values. This is useful for getting all appointment-related interactions in a single request.

# Get all appointment-related interactions (booked, modified, or cancelled)
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

const response = await fetch(
  'https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={'outcome': 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED'},
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)

Valid Outcome Values

Outcome	Description
`APPOINTMENT_BOOKED`	New appointment was scheduled
`APPOINTMENT_MODIFIED`	Existing appointment was rescheduled
`APPOINTMENT_CANCELLED`	Appointment was cancelled
`NO_ANSWER`	Call was not answered
`VOICEMAIL_REACHED`	Call went to voicemail
`CALLBACK_REQUESTED`	Patient requested a callback
`OPT_OUT`	Patient opted out of communications
`DECISION_PENDING`	Patient needs more time to decide

Outcome values are case-sensitive and must be UPPERCASE. Invalid values will return a 400 validation error.

Get All Bookings

A common use case is retrieving all appointment-related interactions from a date range:

# Get all bookings and modifications from the last 30 days
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED&date_from=2024-12-06&date_to=2025-01-05" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

// Get all appointment-related interactions from last 30 days
const today = new Date();
const thirtyDaysAgo = new Date(today);
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

const params = new URLSearchParams({
  outcome: 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
  date_from: thirtyDaysAgo.toISOString().split('T')[0],
  date_to: today.toISOString().split('T')[0]
});

const response = await fetch(
  `https://api.getdoppel.ai/api/v1/interactions?${params}`,
  {
    headers: {
      'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
    }
  }
);
const { data } = await response.json();

console.log(`Found ${data.interactions.length} appointment interactions`);

import requests
from datetime import datetime, timedelta

today = datetime.now()
thirty_days_ago = today - timedelta(days=30)

response = requests.get(
    'https://api.getdoppel.ai/api/v1/interactions',
    params={
        'outcome': 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
        'date_from': thirty_days_ago.strftime('%Y-%m-%d'),
        'date_to': today.strftime('%Y-%m-%d')
    },
    headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
)
data = response.json()

print(f"Found {len(data['data']['interactions'])} appointment interactions")

Quick Reference: Filter Combinations

Use Case	Filters
All inbound calls	`channel=voice&type=INBOUND`
All outbound campaign calls	`channel=voice&type=CAMPAIGN_OUTBOUND`
Callback calls	`channel=voice&type=CAMPAIGN_CALLBACK`
Form-triggered calls	`channel=voice&type=FORM_OUTBOUND`
All inbound WhatsApp	`channel=whatsapp&type=INBOUND`
WhatsApp campaigns	`channel=whatsapp&type=CAMPAIGN_OUTBOUND`
Appointment reminders	`type=APPOINTMENT_REMINDER`
New bookings	`outcome=APPOINTMENT_BOOKED`
All appointment changes	`outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED`
Last 30 days	`date_from=2024-12-06&date_to=2025-01-05`
Search by phone	`search=555` (partial match)

API Reference

Interactions

Metrics

Campaigns

Clinics

Filtering Interactions

Filtering Interactions

Filter Parameters

Common Use Cases

Get All WhatsApp Inbound Messages

Get Voice Campaign Outbound Calls

Get All Appointment Reminders

Get All Inbound Calls

Get Interactions for a Date Range

Get Interactions by Outcome

Filter by Clinic

Combine Multiple Filters

Iterating Through All Pages

Search by Phone Number

Multi-Outcome Filtering

Valid Outcome Values

Get All Bookings

Quick Reference: Filter Combinations

​Filtering Interactions

​Filter Parameters

​Common Use Cases

​Get All WhatsApp Inbound Messages

​Get Voice Campaign Outbound Calls

​Get All Appointment Reminders

​Get All Inbound Calls

​Get Interactions for a Date Range

​Get Interactions by Outcome

​Filter by Clinic

​Combine Multiple Filters

​Pagination

​Iterating Through All Pages

​Search by Phone Number

​Multi-Outcome Filtering

​Valid Outcome Values

​Get All Bookings

​Quick Reference: Filter Combinations

Filtering Interactions

Filter Parameters

Common Use Cases

Get All WhatsApp Inbound Messages

Get Voice Campaign Outbound Calls

Get All Appointment Reminders

Get All Inbound Calls

Get Interactions for a Date Range

Get Interactions by Outcome

Filter by Clinic

Combine Multiple Filters

Pagination

Iterating Through All Pages

Search by Phone Number

Multi-Outcome Filtering

Valid Outcome Values

Get All Bookings

Quick Reference: Filter Combinations