This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SeaX API Wiki

Overview

Welcome to the SeaX API Wiki. This site serves as the central hub for all developer documentation related to the Seasalt.ai SeaX platform. The SeaX API provides secure access to workspace-level data and comprehensive communication management capabilities, enabling you to build powerful integrations and automated workflows.

SeaX offers a complete suite of communication tools including bulk SMS/MMS messaging, webhook notifications for real-time event updates, and advanced analytics for monitoring and optimization. Whether you’re building a simple messaging integration or a complex multi-channel communication platform, SeaX provides the tools and insights you need.

The SeaX platform is built to scale with your business needs, whether you’re sending a few hundred messages per month or managing millions of communications across multiple campaigns. The API provides robust features for compliance management, delivery tracking, customer engagement optimization, real-time event notifications, and comprehensive analytics to help you make data-driven decisions.

Whether you’re just getting started or looking to integrate advanced features, this documentation will guide you through everything you need to know.

Key Features

Currently supported core features include:

  • Bulk SMS/MMS Messaging: Send thousands or millions of messages efficiently with advanced delivery optimization
  • Webhook Notifications: Receive real-time event notifications from Seasalt.ai, enabling instant updates and seamless system integration
  • Analytics: Access insights and usage metrics to help you monitor activity and make data-driven decisions
  • Contact Management: Robust import/export capabilities with sophisticated labeling and segmentation
  • Compliance Management: Automatic Do Not Contact handling and comprehensive opt-out management
  • Delivery Tracking: Real-time status updates and detailed analytics for all messaging operations

Sending Capabilities

Bulk SMS/MMS Messaging

SeaX excels at handling large-scale messaging operations, allowing you to send thousands or millions of SMS and MMS messages efficiently. The bulk messaging system is designed to handle high-volume campaigns while maintaining delivery reliability and speed.

The platform supports both SMS (text-only) and MMS (multimedia) messages, enabling you to send rich content including images, videos, and other media files. This multimedia capability allows for more engaging customer communications and higher response rates compared to text-only messaging.

The bulk messaging system includes intelligent queuing and throttling mechanisms to ensure optimal delivery rates while respecting carrier limitations and maintaining good sender reputation. Messages are processed through multiple carrier networks to ensure maximum deliverability and redundancy.

Scheduled Messaging

One of the most powerful features of SeaX is its ability to schedule messages up to 7 days in advance. This scheduling capability enables you to plan and execute time-sensitive campaigns, send messages at optimal times for your audience, and automate recurring communications.

The scheduling system takes into account time zones, business hours, and customer preferences to optimize message delivery timing. You can schedule individual messages or entire campaigns, and the system provides confirmation and status updates as scheduled messages are processed.

Advanced scheduling features include the ability to modify or cancel scheduled messages before they’re sent, bulk scheduling operations, and integration with external calendar systems for complex campaign coordination.

Bulk Voice Drops

SeaX makes it easy to deliver pre-recorded voice messages to large groups of contacts with just a few clicks. This powerful feature is ideal for announcements, reminders, emergency alerts, or any campaign where a personal touch via voice is more effective than text.

With bulk voice drops, you can upload your audio, select your audience, and send out thousands of voice messages in a highly scalable and efficient way. The system handles call distribution automatically, ensuring high deliverability and minimal manual effort.

AI Agent Campaigns

SeaX empowers you to connect your customers with AI agents you’ve tailored to your business. SeaX makes it easy to place bulk call campaigns that drive real-time, automated conversations.

Customers can speak freely with your automated agents through natural, two-way voice conversations. Perfect for lead qualification, appointment scheduling, surveys, and more.

Do Not Contact Compliance

SeaX automatically respects “Do Not Contact” (DNC) preferences and maintains comprehensive opt-out management. The system automatically processes standard opt-out keywords like “STOP,” “UNSUBSCRIBE,” and “REMOVE ME,” ensuring compliance with telecommunications regulations and customer preferences.

The DNC management system maintains a centralized database of opt-out preferences that’s automatically consulted before any message is sent. This prevents accidental messaging to customers who have opted out and helps maintain compliance with regulations like TCPA and CAN-SPAM.

Customers can opt back in through various mechanisms, and the system maintains a complete audit trail of all opt-in and opt-out activities for compliance reporting and customer service purposes.

Delivery Reports and Analytics

Comprehensive delivery reporting provides detailed insights into message performance, delivery rates, and customer engagement. The system tracks messages through the entire delivery pipeline, providing real-time status updates and detailed analytics.

Delivery reports include information about successful deliveries, failed attempts, bounce reasons, and carrier-specific delivery data. This information is crucial for optimizing message content, timing, and targeting to improve overall campaign performance.

Advanced analytics features include delivery rate trending, carrier performance analysis, and customer engagement metrics that help you understand how your messaging campaigns are performing and where improvements can be made.

Multi-number Support

SeaX supports sending messages from multiple phone numbers, enabling you to scale your messaging operations and maintain separate numbers for different types of communications or business units. This multi-number capability also provides redundancy and helps distribute messaging load across multiple carrier connections.

You can assign specific phone numbers to different campaigns, customer segments, or message types, allowing for better organization and tracking of your messaging activities. The system automatically manages number rotation and load balancing to optimize delivery performance.

Receiving Capabilities

Auto Opt-in and Opt-out Processing

The platform automatically captures and processes opt-in and opt-out requests from customers, maintaining compliance with regulatory requirements while providing a seamless experience for customers who want to manage their communication preferences.

The auto opt-in system can process various types of opt-in requests, including keyword-based opt-ins, web form submissions, and API-driven opt-ins from other systems. All opt-in activities are logged with timestamps and source information for compliance auditing.

The opt-out processing system recognizes standard opt-out keywords and phrases, automatically updating customer preferences and sending confirmation messages as required by regulations. The system also supports custom opt-out keywords and can be configured to handle industry-specific opt-out requirements.

Reply Handling and Customer Engagement

SeaX provides sophisticated reply handling capabilities that enable two-way conversations with customers. The system can automatically route replies to appropriate handlers, trigger automated responses, or forward messages to human operators for personal attention.

The reply handling system maintains conversation context and can trigger different actions based on message content, customer history, and predefined rules. This enables sophisticated customer service workflows and automated support scenarios.

Advanced reply handling features include sentiment analysis, automatic escalation for urgent issues, and integration with CRM systems to provide complete customer interaction history.

Keyword Matching and Auto-responses

The platform includes a powerful keyword matching engine that can automatically respond to customer messages based on predefined keywords and phrases. This automation capability enables 24/7 customer support and instant responses to common inquiries.

The keyword matching system supports exact matches, partial matches, and fuzzy matching to handle variations in customer language and spelling. You can configure different response actions for different keywords, including sending automated replies, adding customer labels, or triggering external system integrations.

Advanced keyword features include support for multiple languages, context-aware matching, and machine learning-enhanced keyword recognition that improves over time based on customer interactions.

Contact Management

Import and Export Capabilities

SeaX provides robust contact management features including bulk import and export capabilities that support various file formats including CSV, Excel, and custom formats. The import system can handle large contact lists with millions of records while maintaining data integrity and validation.

The import process includes data validation, duplicate detection, and error reporting to ensure that your contact database remains clean and accurate. You can map import fields to custom contact attributes and apply transformation rules during the import process.

Export capabilities enable you to extract contact data for analysis, backup, or integration with other systems. Exports can be filtered by various criteria and scheduled to run automatically at regular intervals.

Labeling and Segmentation System

The platform includes a sophisticated labeling system that allows you to assign multiple labels to contacts for organization, segmentation, and targeting purposes. Labels can be applied manually, automatically based on customer behavior, or through API integrations with other systems.

The labeling system supports hierarchical labels, custom label attributes, and dynamic labeling based on customer interactions and preferences. This enables sophisticated customer segmentation and personalized messaging strategies.

Advanced segmentation features include the ability to create complex label combinations, time-based label expiration, and automatic label assignment based on customer lifecycle stages or engagement patterns.

Group Messaging and Targeting

With the labeling system in place, you can easily send targeted messages to specific customer segments by selecting contacts based on their labels. This targeting capability enables personalized messaging campaigns that are more relevant and effective than broad, untargeted communications.

The group messaging system supports complex targeting criteria including label combinations, geographic filters, and behavioral triggers. You can create reusable audience segments and apply them to multiple campaigns for consistent targeting.

Advanced targeting features include A/B testing capabilities, dynamic audience updates, and integration with external data sources for enhanced customer profiling and targeting accuracy.

Getting Started

Authentication Options

SeaX Bulk SMS API provides two primary authentication methods to accommodate different integration scenarios and security requirements.

Access Token Authentication

Access tokens provide short-lived authentication credentials that are ideal for interactive applications and scenarios where token refresh capabilities are available. Access tokens have a limited lifetime for security purposes and must be refreshed periodically using refresh tokens.

To obtain an access token, you must first authenticate with SeaAuth using the scope seax-bulk-sms. This scope specifically authorizes the access token to use SeaX Bulk SMS API endpoints. The authentication process returns both an access token and a refresh token that can be used to obtain new access tokens when the current one expires.

Access tokens should be included in the Authorization header of API requests using the Bearer token format: Authorization: Bearer [access-token]. This method is recommended for applications that can handle token refresh logic and need the enhanced security of short-lived credentials.

API keys provide long-lived authentication credentials that are more convenient for backend integrations and automated systems. Unlike access tokens, API keys don’t expire automatically, making them ideal for server-to-server communications and batch processing scenarios.

To create an API key, use the POST /api/v1/workspace/{workspace_id}/api_keys/reset endpoint. This will generate a new API key and invalidate any existing keys for security purposes. API keys should be stored securely and treated as sensitive credentials.

API keys are included in requests using the X-API-Key header: X-API-Key: [your-api-key]. This method is recommended for most integration scenarios due to its simplicity and reliability.

Quick Start Guide

Sending a Campaign

The campaign workflow is designed to handle bulk messaging operations efficiently while providing comprehensive tracking and management capabilities.

Step 1: Generate API Key Begin by creating an API key for authentication. This key will be used for all subsequent API calls and should be stored securely in your application configuration.

curl -X POST \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/api_keys/reset' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer [access-token]' \
  -d '{"name": "My Integration API Key"}'

Step 2: Import Contacts Upload your contact list using either the CSV import endpoint or individual contact creation endpoints. The import process is asynchronous for large contact lists.

curl -X POST \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/import_contacts' \
  -H 'X-API-Key: [your-api-key]' \
  -F 'file=@contacts.csv' \
  -F 'label_ids=["label1", "label2"]'

Step 3: Monitor Import Progress Use the job ID returned from the import request to monitor progress. The import is complete when the job status is either “finished” or “failed.”

curl -X GET \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/jobs/{job_id}' \
  -H 'X-API-Key: [your-api-key]'

Step 4: Create and Launch Campaign Once contacts are imported, create a campaign specifying the message content, target audience, and scheduling parameters.

curl -X POST \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/campaigns' \
  -H 'X-API-Key: [your-api-key]' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome Campaign",
    "type": "SMS",
    "message": "Welcome to our service!",
    "phone_number": "+1234567890",
    "contact_label_ids": ["new_customers"]
  }'

Step 5: Monitor Campaign Execution Track campaign progress using the job ID returned from campaign creation. Monitor delivery rates and customer responses through the campaign logs endpoint.

Sending Individual Messages

For immediate, individual message sending, the process is more straightforward and doesn’t require campaign setup.

Step 1: Get Sender Phone Numbers Retrieve the list of available phone numbers that can be used for sending messages.

curl -X GET \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/phones' \
  -H 'X-API-Key: [your-api-key]'

Step 2: Send Message Send an SMS or MMS message directly to a specific recipient using one of your available phone numbers.

curl -X POST \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/send_message' \
  -H 'X-API-Key: [your-api-key]' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+1234567890",
    "to_phone_number": "+0987654321",
    "content": "Hello! This is a test message.",
    "media_urls": ["https://example.com/image.jpg"]
  }'

Core Workflows

Campaign Management

Campaign management in SeaX involves creating, configuring, executing, and monitoring bulk messaging operations. The campaign system is designed to handle complex messaging scenarios while providing detailed tracking and analytics.

Campaign Creation and Configuration

When creating a campaign, you specify the campaign type (SMS, MMS, AI_AGENT, or WHATSAPP_BUSINESS_PLATFORM_MESSAGE), target audience, message content, and scheduling parameters. The campaign configuration determines how messages will be sent and to whom.

Campaign configuration includes options for message personalization, delivery timing, and response handling. You can configure campaigns to run immediately or schedule them for future execution, and you can specify complex targeting criteria based on contact labels and attributes.

Advanced campaign features include A/B testing capabilities, message personalization using contact attributes, and integration with external systems for dynamic content generation.

Campaign Execution and Monitoring

Once a campaign is launched, t (Content truncated due to size limit. Use line ranges to read in chunks)

This is a placeholder page that shows you how to use this template site.

This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project.

For large documentation sets we recommend adding content under the headings in this section, though if some or all of them don’t apply to your project feel free to remove them or add your own. You can see an example of a smaller Docsy documentation site in the Docsy User Guide, which lives in the Docsy theme repo if you’d like to copy its docs section.

Other content such as marketing material, case studies, and community updates should live in the About and Community pages.

Find out how to use the Docsy theme in the Docsy User Guide. You can learn more about how to organize your documentation (and how we organized this site) in Organizing Your Content.

1 - Refeactored SeaX Multi-Channel Messaging API Wiki (Refactored)

Overview

The SeaX Multi-Channel Messaging API is a comprehensive communication platform that enables businesses to integrate and automate messaging across SMS, WhatsApp, and voice channels. Built for scalability and enterprise use, SeaX provides unified tools for multi-channel campaigns, contact management, and conversational workflows across all major messaging platforms.

Supported Channels

📱 SMS & MMS Messaging

  • Bulk SMS Campaigns: Send text messages to large contact lists
  • MMS Support: Share images, videos, and rich media content
  • Two-Way Messaging: Receive replies and engage in SMS conversations
  • Delivery Reports: Track message delivery status and engagement

💬 WhatsApp Business Platform

  • Rich Media Messages: Send images, documents, videos, and audio
  • Template Messages: Use pre-approved templates for notifications
  • Interactive Messages: Buttons, lists, and quick reply options
  • Business API Compliance: Full WhatsApp Business API integration
  • Highly Structured Messages (HSM): Certified template messaging

📞 Voice & Phone Calls

  • Auto Dialer Campaigns: Automated outbound call campaigns
  • Custom Call Scripts: Dynamic call flows and interactions
  • Interactive Voice Response (IVR): Menu-driven call handling
  • Call Recording: Record and analyze call interactions
  • Callback Management: Handle inbound calls and callbacks

Key Features

  • Unified Contact Management: Manage contacts across all channels from one platform
  • Multi-Channel Campaigns: Coordinate messaging across SMS, WhatsApp, and voice
  • Advanced Analytics: Track performance metrics across all channels
  • Webhook Integrations: Real-time notifications for all channel events
  • Template Management: Consistent messaging templates across channels
  • Conversation Threading: Unified conversation views across channels

Authentication

SeaX API uses API key authentication. To obtain your API key:

  1. Log into your SeaX account
  2. Navigate to the “Settings” tab
  3. Generate your API key in the API Access section
  4. Use the key in your request headers
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/campaigns

Base URL

All API requests should be made to:

https://seax.seasalt.ai/api/v1/

Channel-Specific Implementation

SMS & MMS Messaging

Sending a Single SMS

const response = await fetch('https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/send_message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+1234567890',
    from: '+1987654321',
    body: 'Hello! This is a test message from SeaX.',
    message_type: 'sms'
  })
});

const result = await response.json();
console.log('Message sent:', result.message_id);

Bulk SMS Campaign

import requests

url = "https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/campaigns"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

campaign_data = {
    "name": "Spring Sale Campaign",
    "message": "🌸 Spring Sale! Get 20% off all items. Use code SPRING20. Shop now!",
    "from_number": "+1987654321",
    "contacts": [
        "+1234567890",
        "+1234567891", 
        "+1234567892"
    ],
    "schedule_time": "2024-04-01T10:00:00Z",
    "campaign_type": "sms"
}

response = requests.post(url, headers=headers, json=campaign_data)
print(f"SMS Campaign created: {response.json()}")

Sending MMS with Media

const mmsResponse = await fetch('https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/send_message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+1234567890',
    from: '+1987654321',
    body: 'Check out our new product!',
    media_url: 'https://example.com/product-image.jpg',
    message_type: 'mms'
  })
});

WhatsApp Business Platform

Send WhatsApp Template Message

whatsapp_template = {
    "to": "+1234567890",
    "template_name": "order_confirmation",
    "template_language": "en_US",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "John Doe"
                },
                {
                    "type": "text", 
                    "text": "ORD-12345"
                }
            ]
        }
    ]
}

response = requests.post(
    "https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/send_message/wabp_template_message",
    headers=headers,
    json=whatsapp_template
)

Send Interactive WhatsApp Message

const interactiveMessage = {
  to: '+1234567890',
  type: 'interactive',
  interactive: {
    type: 'button',
    body: {
      text: 'Would you like to confirm your appointment?'
    },
    action: {
      buttons: [
        {
          type: 'reply',
          reply: {
            id: 'confirm_yes',
            title: 'Yes, Confirm'
          }
        },
        {
          type: 'reply',
          reply: {
            id: 'confirm_no', 
            title: 'Reschedule'
          }
        }
      ]
    }
  }
};

Voice & Phone Call Campaigns

Create Auto Dialer Campaign

voice_campaign = {
    "name": "Appointment Reminder Campaign",
    "script": "Hello {first_name}, this is a reminder about your appointment on {appointment_date}. Press 1 to confirm or 2 to reschedule.",
    "contacts": [
        {
            "phone": "+1234567890",
            "first_name": "John",
            "appointment_date": "March 15th"
        }
    ],
    "schedule_time": "2024-03-14T09:00:00Z",
    "max_call_duration": 60,
    "retry_attempts": 3
}

response = requests.post(
    "https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/auto_dialer_campaigns",
    headers=headers,
    json=voice_campaign
)
print(f"Voice campaign created: {response.json()}")

Handle Call Callbacks

// Webhook endpoint to handle call completion
app.post('/call-webhook', (req, res) => {
  const callEvent = req.body;

  console.log('Call completed:', {
    campaign_id: callEvent.campaign_id,
    contact_phone: callEvent.contact_phone,
    call_duration: callEvent.call_duration,
    call_status: callEvent.call_status,
    user_response: callEvent.user_response
  });

  // Process call results
  if (callEvent.user_response === '1') {
    // Appointment confirmed
    updateAppointmentStatus(callEvent.contact_phone, 'confirmed');
  } else if (callEvent.user_response === '2') {
    // Reschedule requested
    scheduleFollowUp(callEvent.contact_phone);
  }

  res.status(200).send('OK');
});

Multi-Channel Campaign Orchestration

Coordinated Multi-Channel Campaign

# Example: Birthday campaign across all channels
def create_birthday_campaign():
    # 1. Start with SMS
    sms_campaign = create_sms_campaign({
        "message": "🎉 Happy Birthday {first_name}! Use code BIRTHDAY20 for 20% off!"
    })

    # 2. Follow up with WhatsApp rich message
    whatsapp_followup = create_whatsapp_campaign({
        "template": "birthday_celebration",
        "media_url": "https://example.com/birthday-gif.gif"
    })

    # 3. Personal call for VIP customers
    vip_call_campaign = create_voice_campaign({
        "script": "Happy Birthday {first_name}! We have a special surprise for you...",
        "contact_filter": "vip_customers"
    })

    return {
        "sms_campaign_id": sms_campaign.id,
        "whatsapp_campaign_id": whatsapp_followup.id, 
        "voice_campaign_id": vip_call_campaign.id
    }

Contact Management Across Channels

Unified Contact Creation

# Add a contact with multi-channel preferences
curl -X POST "https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "whatsapp_opt_in": true,
    "sms_opt_in": true,
    "voice_opt_in": true,
    "preferred_channel": "whatsapp",
    "labels": ["customer", "vip"],
    "custom_fields": {
      "birthday": "1990-05-15",
      "preferences": "electronics",
      "timezone": "America/New_York"
    }
  }'

Channel-Specific Best Practices

SMS & MMS Best Practices

  • Keep messages concise (160 characters for SMS)
  • Include clear call-to-action
  • Always provide opt-out instructions
  • Use MMS for visual content and branding
  • Respect quiet hours and time zones

WhatsApp Best Practices

  • Use rich media to enhance engagement
  • Leverage interactive buttons and quick replies
  • Follow WhatsApp Business Policy guidelines
  • Use template messages for notifications
  • Personalize messages with customer data

Voice Campaign Best Practices

  • Keep scripts concise and clear
  • Provide clear interaction options
  • Respect do-not-call preferences
  • Schedule calls during appropriate hours
  • Include callback options for missed calls

Analytics and Reporting

Multi-Channel Analytics

// Get comprehensive campaign analytics
const analytics = await fetch(`https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/campaigns/{campaign_id}/analytics`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const stats = await analytics.json();
console.log('Campaign Performance:', {
  sms: {
    sent: stats.sms_sent,
    delivered: stats.sms_delivered,
    response_rate: stats.sms_response_rate
  },
  whatsapp: {
    sent: stats.whatsapp_sent,
    delivered: stats.whatsapp_delivered,
    read_rate: stats.whatsapp_read_rate
  },
  voice: {
    calls_made: stats.voice_calls_made,
    calls_answered: stats.voice_calls_answered,
    completion_rate: stats.voice_completion_rate
  }
});

Webhook Configuration

Multi-Channel Webhook Events

// Handle webhooks for all channels
app.post('/seax-webhook', (req, res) => {
  const event = req.body;

  switch(event.channel) {
    case 'sms':
      handleSmsEvent(event);
      break;
    case 'whatsapp':
      handleWhatsAppEvent(event);
      break;
    case 'voice':
      handleVoiceEvent(event);
      break;
  }

  res.status(200).send('OK');
});

function handleSmsEvent(event) {
  if (event.type === 'message.received') {
    console.log('SMS received:', event.message);
    // Handle incoming SMS
  }
}

function handleWhatsAppEvent(event) {
  if (event.type === 'message.delivered') {
    console.log('WhatsApp message delivered:', event.message_id);
    // Update delivery status
  }
}

function handleVoiceEvent(event) {
  if (event.type === 'call.completed') {
    console.log('Call completed:', event.call_details);
    // Process call results
  }
}

Error Handling

Common HTTP status codes remain the same across all channels:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 422 - Unprocessable Entity (validation errors)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Channel-Specific Error Handling

def handle_seax_error(response):
    if response.status_code == 422:
        error_data = response.json()

        if 'whatsapp' in error_data.get('channel', ''):
            print("WhatsApp error:", error_data.get('message'))
            # Handle WhatsApp-specific errors (template issues, etc.)

        elif 'voice' in error_data.get('channel', ''):
            print("Voice error:", error_data.get('message'))
            # Handle voice-specific errors (invalid phone, etc.)

        else:
            print("SMS error:", error_data.get('message'))
            # Handle SMS-specific errors

Migration Guide

Upgrading from SMS-Only Implementation

If you’re currently using SeaX for SMS-only campaigns, you can easily add multi-channel capabilities:

  1. Update API calls to specify channel types
  2. Add channel preferences to existing contacts
  3. Create channel-specific templates for consistent messaging
  4. Configure webhooks for multi-channel events
  5. Update analytics to track cross-channel performance

Example Migration

# Before: SMS-only campaign
old_campaign = {
    "message": "Sale ending soon!",
    "contacts": ["+1234567890"]
}

# After: Multi-channel campaign
new_campaign = {
    "name": "End of Sale Multi-Channel Push",
    "channels": {
        "sms": {
            "message": "⏰ Sale ending in 2 hours! Use LAST20 for 20% off",
            "contacts": sms_contacts
        },
        "whatsapp": {
            "template": "sale_ending_soon",
            "contacts": whatsapp_contacts
        },
        "voice": {
            "script": "This is a final reminder about our sale ending today...",
            "contacts": vip_contacts
        }
    }
}

Support and Resources

Getting Help

Channel-Specific Resources

For detailed implementation guides and advanced multi-channel use cases, refer to the complete API documentation or contact Seasalt.ai support.

2 - Refactoring Guide - From Bulk SMS to Multi-Channel Messaging

Overview

This document outlines the refactoring of the SeaX API from a “Bulk SMS” focused service to a comprehensive “Multi-Channel Messaging API” that accurately represents its support for SMS, WhatsApp, and voice communications.

Problem Statement

The original SeaX API specification presented itself as “SeaX Bulk SMS” despite supporting:

  • 📱 SMS & MMS messaging
  • 💬 WhatsApp Business Platform integration
  • 📞 Voice calls and auto-dialer campaigns

This created confusion for developers who weren’t aware of the full multi-channel capabilities.

Refactoring Changes

1. API Specification Updates

Title and Description

  • Before: “SeaX Bulk SMS”
  • After: “SeaX Multi-Channel Messaging API”

Enhanced Description

The new description clearly outlines:

  • All three supported channels (SMS, WhatsApp, Voice)
  • Channel-specific capabilities
  • Use cases for each channel
  • Getting started guidance

Endpoint Documentation

Updated endpoint summaries to specify channel types:

  • POST /campaigns → “Create SMS/MMS Campaign”
  • POST /auto_dialer_campaigns → “Create Voice Call Campaign”
  • POST /send_message/wabp_template_message → “Send WhatsApp Business Template Message”

Schema Descriptions

Updated data model descriptions to reflect multi-channel nature:

  • Campaign → “SMS/MMS campaign configuration and management”
  • AutoDialerCampaign → “Voice call campaign configuration and automation settings”
  • Message → “Multi-channel message object supporting SMS, MMS, and WhatsApp”

2. Documentation Website Updates

Homepage

  • Updated SeaX API card to highlight multi-channel capabilities
  • Added channel-specific icons and feature lists
  • Clearer value proposition for each channel

API Documentation Sections

  • Updated section titles and descriptions
  • Added channel information in API info panels
  • Integrated refactored specification with fallback support

Wiki Content

  • Comprehensive multi-channel wiki with separate sections for each channel
  • Channel-specific code examples and best practices
  • Migration guide for existing SMS-only implementations
  • Cross-channel campaign orchestration examples

3. Technical Implementation

Files Created/Updated

refactored_seax_api.json      # Updated OpenAPI specification
updated_seax_wiki.md          # Comprehensive multi-channel wiki
updated_index.html            # Updated website with multi-channel focus  
updated_app.js               # JavaScript with refactored API support
refactoring-guide.md         # This document

Backward Compatibility

  • All existing API endpoints remain unchanged
  • Original specification serves as fallback
  • No breaking changes to existing implementations

Implementation Guide

For API Consumers

No Action Required

  • Existing integrations continue to work unchanged
  • All current endpoints and parameters remain the same
  • Enhanced documentation provides better understanding of capabilities
  1. Review Multi-Channel Capabilities: Explore WhatsApp and voice features
  2. Update Documentation References: Use “Multi-Channel Messaging” terminology
  3. Consider Channel Expansion: Evaluate adding WhatsApp or voice to your messaging strategy

For Documentation Hosting

Quick Implementation

Replace these files in your documentation website:

  • index.html → Use updated_index.html
  • app.js → Use updated_app.js
  • Host refactored_seax_api.json on your server
  • Include updated_seax_wiki.md content

Production Deployment

# 1. Update main files
cp updated_index.html index.html
cp updated_app.js app.js

# 2. Host refactored specification
# Place refactored_seax_api.json in your web root

# 3. Update any hardcoded URLs
# Point to your hosted refactored_seax_api.json

# 4. Deploy to your hosting platform

Key Benefits

For Developers

  • Clear Understanding: Immediately understand all available messaging channels
  • Better Examples: Channel-specific code samples and use cases
  • Comprehensive Guides: Detailed documentation for each channel
  • Migration Support: Clear guidance for expanding beyond SMS

For Business Users

  • Channel Strategy: Better understanding of multi-channel messaging options
  • Use Case Clarity: Specific examples for different business scenarios
  • Compliance Guidance: Channel-specific best practices and regulations

For Seasalt.ai

  • Accurate Branding: API documentation matches actual capabilities
  • Reduced Confusion: Developers immediately understand full feature set
  • Better Adoption: Clear multi-channel value proposition
  • Professional Presentation: Modern, comprehensive API documentation

Migration Examples

Before: SMS-Only Mindset

// Developer thinks this only does SMS
const campaign = {
  message: "Sale ending soon!",
  contacts: ["+1234567890"]
};

After: Multi-Channel Strategy

// Developer understands full capabilities
const multiChannelCampaign = {
  sms: {
    message: "⏰ Sale ending in 2 hours! Use LAST20",
    contacts: sms_contacts
  },
  whatsapp: {
    template: "sale_ending_soon", 
    contacts: whatsapp_contacts
  },
  voice: {
    script: "Final reminder about our sale ending today...",
    contacts: vip_contacts
  }
};

Technical Details

API Specification Changes

  • Updated 229 references to “sms” terminology
  • Enhanced descriptions for 48 API endpoints
  • Improved documentation for 151 data schemas
  • Added channel-specific examples and use cases

Website Architecture

  • Maintained existing design system and styling
  • Added graceful fallback to original specification
  • Preserved all existing functionality
  • Enhanced with multi-channel examples

Performance Considerations

  • Static file hosting compatible
  • Minimal JavaScript changes
  • CDN-friendly implementation
  • Mobile-responsive design maintained

Quality Assurance

Testing Checklist

  • Original API specification loads correctly (fallback)
  • Refactored specification displays when available
  • All navigation and tabs function properly
  • Wiki content renders correctly with code highlighting
  • Copy-to-clipboard functionality works
  • Mobile responsiveness maintained
  • All external links and references work

Validation

  • API specification validates against OpenAPI 3.0 standards
  • HTML validates against W3C standards
  • Accessibility guidelines maintained
  • Cross-browser compatibility preserved

Future Enhancements

Potential Improvements

  1. Interactive Examples: Live API testing with real endpoints
  2. Channel Comparison Tool: Side-by-side feature comparison
  3. Cost Calculator: Multi-channel pricing estimation
  4. Template Gallery: Pre-built templates for each channel
  5. Integration Guides: Platform-specific implementation guides

Feedback Integration

  • Monitor developer feedback on the new documentation
  • Track API usage patterns across different channels
  • Gather suggestions for additional examples or use cases

Support and Resources

Implementation Support

  • Email: info@seasalt.ai
  • Documentation: This refactoring guide
  • Original Specification: Available as fallback
  • Migration Assistance: Contact support for complex migrations

Development Resources

  • GitHub Repository: Complete source code
  • API Testing: Postman collections for all channels
  • SDK Updates: Language-specific libraries with multi-channel examples
  • Video Tutorials: Channel-specific implementation guides

Conclusion

This refactoring successfully transforms the SeaX API documentation from a narrow “Bulk SMS” focus to an accurate representation of its comprehensive multi-channel messaging capabilities. The changes maintain complete backward compatibility while providing developers with a clear understanding of all available features and channels.

The updated documentation positions SeaX as a modern, comprehensive messaging platform capable of handling enterprise communication needs across multiple channels, leading to better developer adoption and more effective use of the platform’s full capabilities.

3 - Seasalt.ai Analytics API

Comprehensive API documentation for the SeaX Analytics Generate Metric Report endpoint, enabling bulk retrieval of multiple analytics metrics in a single request for efficient workspace performance monitoring and reporting.

Overview

The Generate Metric Report endpoint provides a unified interface for retrieving multiple analytics metrics in a single request, streamlining the process of generating comprehensive reports for workspace performance analysis. Unlike individual metric endpoints, this bulk endpoint allows you to request multiple analytics types simultaneously, reducing API calls and improving efficiency for dashboard and reporting applications. The endpoint supports all available analytics metrics including conversation overviews, activity trends, label usage, communication volumes, and detailed breakdowns, making it ideal for creating unified analytics dashboards and comprehensive performance reports.

Authentication via API key is required to ensure secure access to workspace data.


Prerequisites

Ensure the following are in place:

1. Generate Your API Key

All APIs require a valid API key issued from your workspace. All requests must include a valid API key in the request header (X-API-Key).

  • Go to Workspace → API Key tab.

  • Click Add New Key and check Workspace Events Notification as the scope.

  • Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

2. Prepare Your Webhook Receiver

Your server must:

  • Be publicly accessible over HTTPS

  • Accept POST requests

  • Handle application/json payloads


Endpoint

POST https://seax.seasalt.ai/analytics-api/v1/generate_metric_report

Use this endpoint to generate multiple analytics metrics in a single request, providing a comprehensive view of your workspace performance across various dimensions.

Sample Request

curl -X POST https://seax.seasalt.ai/analytics-api/v1/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview", "activity_trend"],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Request Fields

The request body uses the AnalyticsRequestType schema with the following fields:

Note: Fields marked with specific metric requirements are only used with certain metrics. See individual metric sections for detailed field dependencies.

FieldTypeRequiredUsed By MetricsDescriptionAllowed Values / Example
metricsarray of stringsAllList of analytics metrics to generate["conversation_overview", "activity_trend", "label_usage", "conversation_breakdown", "communication_volume", "total_usage", "conversation_overview_yearly", "label_overview", "agent_activity"]
message_typestringactivity_trendWhether to analyze messages or callsmessages, calls
time_unitstringactivity_trend, label_usageAggregation level for time-based dataday, month, year
timezonestringAll time-based metricsTimezone used for grouping and filteringExample: UTC, Asia/Taipei, America/Los_Angeles see a list of tz database time zones here
start_datestring (ISO 8601 datetime)Date range metrics (see individual metrics)Custom start of the date rangeExample: 2024-06-01T00:00:00 or 2024-06-01T23:59:59-07:00 (with timezone)
end_datestring (ISO 8601 datetime)Date range metrics (see individual metrics)Custom end of the date rangeExample: 2024-06-01T23:59:59 or 2024-06-01T23:59:59-07:00 (with timezone)
range_typestringconversation_overview, agent_activityPredefined time range (alternative to start/end dates)last_day, last_7_days, last_30_days, last_90_days, last_180_days
exclude_empty_responsebooleanconversation_overviewExclude conversations with no bot or agent repliestrue, false
labelsarray of stringslabel_usageFilter by specific label namesExample: ["support", "sales"]
agentsarray of stringsagent_activityFilter by specific agent user accountsExample: ["agent_user_1", "agent_user_2"]
yearstring (YYYY)conversation_overview_yearlyYear for yearly report metricsExample: 2024

Metrics Use Case

MetricCompatible WithBest Use Case
conversation_overviewAny metricDashboard overview with other metrics
communication_volumeconversation_overviewVoice vs text communication analysis
activity_trendlabel_usageTrend analysis with label patterns
label_overviewlabel_usageLabel management and usage analysis
conversation_breakdownactivity_trendDetailed activity pattern analysis
total_usageAny metricHigh-level usage summaries
conversation_overview_yearlyStandalone recommendedAnnual reporting (resource intensive)
agent_activityAny metricAgent availability and productivity tracking

Authorization

You must provide your API key in the X-API-KEY header.

To set up your API Key:

  • Go to Workspace → API Key tab.
  • Click Add New Key and check the SeaX API Endpoints scope.
  • Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

Available Metrics

The following metrics are available through this endpoint. Each metric has specific requirements and returns structured data:

Performance Tip: Requesting multiple related metrics in a single call is more efficient than separate requests. However, avoid combining resource-intensive metrics like conversation_overview_yearly with others unless necessary.

CONVERSATION_OVERVIEW

Provides comprehensive conversation statistics over a specified time range, including message counts, user interactions, and percentage changes compared to the previous period.

Use Cases:

  • Dashboard overview widgets
  • Comparing current vs previous period performance
  • Monitoring agent workload and bot effectiveness

Required Fields:

  • metrics: Must include "conversation_overview"
  • range_type: Time range specification (use last_30_days, last_7_days, etc.)

Optional Fields:

  • timezone (string): Timezone for date calculations and filtering

    • Default: "UTC"
    • Example: "America/Los_Angeles", "Asia/Tokyo", "Europe/London"
    • Recommendation: Set to your business timezone for accurate reporting
  • exclude_empty_response (boolean): Filter out conversations with no bot or agent responses

    • Default: false (includes all conversations)
    • Example: true to focus only on engaged conversations
    • Use case: Set to true when analyzing actual engagement vs total traffic

Note: This metric automatically calculates percentage changes by comparing with the equivalent previous period.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview"],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "exclude_empty_response": true
  }'

Sample Response:

{
  "conversation_overview": {
    "conversations": 150,
    "messages": 2500,
    "bot_messages": 1200,
    "agent_messages": 800,
    "live_agent_requests": 50,
    "distinct_user_count": 125,
    "conversations_change_percentage": 10.5,
    "messages_change_percentage": 5.0,
    "bot_messages_change_percentage": 8.0,
    "agent_messages_change_percentage": 12.0,
    "live_agent_requests_change_percentage": 15.0,
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-01-31T23:59:59Z",
    "previous_period_start": "2023-12-01T00:00:00Z",
    "previous_period_end": "2023-12-31T23:59:59Z"
  }
}

CONVERSATION_OVERVIEW_YEARLY

Provides yearly conversation statistics with monthly breakdown and average calculations.

Use Cases:

  • Annual performance reports
  • Year-over-year analysis
  • Monthly trend identification
  • Resource planning based on historical data

Required Fields:

  • metrics: Must include "conversation_overview_yearly"
  • year: Year in YYYY format (e.g., "2024")

Optional Fields:

  • timezone (string): Timezone for date calculations
    • Default: "UTC"
    • Example: "America/New_York", "Europe/Berlin", "Asia/Shanghai"
    • Note: Affects how the year boundaries are calculated

Warning: This is a resource-intensive metric. Avoid combining with multiple other metrics in high-frequency requests.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview_yearly"],
    "year": "2024",
    "timezone": "UTC"
  }'

Sample Response:

{
  "conversation_overview_yearly": {
    "total_conversations": 1800,
    "total_messages": 15000,
    "average_messages_per_conversation": 8.33,
    "monthly_messages": {
      "January": 1200,
      "February": 1100,
      "March": 1300,
      "April": 1250,
      "May": 1400,
      "June": 1350,
      "July": 1450,
      "August": 1300,
      "September": 1200,
      "October": 1250,
      "November": 1100,
      "December": 1100
    }
  }
}

CONVERSATION_BREAKDOWN

Provides detailed breakdown of conversation activity by channel, day of week, and hour of day, useful for identifying peak activity periods and channel preferences.

Use Cases:

  • Staffing optimization (identify peak hours/days)
  • Channel performance analysis
  • Customer behavior pattern analysis
  • Resource allocation planning

Required Fields:

  • metrics: Must include "conversation_breakdown"
  • start_date: Start of analysis period (ISO 8601 format)
  • end_date: End of analysis period (ISO 8601 format)

Optional Fields:

  • timezone (string): Timezone for hour-of-day and day-of-week analysis
    • Default: "UTC"
    • Example: "America/Chicago", "Asia/Seoul", "Australia/Sydney"
    • Important: Critical for accurate hour-of-day patterns as customer activity varies by local time
    • Use case: Set to your primary customer base timezone for meaningful staffing insights

Performance Tip: Limit date ranges to 90 days or less for optimal performance.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_breakdown"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "timezone": "UTC"
  }'

Sample Response:

{
  "conversation_breakdown": {
    "channel_summary": {
      "WebChat": {
        "user_count": 45,
        "inbound_message_count": 320,
        "outbound_message_count": 280,
        "total_message_count": 600
      },
      "SMS": {
        "user_count": 30,
        "inbound_message_count": 150,
        "outbound_message_count": 120,
        "total_message_count": 270
      }
    },
    "messages_by_day": {
      "Monday": 60,
      "Tuesday": 80,
      "Wednesday": 75,
      "Thursday": 90,
      "Friday": 100,
      "Saturday": 40,
      "Sunday": 25
    },
    "messages_by_hour": {
      "0": 5,
      "1": 2,
      "2": 0,
      "3": 1,
      "4": 3,
      "5": 8,
      "6": 12,
      "7": 20,
      "8": 30,
      "9": 40,
      "10": 50,
      "11": 60,
      "12": 45,
      "13": 35,
      "14": 28,
      "15": 22,
      "16": 18,
      "17": 15,
      "18": 10,
      "19": 8,
      "20": 5,
      "21": 4,
      "22": 2,
      "23": 1
    }
  }
}

LABEL_OVERVIEW

Returns comprehensive information about all labels in the workspace, including usage counts and label metadata.

Use Cases:

  • Label management and cleanup
  • Understanding label usage patterns
  • Contact segmentation analysis
  • Label performance tracking

Required Fields:

  • metrics: Must include "label_overview"

Optional Fields:

  • None (this metric automatically returns all workspace labels including both custom and system labels)

Note: This metric includes both custom and system labels. System labels may have null workspace_id.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_overview"]
  }'

Sample Response:

{
  "label_overview": [
    {
      "id": "label-123",
      "name": "Support",
      "color": "#FF5733",
      "description": "Customer support inquiries",
      "total_count": 150,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T12:30:00Z"
    },
    {
      "id": "label-456",
      "name": "Sales",
      "color": "#33C3FF",
      "description": "Sales-related conversations",
      "total_count": 89,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-10T09:15:00Z"
    }
  ]
}

COMMUNICATION_VOLUME

Provides counts of inbound/outbound voice calls and non-voice messages for a specified time period.

Use Cases:

  • Communication channel analysis
  • Voice vs text usage tracking
  • Capacity planning
  • Service level monitoring

Required Fields:

  • metrics: Must include "communication_volume"
  • start_date: Start of analysis period (ISO 8601 format)
  • end_date: End of analysis period (ISO 8601 format)

Optional Fields:

  • timezone (string): Timezone for date range filtering
    • Default: "UTC"
    • Example: "America/Denver", "Europe/Paris", "Asia/Mumbai"
    • Use case: Ensures accurate date boundaries for your business operations

Note: “Non-voice” includes SMS, chat messages, and other text-based communications.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["communication_volume"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Response:

{
  "communication_volume": {
    "inbound_voice_count": 25,
    "outbound_voice_count": 15,
    "inbound_non_voice_count": 450
  }
}

ACTIVITY_TREND

Tracks communication activity changes over time, with breakdowns by sender type or call direction, including percentage change calculations.

Use Cases:

  • Trend analysis over time
  • Bot vs human agent performance tracking
  • Seasonal pattern identification
  • Growth/decline analysis

Required Fields:

  • metrics: Must include "activity_trend"
  • start_date: Start of analysis period (ISO 8601 format)
  • end_date: End of analysis period (ISO 8601 format)

Optional Fields:

  • message_type (string): Type of communication to analyze

    • Default: "messages"
    • Options:
      • "messages": Shows breakdown by CUSTOMER/AGENT/BOT/SYSTEM sender types
      • "calls": Shows breakdown by inbound/outbound call direction
    • Example: "messages" for chat analysis, "calls" for voice traffic analysis
  • time_unit (string): Time period for data aggregation

    • Default: "month"
    • Options: "day", "month", "year"
    • Example: Use "day" for detailed short-term analysis, "month" for trend analysis
    • Performance tip: Use "month" or "year" for large date ranges
  • timezone (string): Timezone for date grouping

    • Default: "UTC"
    • Example: "America/Phoenix", "Europe/Rome", "Asia/Bangkok"
    • Use case: Ensures trend periods align with your business calendar

Performance Tip: Use "month" or "year" time_unit for large date ranges to reduce response size.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["activity_trend"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "message_type": "messages",
    "time_unit": "day"
  }'

Sample Response:

{
  "activity_trend": {
    "time_unit": "day",
    "data": [
      {
        "period": "2024-01-01",
        "CUSTOMER": 45,
        "AGENT": 60,
        "BOT": 20,
        "SYSTEM": 5
      },
      {
        "period": "2024-01-02",
        "CUSTOMER": 50,
        "AGENT": 70,
        "BOT": 25,
        "SYSTEM": 3
      }
    ],
    "change_percent": 12.5
  }
}

LABEL_USAGE

Returns label usage statistics over time, grouped by the specified time unit.

Use Cases:

  • Label trend analysis
  • Campaign effectiveness tracking
  • Seasonal label usage patterns
  • Specific label performance monitoring

Required Fields:

  • metrics: Must include "label_usage"
  • start_date: Start of analysis period (ISO 8601 format)
  • end_date: End of analysis period (ISO 8601 format)

Optional Fields:

  • time_unit (string): Time period for data grouping

    • Default: "month"
    • Options: "day", "month", "year"
    • Example: "day" for daily label application patterns, "month" for monthly trends
    • Use case: Choose based on your analysis timeframe and data volume
  • labels (array of strings): Specific label names to include in analysis

    • Default: Returns data for all available labels in the workspace
    • Example: ["support", "sales", "billing"] to focus on key business categories
    • Performance tip: Filter to specific labels to reduce response size and focus analysis
    • Use case: Monitor specific campaign labels or department categories
  • timezone (string): Timezone for time period boundaries

    • Default: "UTC"
    • Example: "America/Los_Angeles", "Europe/London", "Asia/Tokyo"
    • Use case: Align time periods with your business calendar for accurate trend analysis

Tip: Use the labels filter to focus on specific labels of interest and reduce response size.

Sample Request:

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-02-29T23:59:59",
    "time_unit": "month",
    "labels": ["support", "sales", "billing"]
  }'

Sample Response:

{
  "label_usage": [
    {
      "period": "2024-01",
      "labels": [
        { "name": "support", "count": 45 },
        { "name": "sales", "count": 32 },
        { "name": "billing", "count": 18 }
      ]
    },
    {
      "period": "2024-02",
      "labels": [
        { "name": "support", "count": 52 },
        { "name": "sales", "count": 28 },
        { "name": "billing", "count": 22 }
      ]
    }
  ]
}

TOTAL_USAGE

Returns summary of total voice call duration and chat message counts over a specified period.

Use Cases:

  • Billing and usage tracking
  • Resource consumption monitoring
  • Service usage summaries
  • Cost analysis

Required Fields:

  • metrics: Must include "total_usage"

Optional Fields:

  • start_date (string, ISO 8601 datetime): Beginning of the analysis period

    • Default: If omitted, uses all available historical data from the beginning of records
    • Example: "2024-01-01T00:00:00", "2024-06-15T00:00:00-07:00"
    • Use case: Specify to analyze usage for a particular period, or omit for total lifetime usage
  • end_date (string, ISO 8601 datetime): End of the analysis period

    • Default: If omitted, uses all available data up to the current time
    • Example: "2024-12-31T23:59:59", "2024-06-30T23:59:59+08:00"
    • Use case: Specify for period analysis, or omit for usage up to now
  • timezone (string): Timezone for date range interpretation

    • Default: "UTC"
    • Example: "America/New_York", "Europe/Amsterdam", "Asia/Singapore"
    • Use case: Ensures date boundaries match your business timezone

Note: If no date range is specified, returns total usage across all available data.

Sample Request:

curl -X POST https://your-seax-domain.com/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["total_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Response:

{
  "total_usage": {
    "total_voice_minutes": 450.5,
    "total_chat_responses": 2500
  }
}

AGENT_ACTIVITY

Provides detailed agent activity data including online/offline status sessions with timestamps and duration, enabling workforce management and productivity analysis.

Use Cases:

  • Agent availability tracking
  • Workforce scheduling optimization
  • Productivity analysis and reporting
  • Agent performance monitoring
  • Shift coverage analysis

Required Fields:

  • metrics: Must include "agent_activity"
  • Either range_type OR both start_date and end_date

Optional Fields:

  • agents (array of strings): List of specific agent user accounts to filter by

    • Default: If omitted, returns data for all agents in the workspace
    • Example: ["agent_user_1@email.com", "agent_user_2@email.com", "agent_user_3@email.com"]
    • Use case: Monitor specific team members or department agents
    • Performance tip: Filter to specific agents to reduce response size when analyzing individual performance
  • timezone (string): Timezone for date range interpretation

    • Default: "UTC"
    • Example: "America/Chicago", "Europe/Madrid", "Asia/Hong_Kong"
    • Use case: Align activity timestamps with your business timezone for accurate shift analysis

Note: Activity sessions include status, start time, end time, and duration in seconds.

Available Agent Status Values

The status field in the response can have the following values:

StatusDescription
AVAILABLEAgent is online and ready to handle conversations
OFFLINEAgent is not logged in or has gone offline
ON_THE_CALLAgent is currently handling a voice call
CALL_RINGINGAn incoming call is ringing for the agent
OUTBOUNDAgent is making an outbound call
WRAP_UPAgent is in post-call wrap-up time
MEALAgent is on a meal break
BREAKAgent is on a regular break
AWAY(Deprecated) Agent is temporarily away
DO_NOT_DISTURB(Deprecated) Agent has enabled do-not-disturb mode

Important: The AWAY and DO_NOT_DISTURB statuses are deprecated but may appear in historical data for backward compatibility.

Sample Request with Range Type:

curl -X POST https://seax.seasalt.ai/analytics-api/v1/generate_metric_report \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["agent_activity"],
    "range_type": "last_7_days",
    "agents": ["agent_user_1", "agent_user_2"],
    "timezone": "America/Los_Angeles"
  }'

Sample Request with Date Range:

curl -X POST https://seax.seasalt.ai/analytics-api/v1/generate_metric_report \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["agent_activity"],
    "start_date": "2024-01-15T00:00:00",
    "end_date": "2024-01-15T23:59:59",
    "timezone": "UTC"
  }'

Sample Response:

{
  "agent_activity": {
    "agents": [
      {
        "agent_id": "agent_user_1",
        "status": "AVAILABLE",
        "start_time": "2024-01-15T08:00:00Z",
        "end_time": "2024-01-15T10:30:00Z",
        "duration_seconds": 9000
      },
      {
        "agent_id": "agent_user_1",
        "status": "ON_THE_CALL",
        "start_time": "2024-01-15T10:30:00Z",
        "end_time": "2024-01-15T11:00:00Z",
        "duration_seconds": 1800
      },
      {
        "agent_id": "agent_user_1",
        "status": "WRAP_UP",
        "start_time": "2024-01-15T11:00:00Z",
        "end_time": "2024-01-15T11:05:00Z",
        "duration_seconds": 300
      },
      {
        "agent_id": "agent_user_1",
        "status": "MEAL",
        "start_time": "2024-01-15T12:00:00Z",
        "end_time": "2024-01-15T13:00:00Z",
        "duration_seconds": 3600
      },
      {
        "agent_id": "agent_user_1",
        "status": "AVAILABLE",
        "start_time": "2024-01-15T13:00:00Z",
        "end_time": "2024-01-15T17:00:00Z",
        "duration_seconds": 14400
      },
      {
        "agent_id": "agent_user_2",
        "status": "AVAILABLE",
        "start_time": "2024-01-15T09:00:00Z",
        "end_time": "2024-01-15T15:00:00Z",
        "duration_seconds": 21600
      },
      {
        "agent_id": "agent_user_2",
        "status": "BREAK",
        "start_time": "2024-01-15T15:00:00Z",
        "end_time": "2024-01-15T15:15:00Z",
        "duration_seconds": 900
      },
      {
        "agent_id": "agent_user_2",
        "status": "OFFLINE",
        "start_time": "2024-01-15T17:00:00Z",
        "end_time": null,
        "duration_seconds": null
      }
    ]
  }
}

Complete Sample Request and Response

Sample Request with Multiple Metrics:

curl -X POST https://your-seax-domain.com/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      "conversation_overview",
      "communication_volume",
      "label_overview"
    ],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Successful Response:

{
  "conversation_overview": {
    "conversations": 150,
    "messages": 2500,
    "bot_messages": 1200,
    "agent_messages": 800,
    "live_agent_requests": 50,
    "distinct_user_count": 125,
    "conversations_change_percentage": 10.5,
    "messages_change_percentage": 5.0,
    "bot_messages_change_percentage": 8.0,
    "agent_messages_change_percentage": 12.0,
    "live_agent_requests_change_percentage": 15.0,
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-01-31T23:59:59Z",
    "previous_period_start": "2023-12-01T00:00:00Z",
    "previous_period_end": "2023-12-31T23:59:59Z"
  },
  "communication_volume": {
    "inbound_voice_count": 25,
    "outbound_voice_count": 15,
    "inbound_non_voice_count": 450
  },
  "label_overview": [
    {
      "id": "label-123",
      "name": "Support",
      "color": "#FF5733",
      "description": "Customer support inquiries",
      "total_count": 150,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T12:30:00Z"
    },
    {
      "id": "label-456",
      "name": "Sales",
      "color": "#33C3FF",
      "description": "Sales-related conversations",
      "total_count": 89,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-10T09:15:00Z"
    }
  ]
}

Error Responses

The API returns specific error messages to help you troubleshoot issues:

400 Bad Request - Missing Required Field:

{
  "detail": "Range type is required for conversation overview"
}

Solution: Add the range_type field when using the conversation_overview metric.

400 Bad Request - Invalid Metric:

{
  "detail": "Unsupported metric: invalid_metric_name"
}

Solution: Check the metric name against the supported list in the schema table above.

400 Bad Request - Date Range Required:

{
  "detail": "Start date and end date are required for conversation breakdown"
}

Solution: Provide both start_date and end_date fields for date-range metrics.

401 Unauthorized:

{
  "detail": "Invalid API key"
}

Solution: Verify your API key is correct and has the appropriate permissions.

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "metrics"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution: Ensure all required fields are included in your request body.

Common Error Scenarios

ErrorCauseSolution
“Range type is required”Missing range_type for overviewAdd range_type field
“Year is required”Missing year for yearly overviewAdd year field in YYYY format
“Start date and end date are required”Missing dates for time-range metricsAdd both start_date and end_date
“Invalid year format”Incorrect year formatUse 4-digit year format (e.g., “2024”)
“Unsupported metric”Typo in metric nameCheck spelling against supported metrics

Best Practices

Request Optimization
  1. Batch Related Metrics: Request related metrics together to minimize API calls and ensure data consistency.

    • ✅ Good: ["conversation_overview", "communication_volume"]
    • ❌ Avoid: Separate calls for each metric
  2. Timezone Consistency: Always specify the same timezone across related requests to ensure accurate comparisons.

    • ✅ Good: Set "timezone": "America/Los_Angeles" for all requests
    • ❌ Avoid: Mixing UTC and local timezones in related queries
  3. Date Range Optimization:

    • Use range_type for standard periods instead of custom dates when possible
    • Limit date ranges to 90 days or less for complex metrics
    • Ensure start_date is before end_date
Error Handling
  1. Comprehensive Error Handling: Implement proper error handling for each metric, as some may succeed while others fail due to missing required fields.
    // Example error handling
    try {
      const response = await fetch('/api/v1/analytics/generate_metric_report', {
        method: 'POST',
        headers: { 'X-API-KEY': apiKey, 'Content-Type': 'application/json' },
        body: JSON.stringify(requestBody),
      });
      if (!response.ok) {
        const error = await response.json();
        console.error('API Error:', error.detail);
      }
    } catch (error) {
      console.error('Network Error:', error);
    }
    
Performance Optimization
  1. Query Performance:

    • Avoid conversation_overview_yearly in high-frequency requests
    • Use appropriate time_unit values (prefer month over day for large ranges)
    • Consider implementing client-side caching for frequently requested combinations
    • Set reasonable request timeouts (30-60 seconds for complex queries)
  2. Resource Management:

    • Don’t request more metrics than needed for your use case
    • Use label filtering (labels parameter) to reduce response size
    • Monitor API quota usage for high-volume applications
Data Consistency
  1. Timezone Handling:

    • Always specify timezone for business reporting
    • Use the same timezone across related dashboard widgets
    • Consider user’s local timezone for UI display
  2. Date Range Logic:

    • Validate date ranges on the client side before API calls
    • Handle edge cases like month boundaries and leap years
    • Consider business calendar vs calendar dates for reporting

Real-World Usage Examples

Dashboard Overview (Most Common)

curl -X POST https://seax.seasalt.ai/seax-api/api/v1/analytics/generate_metric_report
ric_report
  -H "X-API-KEY: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview", "communication_volume"],
    "range_type": "last_30_days",
    "timezone": "America/New_York"
  }'

Detailed Analysis

curl -X POST https://api.example.com/v1/analytics/generate_metric_report \
  -H "X-API-KEY: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["activity_trend", "conversation_breakdown"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "time_unit": "day",
    "timezone": "UTC"
  }'

Label Performance Review

curl -X POST https://api.example.com/v1/analytics/generate_metric_report \
  -H "X-API-KEY: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_overview", "label_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "labels": ["support", "sales", "billing"]
  }'

4 - Seasalt.ai Webhook Notification API Tutorial

Learn how to use Seasalt.ai’s Webhook Notification API to receive real-time event updates for conversations, calls, and user actions. Ideal for integrations with Zapier and custom automation workflows.

Overview

A webhook-based notification system that lets your services receive real-time updates from Seasalt.ai products like SeaChat. Whether you want to track new conversations, missed calls, or contact changes, using the following endpoints ensures you stay informed the moment it happens. With support for multiple event types and delivery modes (immediate, delayed, batched), SeaX’s Webhook Notification are ideal for diverse automation and integration needs.

One powerful use case built on top of this webhook system is our Zapier integration. When an event is emitted via webhook, it can immediately trigger a Zap, allowing users to seamlessly connect Seasalt.ai products with tools like Google Sheets, Notion, Slack, and more. In this setup, webhooks act as the upstream event source, and Zapier serves as the downstream automation engine, consuming those events and turning them into custom workflows without any code. Explore the integration here: Seasalt.ai on Zapier


Prerequisites

Ensure the following are in place:

1. Generate Your API Key

All APIs require a valid API key issued from your workspace. All requests must include a valid API key in the request header (X-API-Key).

  • Go to Workspace → API Key tab.

  • Click Add New Key and check Workspace Events Notification as the scope.

  • Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

2. Prepare Your Webhook Receiver

Your server must:

  • Be publicly accessible over HTTPS

  • Accept POST requests

  • Handle application/json payloads


Subscription APIs

This section explains how to manage webhook subscriptions in your workspace.

Create a Subscription

Create a new webhook subscription in your SeaX workspace.

Endpoint

POST https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription

Use this endpoint to register a webhook that will receive event notifications from SeaX.

Authorization

You must provide your API key in the X-API-KEY header.

Request Body

FieldTypeRequiredDescription
webhook_urlstringThe publicly accessible URL to receive webhook events.
event_typesarray of stringList of event types to subscribe to. See supported event types below.
created_bystringIdentifier of the user creating the subscription.
is_enabledbooleanWhether the subscription is active (true) or paused (false).
typestringSubscription source. Options: "SEASALT" (default), "ZAPIER"

Supported Event Types

To get a list of supported event types, you can use this endpoint.

Once you’ve subscribed to the desired event_types, refer to the Event Payload Schema Reference section for detailed information on the structure of each event’s webhook payload. This helps you understand what fields to expect and how to process them correctly in your application.

  • conversation.new
  • conversation.updated
  • message.new
  • conversation.label.added
  • conversation.label.deleted
  • conversation.ended
  • call.new
  • call.updated
  • call.ended

Sample Request

curl -X POST "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://api.example.com/webhook",
    "event_types": ["conversation.new", "message.new"],
    "created_by": "user_12345",
    "is_enabled": true,
    "type": "SEASALT"
  }'

Sample Successful Response

{
  "webhook_url": "https://api.example.com/webhook",
  "event_types": [
    "conversation.new",
    "message.new"
  ],
  "created_by": "user_12345",
  "is_enabled": true,
  "type": "SEASALT"
}

Retrieve a Subscription

This endpoint retrieves the details of a specific webhook subscription by its ID.

Endpoint

GET https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}

Authorization

You must provide your API key in the X-API-KEY header.

Sample Request

curl -X GET "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}" \
  -H "X-API-KEY: <your_api_key>"

Sample Successful Response

{
  "webhook_url": "https://api.example.com/webhook",
  "event_types": [
    "conversation.new",
    "message.new"
  ],
  "created_by": "user_12345",
  "is_enabled": true,
  "type": "SEASALT"
}

Retrieve a List of Subscriptions based on criterion

Endpoint

GET https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Query Parameter

We support the following optional queries to retrieve subscriptions. If not provided, all subscriptions for the workspace will be returned.

NameTypeRequiredDefaultDescription
order_bystringcreated_at:descOrder items by field and direction. Format: field:direction
typestringFilter by subscription type. Enum: SEASALT, ZAPIER

Order By Options

The order_by query parameter allows you to sort the delivery logs by a specific field and direction.
The format is field:direction, where direction can be either asc for ascending or desc for descending.

Supported fields for Order By:

order_by ValueDescription
created_at:ascOldest subscriptions first
created_at:descNewest subscriptions first (default)
updated_at:ascLeast recently updated subscriptions first
updated_at:descMost recently updated subscriptions first
id:ascSort by subscription ID (A–Z)
id:descSort by subscription ID (Z–A)
created_by:ascCreator A–Z
created_by:descCreator Z–A
updated_by:ascLast updater A–Z
updated_by:descLast updater Z–A
is_enabled:ascInactive subscriptions first
is_enabled:descActive subscriptions first
type:ascSubscription type A–Z (SEASALT, ZAPIER)
type:descSubscription type Z–A

If not specified, the default is created_at:desc.

Sample Request

curl -X GET "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription?order_by=created_at:asc&type=SEASALT" \
  -H "X-API-KEY: <your_api_key>"

Sample Successful Response

{
  "subscriptions": [
    {
      "webhook_url": "https://api.example.com/webhook",
      "event_types": [
        "conversation.new",
        "message.new"
      ],
      "created_by": "user_12345",
      "is_enabled": true,
      "type": "SEASALT",
      "id": "sub_12345",
      "created_at": "2024-03-10T15:30:00Z",
      "updated_at": "2024-03-10T15:30:00Z",
      "updated_by": "user_12345"
    }
  ]
}

Update a Subscription

Modify an existing webhook subscription to update its webhook URL, event types, status, or type.

Endpoint

PATCH https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Request Body

FieldTypeRequiredDescription
webhook_urlstringNoThe URL to which webhook events will be delivered.
event_typesstring[]NoA list of event types you want to subscribe to.
is_enabledbooleanNoWhether the subscription is active.
typestringNoType of subscription. Enum: SEASALT, ZAPIER.
updated_bystringYesEmail or identifier of the user making the update.

Sample Request

curl -X PATCH "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://api.example.com/webhook",
    "event_types": ["conversation.new", "message.new"],
    "updated_by": "user_12345",
    "is_enabled": true
  }'

Sample Successful Response

{
  "webhook_url": "https://api.example.com/webhook",
  "event_types": [
    "conversation.new",
    "message.new"
  ],
  "created_by": "user_12345",
  "is_enabled": true,
  "type": "SEASALT",
  "id": "sub_12345",
  "created_at": "2024-03-10T15:30:00Z",
  "updated_at": "2024-03-10T15:30:00Z",
  "updated_by": "user_12345"
}

Remove a Subscription

Delete an existing webhook subscription from your workspace. This action permanently disables event delivery to the specified webhook URL.

Endpoint

DELETE https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Sample Request

curl -X DELETE "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/subscription/{subscription_id}" \
  -H "X-API-KEY: <your_api_key>"

Sample Request

HTTP Status Code: 204 No Content

Get a List of Supported Events

Retrieve a list of all event types that can be used when creating or updating webhook subscriptions. Each event type includes a brief description of when it is triggered.

Endpoint

GET https://seax.seasalt.ai/notify-api/v1/event_types

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Sample Request

curl -X GET "https://seax.seasalt.ai/notify-api/v1/event_types" \
  -H "X-API-KEY: <your_api_key>"

Sample Successful Response

[
  {
    event_type: 'conversation.new',
    description: 'Triggered when a new conversation is created',
  },
  {
    event_type: 'conversation.updated',
    description: 'Triggered when a conversation is updated',
  },
  {
    event_type: 'message.new',
    description: 'Triggered when a message is sent',
  },
  {
    event_type: 'conversation.ended',
    description: 'Triggered when a conversation is ended',
  },
  {
    event_type: 'conversation.label.added',
    description: 'Triggered when a label is added to a conversation',
  },
  {
    event_type: 'conversation.label.deleted',
    description: 'Triggered when a label is removed from a conversation',
  },
  {
    event_type: 'call.new',
    description: 'Triggered when a call starts',
  },
  {
    event_type: 'call.ended',
    description: 'Triggered when a call ends',
  },
  {
    event_type: 'call.updated',
    description: 'Triggered when a call summary is generated',
  }
];

Test Your Webhook and Know What Will Be Sent

Simulate different types of events to validate your webhook endpoint. This section walks you through:

  • How test requests are constructed
  • What payload structure to expect

Endpoint

POST https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/test

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Request Body

NameTypeRequiredDescription
event_typestringYesThe type of event to simulate (e.g. conversation.new)
webhook_urlstringYesThe URL to which the test payload will be sent

Sample Request

curl -X POST "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/test" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "conversation.new",
    "webhook_url": "https://api.example.com/test-webhook"
  }'

Sample Successful Response

The actual response body sent to your webhook_url depends on the event_type provided. Below is an example response for the conversation.new event type:

{
  "id": "6e74c661-4c66-4d1e-81b0-64b2f4dcac98",
  "affect": "add",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:44:30.000000",
  "event_type": "conversation.new",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "cust-001",
      "name": "Test User",
      "email": "Test@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "latest_inbound_message": {
      "id": "msg-in-123456",
      "direction": "INBOUND",
      "text": "Hello, I need help!",
      "type": "text",
      "created_at": "2025-06-20T23:44:00.000000"
    },
    "latest_outbound_message": {
      "id": "msg-out-123456",
      "direction": "OUTBOUND",
      "text": "Sure, how can I assist?",
      "type": "text",
      "created_at": "2025-06-20T23:44:30.000000"
    }
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user"
}

Delivery Logs

Learn how to retrieve delivery logs for your webhooks and what you can expect in logs.

Get Webhook Delivery Logs for a Workspace

Retrieves webhook delivery logs for a specific workspace. You can optionally filter results by event type, delivery status, date range, and more.

Endpoint

GET https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Query Parameter

The following optional query parameters are supported.

NameTypeDescription
event_typestringFilter logs by event type (e.g. conversation.new)
delivery_statusstringFilter by delivery status (success, failed)
start_datedatetimeReturn logs created on or after this date (ISO 8601 format). Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
end_datedatetimeReturn logs created on or before this date. Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
order_bystringSort results (default: created_at:desc). Format: field:direction
limitintegerMaximum number of results (default: 0 for unlimited)
offsetintegerNumber of results to skip (default: 0)

Order By Options

The order_by query parameter allows you to sort the delivery logs by a specific field and direction.
The format is field:direction, where direction can be either asc for ascending or desc for descending.

Supported fields for Order By:

order_by ValueDescription
created_at:ascOldest logs first
created_at:descNewest logs first (default)
event_type:ascEvent type A–Z
event_type:descEvent type Z–A
delivery_status:ascStatus A–Z (e.g. failed before success)
delivery_status:descStatus Z–A
status_code:ascLower HTTP status codes first (e.g. 200 → 500)
status_code:descHigher HTTP status codes first (e.g. 500 → 200)

If not specified, the default is created_at:desc.

Sample Request

curl -X GET "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs?event_type=conversation.new&delivery_status=success&order_by=created_at:desc&limit=10&offset=0" \
  -H "X-API-KEY: <your_api_key>"

Sample Successful Response

{
  "total": 1,
  "data": [
    {
      "id": "1234567890abcdef",
      "workspace_id": "ws_123456",
      "event_id": "evt_987654321",
      "subscription_id": "29efe26f-eb8a-4ee8-9abf-d8651a31283e",
      "event_type": "conversation.new",
      "webhook_url": "https://api.example.com/webhooks/incoming",
      "delivery_status": "success",
      "status_code": "200",
      "response_body": "{\"status\": \"received\", \"message\": \"Webhook processed successfully\"}",
      "delivered_event_obj": {
        "id": "1246965",
        "workspace_id": "1246965",
        "workspace_name": "seasalt.ai bot",
        "value": {
          "event_type": "conversation.new",
          "event_source": "seax",
          "event_triggered_by": "kelly@seasalt.ai",
          "payload": {
            "conversation": {
              "id": "conv_123",
              "title": "New Conversation"
            }
          },
          "occurred_at": "2025-06-20T23:44:30.000000",
          "sent_at": "2025-06-20T23:44:30.000000",
          "subscription_created_by": "kelly@seasalt.ai",
          "subscription_updated_by": "kelly@seasalt.ai"
        }
      },
      "created_at": "2024-03-11T04:18:13.558258"
    }
  ]
}

Get Webhook Delivery Logs for a Subscription

Retrieve webhook delivery logs tied to a specific subscription. Supports optional filtering by event type, delivery status, date range, ordering, and pagination.

Endpoint

GET https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs/{subscription_id}

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

NameTypeDescription
event_typestringFilter logs by event type (e.g. conversation.new)
delivery_statusstringFilter by delivery status (success, failed)
start_datedatetimeReturn logs created on or after this date (ISO 8601 format). Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
end_datedatetimeReturn logs created on or before this date. Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
order_bystringSort results (default: created_at:desc). Format: field:direction
limitintegerMaximum number of results (default: 0 for unlimited)
offsetintegerNumber of results to skip (default: 0)

Order By Options

The order_by query parameter allows you to sort the delivery logs by a specific field and direction.
The format is field:direction, where direction can be either asc for ascending or desc for descending.

Supported fields for ordering:

order_by ValueDescription
created_at:ascOldest logs first
created_at:descNewest logs first (default)
event_type:ascEvent type A–Z
event_type:descEvent type Z–A
delivery_status:ascStatus A–Z (e.g. failed before success)
delivery_status:descStatus Z–A
status_code:ascLower HTTP status codes first (e.g. 200 → 500)
status_code:descHigher HTTP status codes first (e.g. 500 → 200)

If not specified, the default is created_at:desc.

Sample Request

curl -X GET "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs/{subscription_id}?event_type=conversation.new&delivery_status=success&order_by=created_at:desc&limit=10&offset=0" \
  -H "X-API-KEY: <your_api_key>"

Sample Request

{
  "total": 1,
  "data": [
    {
      "id": "1234567890abcdef",
      "workspace_id": "ws_123456",
      "event_id": "evt_987654321",
      "subscription_id": "29efe26f-eb8a-4ee8-9abf-d8651a31283e",
      "event_type": "conversation.new",
      "webhook_url": "https://api.example.com/webhooks/incoming",
      "delivery_status": "success",
      "status_code": "200",
      "response_body": "{\"status\": \"received\", \"message\": \"Webhook processed successfully\"}",
      "delivered_event_obj": {
        "id": "1246965",
        "workspace_id": "1246965",
        "workspace_name": "seasalt.ai bot",
        "value": {
          "event_type": "conversation.new",
          "event_source": "seax",
          "event_triggered_by": "kelly@seasalt.ai",
          "payload": {
            "conversation": {
              "id": "conv_123",
              "title": "New Conversation"
            }
          },
          "occurred_at": "2025-06-20T23:44:30.000000",
          "sent_at": "2025-06-20T23:44:30.000000",
          "subscription_created_by": "kelly@seasalt.ai",
          "subscription_updated_by": "kelly@seasalt.ai"
        }
      },
      "created_at": "2024-03-11T04:18:13.558258"
    }
  ]
}

Export Webhook Delivery Logs to Email

Export webhook delivery logs for a workspace within a specific date range and receive a download link via email.

Endpoint

POST https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs/export

Authorization

This endpoint requires an API key passed in the X-API-KEY header.

Request Body

NameTypeRequiredDescription
emailstringThe email address to receive the download link.
start_datedatetimeStart date of the logs to export (ISO 8601 format). Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
end_datedatetimeEnd date of the logs to export (ISO 8601 format). Example: 2024-06-01T23:59:59-07:00 (America/Los_Angeles), 2024-06-01T23:59:59+08:00 (Asia/Singapore)
langstringEither en-US or zh-TW. We currently support two languages in the email template: English and Traditional Chinese. If any other value is provided, the template will default to English.

Sample Request

curl -X POST "https://seax.seasalt.ai/notify-api/v1/workspaces/{workspace_id}/logs/export" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-03-01T00:00:00Z",
    "end_date": "2024-03-31T23:59:59Z",
    "lang": "en-US",
    "email": "test@email.com"
  }'

Sample Successful Response

{
  "job_id": "export_job_abc123",
  "message": "Log export job started. You will receive an email once the file is ready."
}
Result

You will receive an email containing a secure download link to the exported log file once the export is complete.

Notes

This is an asynchronous export. Processing time varies depending on the data volume.

Event Payload Schema Reference

This section provides a detailed breakdown of the payload schema for each supported event type in the Webhook Notification API. Each event includes standard metadata (like id, timestamp, workspace) and a structured data object specific to the event. Use these schema definitions to correctly parse, process, and respond to webhook notifications in your application.

conversation.new

This event is triggered when a new conversation is initiated within the Seasalt.ai platform. It typically includes details about the conversation, customer, and the latest messages exchanged.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "conversation.new"
affectstringType of change, usually "add"
versionstringEvent schema version, e.g. "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source (e.g., AI agent ID)
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the new conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel where the conversation started
data.customer.idstringCustomer ID
data.customer.namestringCustomer name
data.customer.emailstringCustomer email address
data.customer.phonestringCustomer phone number
data.customer.addressstringAddress or source identifier
data.customer.channelstringCustomer’s channel (should match data.channel)
data.latest_inbound_message.idstringID of the latest inbound message
data.latest_inbound_message.directionstringAlways "INBOUND"
data.latest_inbound_message.textstringMessage content
data.latest_inbound_message.typestringType of message (e.g. "text")
data.latest_inbound_message.created_atstringTimestamp of message creation (ISO 8601)
data.latest_outbound_message.idstringID of the latest outbound message
data.latest_outbound_message.directionstringAlways "OUTBOUND"
data.latest_outbound_message.textstringMessage content
data.latest_outbound_message.typestringType of message (e.g. "text")
data.latest_outbound_message.created_atstringTimestamp of message creation (ISO 8601)

Sample Event Payload

{
  "id": "6e74c661-4c66-4d1e-81b0-64b2f4dcac98",
  "event_type": "conversation.new",
  "affect": "add",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:45:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User",
      "email": "Test@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "latest_inbound_message": {
      "id": "msg-in-123456",
      "direction": "INBOUND",
      "text": "Hello, I need help!",
      "type": "text",
      "created_at": "2025-06-20T23:44:00.000000"
    },
    "latest_outbound_message": {
      "id": "msg-out-123456",
      "direction": "OUTBOUND",
      "text": "Sure, how can I assist?",
      "type": "text",
      "created_at": "2025-06-20T23:44:30.000000"
    }
  }
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

conversation.updated

This event is triggered when an existing conversation is updated—such as changes to customer info, title, or other metadata.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "conversation.updated"
affectstringType of change, typically "change"
versionstringEvent schema version, e.g. "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source (e.g., AI agent ID)
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the updated conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel where the conversation takes place
data.customer.idstringCustomer ID
data.customer.namestringCustomer name
data.customer.emailstringCustomer email address
data.customer.phonestringCustomer phone number
data.customer.addressstringAddress or source identifier
data.customer.channelstringCustomer’s channel (should match data.channel)
data.updated_fieldsarray of stringList of fields that were updated
data.previousobjectPrevious values before the update
data.currentobjectCurrent values after the update
data.updated_by.idstring (optional)ID of the user or agent who made the update
data.updated_by.namestring (optional)Name of the user or agent who made the update
data.updated_by.typestring (optional)Type of entity (e.g., agent, system)
data.updated_atstringTimestamp of the update (ISO 8601)

Sample Event Payload

{
  "id": "cb1537d3-712e-44cf-8709-11b3fe55177a",
  "event_type": "conversation.updated",
  "affect": "change",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:45:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User",
      "email": "zapier@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "updated_fields": ["is_unread"],
    "previous": {
      "is_unread": "false"
    },
    "current": {
      "is_unread": "true"
    },
    "updated_by": {
      "id": "user_123",
      "name": "Admin",
      "type": "agent"
    },
    "updated_at": "2025-06-20T23:44:59.000000"
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

conversation.ended

This event is triggered when a conversation ends or is closed. It shares the same structure as conversation.updated, with the affect field set to “delete”.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "conversation.ended"
affectstringAlways "delete"
versionstringEvent schema version, e.g. "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source (e.g., AI agent ID)
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the ended conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel where the conversation took place
data.customer.idstringCustomer ID
data.customer.namestringCustomer name
data.customer.emailstringCustomer email address
data.customer.phonestringCustomer phone number
data.customer.addressstringAddress or source identifier
data.customer.channelstringCustomer’s channel (should match data.channel)
data.updated_fieldsarray of stringList of fields that were changed before the conversation ended
data.previousobjectPrevious values before the final update
data.currentobjectFinal values at the moment the conversation ended
data.updated_by.idstring (optional)ID of the user or agent who ended the conversation
data.updated_by.namestring (optional)Name of the user or agent
data.updated_by.typestring (optional)Type of entity (e.g., agent, system)
data.updated_atstringTimestamp when the conversation was ended

Sample Event Payload

{
  "id": "cb1537d3-712e-44cf-8709-11b3fe55177a",
  "event_type": "conversation.ended",
  "affect": "delete",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:45:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User",
      "email": "Test@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "updated_fields": ["CSAT_SUBMISSION"],
    "previous": "null",
    "current": {"rating": 5, "comment": "Quick and accurate response. Nice experience!"},
    "updated_by": {"type": "USER", "id": "user-abc-123", "name": "Test User"},
    "updated_at": "2025-06-20T23:44:59.000000"
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

message.new

This event is triggered whenever a new message is sent in a conversation. It includes detailed metadata about the message content, sender, and direction.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "message.new"
affectstringAlways "add"
versionstringEvent schema version, e.g. "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source (e.g., AI agent ID)
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the conversation the message belongs to
data.conversation_titlestringTitle of the conversation
data.message_idstringUnique identifier of the message
data.directionstringMessage direction (INBOUND or OUTBOUND)
data.created_atstringWhen the message was created (ISO 8601 format)
data.sender.typestringSender type (CUSTOMER, BOT, AGENT, etc.)
data.sender.idstringID of the sender
data.sender.namestring (optional)Name of the sender
data.content.typestringType of content (text, image, etc.)
data.content.textstringTextual content of the message
data.content.dataobject (optional)Additional data for rich content (e.g., image URLs, metadata)

Sample Event Payload

{
  "id": "3a3b8bc0-dc3d-43b4-a957-17c2fe1ad153",
  "event_type": "message.new",
  "affect": "add",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:46:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "message_id": "msg-789",
    "direction": "INBOUND",
    "created_at": "2025-06-20T23:45:59.000000",
    "sender": {
      "type": "CUSTOMER",
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User"
    },
    "content": {
      "type": "text",
      "text": "Hello, I need help!",
      "data": null
    }
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

conversation.label.added

This event is triggered when one or more labels are attached to a conversation. It includes details about the updated fields, customer info, who added the label, and when.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "conversation.label.added"
affectstringAlways "add"
versionstringEvent schema version, e.g., "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel type of the conversation
data.customerobjectCustomer information (id, name, contact info, etc.)
data.updated_fieldsarray of stringList of updated fields (likely includes labels)
data.previousobject (optional)Previous values of updated fields
data.currentobject (optional)Current values of updated fields
data.added_byobject (optional)The user or bot who added the label
data.added_atstringTimestamp when the label was added
data.labelsarray of objectList of label objects (e.g., label id and name)

Sample Event Payload

{
  "id": "ba01d246-3a8c-4e63-a191-28215797388b",
  "event_type": "conversation.label.added",
  "affect": "add",
  "version": "0.0.1",
  "timestamp": "2025-06-20T23:50:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User",
      "email": "Test@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "updated_fields": ["labels"],
    "previous": {},
    "current": {
      "labels": [
        {
          "id": "90c51757408941e2834f76392249b10f",
          "color": "#a7927f",
          "label": "solved",
          "created_at": "2025-05-10T00:20:38.834259",
          "updated_at": "2025-05-10T00:20:38.834259",
          "description": "",
          "workspace_id": Zapier.get_base_sample_data()[0],
        },
      ]
    },
    "added_by": {
      "id": "user-001",
      "type": "agent",
      "name": "Support Agent"
    },
    "added_at": "2025-06-20T23:50:00.000000",
    "labels": [
     {
        "id": "90c51757408941e2834f76392249b10f",
        "name": "solved",
        "type": "CONVERSATION",
        "color": "#a7927f",
        "is_system": False,
        "description": "",
      }
    ]
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

conversation.label.deleted

This event is triggered when one or more labels are removed from a conversation. It includes details about which fields changed, who removed the label, and when.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "conversation.label.deleted"
affectstringAlways "delete"
versionstringEvent schema version, e.g., "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel type of the conversation
data.customerobjectCustomer information (id, name, contact info, etc.)
data.updated_fieldsarray of stringList of updated fields (likely includes labels)
data.previousobject (optional)Previous values of updated fields
data.currentobject (optional)Current values of updated fields
data.removed_byobject (optional)The user or bot who removed the label
data.removed_atstringTimestamp when the label was removed
data.labelsarray of objectList of label objects that were removed

Sample Event Payload

{
  "id": "ab1f7a9b-3a7e-4894-9b35-ef3eaa0e2174",
  "event_type": "conversation.label.deleted",
  "affect": "delete",
  "version": "0.0.1",
  "timestamp": "2025-06-21T00:00:00.000000",
  "workspace": {
    "id": "workspace-123",
    "name": "Zapier Workspace"
  },
  "source": {
    "id": "source-456",
    "type": "WEBCHAT",
    "identifier": "Test AI Agent"
  },
  "data": {
    "conversation_id": "conv-789",
    "conversation_title": "Test Example Conversation",
    "channel": "WEBCHAT",
    "customer": {
      "id": "fb0b4af0-ad6a-48a3-ad3c-d10b237b432c",
      "name": "Test User",
      "email": "Test@example.com",
      "phone": "+123456789",
      "address": "Test AI Agent",
      "channel": "WEBCHAT"
    },
    "updated_fields": ["labels"],
    "previous": {
      "labels": [
        {
          "id": "8d99e9b041f04447858cde7506cee4d5",
          "color": "#565e9c",
          "label": "newUser",
          "created_at": "2025-04-08T02:48:25.059243",
          "updated_at": "2025-04-08T02:48:25.059243",
          "description": "this is a new user",
          "workspace_id": Zapier.get_base_sample_data()[0],
        },
        {
            "id": "90c51757408941e2834f76392249b10f",
            "color": "#a7927f",
            "label": "solved",
            "created_at": "2025-05-10T00:20:38.834259",
            "updated_at": "2025-05-10T00:20:38.834259",
            "description": "",
            "workspace_id": Zapier.get_base_sample_data()[0],
        },
      ]
    },
    "current": {
      [
        {
          "id": "8d99e9b041f04447858cde7506cee4d5",
          "color": "#565e9c",
          "label": "newUser",
          "created_at": "2025-04-08T02:48:25.059243",
          "updated_at": "2025-04-08T02:48:25.059243",
          "description": "this is a new user",
          "workspace_id": Zapier.get_base_sample_data()[0],
      }
    ]},
    "removed_by": {
      "id": "user-002",
      "type": "agent",
      "name": "Support Agent"
    },
    "removed_at": "2025-06-21T00:00:00.000000",
    "labels": [
      {
          "id": "90c51757408941e2834f76392249b10f",
          "name": "solved",
          "type": "CONVERSATION",
          "color": "#a7927f",
          "is_system": False,
          "description": "",
      }
    ],
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

call.new

This event is triggered when a new call is initiated. It includes information about the caller, callee, call direction, channel, and metadata.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "call.new"
affectstringAlways "add"
versionstringEvent schema version, e.g., "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source
source.typestringChannel type (e.g., WEBCHAT, MESSENGER, etc.)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the associated conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel where the call took place
data.directionstringINBOUND or OUTBOUND
data.call_fromobjectEntity initiating the call (type, id, name, address)
data.call_toobjectEntity receiving the call (type, id, name, address)
data.started_atstringTimestamp when the call started (ISO 8601 format)
data.metadataobject (optional)Additional metadata, such as SIP info or system details

Sample Event Payload

{
  "id": "e1b57c9f-dcd9-4bc1-bdc8-cfc9960c011e",
  "event_type": "call.new",
  "affect": "add",
  "version": "0.0.1",
  "timestamp": "2025-06-21T09:00:00.000000",
  "workspace": {
    "id": "workspace-456",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-999",
    "type": "SEAX_CALL",
    "identifier": "Test Callbot"
  },
  "data": {
    "conversation_id": "conv-call-001",
    "conversation_title": "+11234567890",
    "channel": "SEAX_CALL",
    "direction": "INBOUND",
    "started_at": "2025-06-21T09:00:00.000000",
    "call_from": {
      "id": "cust-001",
      "id": "+123456789",
      "name": "Zapier AI Agent",
      "type": "AGENT",
      "address": "+123456789",
      "conversation_id": "123",
      "conversation_title": "+123456789",
    },
    "call_to": {
      "id": "agent-001",
      "name": "+123456789",
      "type": "CUSTOMER",
      "address": "+123456789",
      "conversation_id": "123",
      "conversation_title": "+123456789",
    },
    "started_at": "2025-06-21T09:00:00.000000",
    "metadata": {
      "sip_session_id": "abc123",
      "recording_enabled": true
    }
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

call.ended

This event is triggered when a call ends. It contains the call participants, duration, reason for ending, and optional recording information.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "call.ended"
affectstringAlways "delete"
versionstringEvent schema version, e.g., "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source
source.typestringChannel type (e.g., SEAX_CALL, WHATSAPP)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the associated conversation
data.conversation_titlestringTitle of the conversation
data.channelstringChannel where the call took place
data.directionstringINBOUND or OUTBOUND
data.duration_secondsintegerDuration of the call in seconds
data.finish_reasonstringReason the call ended (e.g., completed, abandoned, failed)
data.call_fromobjectCaller info (type, id, name, address)
data.call_toobjectCallee info (type, id, name, address)
data.finished_atstringWhen the call ended (ISO 8601)
data.finished_bystringWho ended the call (timestamp)
data.recording_availablebooleanWhether a recording is available
data.recording_urlstring (optional)URL to download the call recording

Sample Event Payload

{
  "id": "2c72e50e-68ae-4a97-8f20-cdffedexample",
  "event_type": "call.ended",
  "affect": "delete",
  "version": "0.0.1",
  "timestamp": "2025-06-21T09:15:00.000000",
  "workspace": {
    "id": "workspace-456",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-999",
    "type": "SEAX_CALL",
    "identifier": "Test Callbot"
  },
  "data": {
    "conversation_id": "conv-call-001",
    "conversation_title": "+11234567890",
    "channel": "SEAX_CALL",
    "direction": "INBOUND",
    "duration_seconds": 300,
    "finish_reason": "completed",
    "call_from": {
      "id": "cust-001",
      "id": "+123456789",
      "name": "Zapier AI Agent",
      "type": "AGENT",
      "address": "+123456789",
      "conversation_id": "123",
      "conversation_title": "+123456789",
    },
    "call_to": {
      "id": "agent-001",
      "name": "+123456789",
      "type": "CUSTOMER",
      "address": "+123456789",
      "conversation_id": "123",
      "conversation_title": "+123456789",
    },
    "finished_at": "2025-06-21T09:15:00.000000",
    "finished_by": "2025-06-21T09:15:00.000000",
    "recording_available": true,
    "recording_url": "https://recordings.example.com/recording1234.mp3"
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

call.updated

This event is triggered when details of an ongoing or completed call are updated. It is typically used to reflect changes such as transcription availability, additional metadata, or corrections.

Payload Fields

FieldTypeDescription
idstringUnique identifier of the event
event_typestringAlways "call.updated"
affectstringAlways "update"
versionstringEvent schema version, e.g., "0.0.1"
timestampstringWhen the event occurred, in ISO 8601 format
workspace.idstringWorkspace ID associated with the event
workspace.namestringWorkspace name
source.idstringID of the event source
source.typestringChannel type (e.g., SEAX_CALL, WHATSAPP)
source.identifierstringIdentifier or name of the bot or integration
data.conversation_idstringID of the associated conversation
data.conversation_titlestringTitle of the conversation
data.call_idstring (optional)ID of the call being updated
data.update_reasonstring (optional)Description of why the call was updated
data.previousobject (optional)Previous values of updated fields
data.currentobject (optional)New/current values of updated fields
data.updated_atstringWhen the update occurred (ISO 8601 format)
data.resourcesobject (optional)Additional attached data, such as transcription or analysis

Sample Event Payload

{
  "id": "fcfe4bfa-8e04-4710-a10a-9f20c5e83ee3",
  "event_type": "call.updated",
  "affect": "update",
  "version": "0.0.1",
  "timestamp": "2025-06-22T10:10:00.000000",
  "workspace": {
    "id": "workspace-456",
    "name": "Test Workspace"
  },
  "source": {
    "id": "source-999",
    "type": "SEAX_CALL",
    "identifier": "Test Callbot"
  },
  "data": {
    "conversation_id": "conv-call-001",
    "conversation_title": "+11234567890",
    "call_id": "call-abc-123",
    "update_reason": "Transcription completed",
    "previous": {
      "recording_url": null
    },
    "update_reason": "recording_ready",
    "current": {
      "recording_url": "https://recordings.example.com/recording1234.mp3"
    },
    "updated_at": "2025-06-22T10:10:00.000000",
    "resources": {
      "session_id": "789456123",
      "channel_type": "SEAX_CALL",
      "conversation_id": "123456",
}
  },
  "subscription_created_by": "Test_user",
  "subscription_updated_by": "Test_user",
}

5 - API Docs

Overview and documentation entry point.

5.1 - Analytics API Swagger

Seasalt.ai Analytics API Tutorial

5.2 - Bulk SMS Campaign API Swagger

Seasalt.ai Bulk SMS Campaign API Tutorial

🚀 Getting Started with the Bulk SMS Campaign API

5.3 - Event Notification API Swagger

Seasalt.ai Event Notification API Tutorial

5.4 - Analytics API Redoc

Seasalt.ai Analytics API Tutorial Redoc

5.5 - Event Notification API Redoc

Seasalt.ai Event Notification API Tutorial Redoc

6 - Bulk SMS/MMS Campaigns

API endpoints for creating and managing bulk SMS/MMS campaigns with contact targeting and scheduling.

Bulk SMS/MMS Campaigns

Overview

The Bulk SMS/MMS Campaigns API enables you to send messages at scale to targeted contact lists. This comprehensive guide covers contact management, campaign creation, and monitoring. The API supports SMS, MMS, and WhatsApp Business Platform messages with advanced targeting, scheduling, and delivery tracking capabilities.

After reading through this tutorial, try out the endpoints here

Authorization

You must provide your API key in the X-API-KEY header.

To set up your API Key:

  • Go to Account → API Key tab.
  • Refresh the Key if needed
  • Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

Step-by-Step Guide

1. Get Phone Numbers

GET /api/v1/workspace/{workspace_id}/phones

First, retrieve available phone numbers for sending campaigns.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of results to skip before starting to return.
Default: 0
0
limitinteger (query)Max number of results to return.
Default: 10
10
is_ownedboolean (query)Filter for owned records only.
Default: false
true, false
enabledboolean (query)Filter by whether the item is enabled.
Default: true
true, false
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/phones?offset=0&limit=10&is_owned=false&enabled=true' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "name": "Marketing Line",
      "enabled": true,
      "phone": "+1234567890",
      "country": "US",
      "type": "LOCAL",
      "source": "TWILIO",
      "phone_capability": {
        "sms": true,
        "mms": true,
        "voice": true,
        "fax": false
      },
      "is_default": true,
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "created_time": "2025-07-07T18:12:58.351633",
      "updated_time": "2025-07-07T18:12:58.351649"
    }
  ],
  "total": 1
}

2. Get Contacts

GET /api/v1/workspace/{workspace_id}/contacts

Retrieve and filter contacts to target in your campaign.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of rows to skip.
Default: 0
0
limitinteger (query)Number of rows to return.
Default: 10
10
keywordstring (query)Search keyword for contact names and phones+18111222333
any_contact_label_idsstring (query)Include contacts with any of these label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,22222222-3333-5555-4444-666666666666
all_contact_label_idsstring (query)Include contacts with all of these label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,22222222-3333-5555-4444-666666666666
exclude_contact_idsstring (query)Exclude specific contact IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,22222222-3333-5555-4444-666666666666
exclude_labelsstring (query)Exclude contacts with these label IDs.
Comma-separated values
f47ac10b-58cc-4372-a567-0e02b2c3d479,550e8400-e29b-41d4-a716-446655440000
order_bystring (query)Sort order. Default: created_time:descphone:asc,created_time:desc,name:asc
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts?offset=0&limit=10&any_contact_label_ids=11111111-2222-4444-3333-555555555555&exclude_labels=47ac10b-58cc-4372-a567-0e02b2c3d479,550e8400-e29b-41d4-a716-446655440000' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "name": "John Doe",
      "phone": "+12345678900",
      "note": "VIP customer",
      "whatsapp_phone": "+12345678900",
      "contact_field_data": {
        "customer_tier": "gold",
        "last_purchase": "2024-01-15"
      },
      "id": "11111111-2222-4444-3333-555555555555",
      "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_time": "2025-07-07T18:13:04.845276",
      "updated_time": "2025-07-07T18:13:04.845287",
      "contact_labels": [
        {
          "name": "vip_customers",
          "color": "#19b9c3",
          "description": "VIP customers with high lifetime value",
          "id": "11111111-2222-4444-3333-555555555555",
          "is_system": false
        }
      ]
    }
  ],
  "total": 1
}

3. Import Contacts (Optional)

POST /api/v1/workspace/{workspace_id}/import_contacts

Import contacts from a CSV file if you need to add new contacts.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
filefile (form-data)CSV file containing contactscontacts.csv
duplicate_strategystring (query)How to handle duplicate contactsmark, skip, update
phone_countrystring (query)Default country code for phone numbersUS, GB, CA
Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/import_contacts?duplicate_strategy=mark&phone_country=US' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -F 'file=@contacts.csv'

Response:

{
  "id": "job_12345678-abcd-efgh-ijkl-123456789012",
  "status": "processing",
  "job_type": "import_contacts",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:00:00.000Z",
  "progress": 0,
  "total_items": 1000,
  "processed_items": 0,
  "failed_items": 0
}

4. Create Bulk SMS/MMS Campaign

POST /api/v1/workspace/{workspace_id}/campaigns

IMPORTANT: This endpoint will immediately send the campaign to all selected contacts. Carefully select your target audience using contact labels.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
namestringCampaign nameSpring Sale 2025
typestringCampaign typeSMS, MMS, AI_AGENT, WHATSAPP_BUSINESS_PLATFORM_MESSAGE
messagestringMessage content🌸 Spring Sale Alert! Get 25% off all items. Use code SPRING25. Valid until March 31st.
phone_idsarray[string]Phone number IDs to send from["020086f5-fb0e-4a0c-920a-bbdd04f4381c"]
any_contact_label_idsarray[string]Include contacts with any of these labels["11111111-2222-4444-3333-555555555555"]
all_contact_label_idsarray[string]Include contacts with all of these labels["22222222-3333-5555-4444-666666666666"]
exclude_contact_idsarray[string]Exclude specific contact IDs["11111111-2222-4444-3333-555555555555"]
exclude_any_contact_label_idsarray[string]Exclude contacts with any of these labels["33333333-4444-6666-5555-777777777777"]
media_urlsarray[string]Media URLs for MMS campaigns["https://example.com/image.jpg"]
start_timestring ($date-time)Campaign start time (for scheduling)2025-07-18T10:00:00+00:00
end_timestring ($date-time)Campaign end time (for scheduling)2025-07-18T18:00:00+00:00
is_schedulebooleanWhether the campaign is scheduledtrue, false
enable_link_shorteningbooleanEnable automatic link shortening in messagestrue, false
attach_contact_label_idsarray[string]Labels to attach to contacts after campaign["spring_campaign_2025"]
Example: SMS Campaign

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "name": "Spring Sale 2025",
    "type": "SMS",
    "message": "🌸 Spring Sale Alert! Get 25% off all items. Use code SPRING25. Valid until March 31st. Shop now: https://example.com/sale",
    "phone_ids": ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"],
    "any_contact_label_ids": ["11111111-2222-4444-3333-555555555555"],
    "exclude_any_contact_label_ids": ["22222222-3333-5555-4444-666666666666"],
    "enable_link_shortening": true,
    "attach_contact_label_ids": ["33333333-4444-6666-5555-777777777777"],
    "is_schedule": false
  }'

Response:

{
  "id": "campaign_12345678-abcd-efgh-ijkl-123456789012",
  "name": "Spring Sale 2025",
  "type": "SMS",
  "message": "🌸 Spring Sale Alert! Get 25% off all items. Use code SPRING25. Valid until March 31st. Shop now: https://example.com/sale",
  "status": "sending",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:00:00.000Z",
  "start_time": "2025-07-17T19:00:00.000Z",
  "phones": [
    {
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "phone": "+1234567890",
      "name": "Marketing Line"
    }
  ],
  "target_contact_count": 1250,
  "job_id": "job_12345678-abcd-efgh-ijkl-123456789012"
}
Example: MMS Campaign

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "name": "New Product Launch",
    "type": "MMS",
    "message": "Introducing our latest product! Check out the image and visit our store.",
    "media_urls": ["https://example.com/product-image.jpg"],
    "phone_ids": ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"],
    "any_contact_label_ids": ["product_enthusiasts"],
    "is_schedule": false
  }'

5. Monitor Campaign Progress

GET /api/v1/workspace/{workspace_id}/campaigns/{campaign_id}

Get detailed information about a specific campaign.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
campaign_idstring (path)Unique identifier of the campaigncampaign_12345678-abcd-efgh-ijkl-123456789012
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns/campaign_12345678-abcd-efgh-ijkl-123456789012' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "id": "campaign_12345678-abcd-efgh-ijkl-123456789012",
  "name": "Spring Sale 2025",
  "type": "SMS",
  "status": "finished",
  "message": "🌸 Spring Sale Alert! Get 25% off all items. Use code SPRING25. Valid until March 31st. Shop now: https://example.com/sale",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:15:00.000Z",
  "start_time": "2025-07-17T19:00:00.000Z",
  "end_time": "2025-07-17T19:15:00.000Z",
  "statistics": {
    "total_contacts": 1250,
    "sent": 1245,
    "failed": 5,
    "delivered": 1200,
    "bounced": 45,
    "opened": 890,
    "clicked": 234
  },
  "phones": [
    {
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "phone": "+1234567890",
      "name": "Marketing Line"
    }
  ]
}

6. Get Campaign Logs

GET /api/v1/workspace/{workspace_id}/campaigns/{campaign_id}/logs

Retrieve detailed logs for individual message deliveries.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
campaign_idstring (path)Unique identifier of the campaigncampaign_12345678-abcd-efgh-ijkl-123456789012
message_statusesstring (query)Filter by message statussent,delivered,failed
offsetinteger (query)Number of rows to skip.
Default: 0
0
limitinteger (query)Number of rows to return.
Default: 10
10
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns/campaign_12345678-abcd-efgh-ijkl-123456789012/logs?offset=0&limit=10&message_statuses=delivered,failed' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "id": "log_12345678-abcd-efgh-ijkl-123456789012",
      "contact_id": "11111111-2222-4444-3333-555555555555",
      "contact_name": "John Doe",
      "contact_phone": "+12345678900",
      "message_status": "delivered",
      "sent_time": "2025-07-17T19:01:00.000Z",
      "delivered_time": "2025-07-17T19:01:30.000Z",
      "error_message": null,
      "message_id": "msg_12345678-abcd-efgh-ijkl-123456789012"
    },
    {
      "id": "log_87654321-dcba-hgfe-lkji-210987654321",
      "contact_id": "22222222-3333-5555-4444-666666666666",
      "contact_name": "Jane Smith",
      "contact_phone": "+19876543210",
      "message_status": "failed",
      "sent_time": "2025-07-17T19:01:00.000Z",
      "delivered_time": null,
      "error_message": "Invalid phone number",
      "message_id": "msg_87654321-dcba-hgfe-lkji-210987654321"
    }
  ],
  "total": 1245,
  "offset": 0,
  "limit": 10
}

7. Send Individual Messages

POST /api/v1/workspace/{workspace_id}/send_message

For sending individual messages to specific contacts (not bulk campaigns).

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
phone_numberstringSender phone number+1234567890
to_phone_numberstringRecipient phone number+19876543210
contentstringMessage contentThank you for your recent purchase!
media_urlsarray[string]Media URLs for MMS messages["https://example.com/receipt.jpg"]
Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/send_message' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "phone_number": "+1234567890",
    "to_phone_number": "+19876543210",
    "content": "Thank you for your recent purchase! Your order #12345 has been shipped."
  }'

Response:

{
  "id": "msg_12345678-abcd-efgh-ijkl-123456789012",
  "status": "sent",
  "from_phone": "+1234567890",
  "to_phone": "+19876543210",
  "content": "Thank you for your recent purchase! Your order #12345 has been shipped.",
  "created_time": "2025-07-17T19:00:00.000Z",
  "sent_time": "2025-07-17T19:00:01.000Z"
}

Best Practices

Contact Targeting

  1. Use Labels Effectively: Organize contacts with meaningful labels like vip_customers, new_subscribers, location_nyc
  2. Exclude DNC Lists: Always exclude DNC (Do Not Contact) and unsubscribed labels
  3. Test with Small Groups: Test campaigns with a small subset before sending to large audiences
  4. Segment by Engagement: Use labels to track engagement levels and target accordingly

Message Content

  1. Keep It Concise: SMS messages have character limits; be clear and direct
  2. Include Clear CTAs: Use clear calls-to-action with shortened links
  3. Personalization: Use contact fields for personalized messaging
  4. Timing: Consider time zones and send during appropriate hours

Campaign Management

  1. Monitor Delivery: Check campaign logs regularly for delivery issues
  2. Track Performance: Monitor open rates, click rates, and conversions
  3. Handle Failures: Review failed messages and update contact information
  4. Respect Opt-outs: Process unsubscribe requests immediately

Error Handling

Common error responses and how to handle them:

Authentication Errors

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "status_code": 401
}

Validation Errors

{
  "error": "Validation Error",
  "message": "Invalid phone number format",
  "status_code": 422,
  "details": {
    "field": "to_phone_number",
    "code": "INVALID_FORMAT"
  }
}

Rate Limit Errors

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests",
  "status_code": 429,
  "retry_after": 60
}

Conclusion

The SeaX Bulk SMS/MMS API provides powerful tools for managing large-scale messaging campaigns. By following this guide, you can effectively target contacts, send campaigns, and monitor performance. Remember to always respect customer preferences and maintain compliance with messaging regulations.

7 - WhatsApp Business Platform Campaigns

API endpoints for setting up and managing campaigns via the WhatsApp Business Platform.

WhatsApp Business Platform Campaigns

Overview

The WhatsApp Business Platform Campaigns API empowers organizations to design and implement effective messaging campaigns targeting contacts on WhatsApp. By leveraging this platform, businesses can engage their audience on a widely-used messaging app, increasing open rates and enhancing customer interactions.

Key Benefits

  • Wider Reach: Connect with billions of users worldwide.
  • Personalization: Customize messages to maximize engagement.
  • Rich Media: Send images, videos, and documents.
  • Automation: Schedule and automate messaging workflows.

Use Cases

  • Product Promotions
  • Customer Feedback Campaigns
  • Announcements and Updates

Limitations

  • Requires a verified business account.
  • Limited to contacts who have opted-in.

After reading through this tutorial, try out the endpoints here

Getting Started

Authorization

To interact with the WhatsApp Business Platform Campaigns API, you need to authorize your requests using an API key, which must be included in the X-API-KEY header for every request.

Setting Up Your API Key

  1. Navigate to Account → API Key tab in your dashboard.
  2. Generate or refresh your API Key if necessary.
  3. Copy the API Key and store it securely.

Note: Keep your API key confidential to ensure the security of your service.

Example Header:

-H 'X-API-Key: your_api_key_here'

For more details on authorization, refer to the Authorization Guide.

Step-by-Step Guide

1. Retrieve Phone Numbers

Endpoint: GET /api/v1/workspace/{workspace_id}/phones

Begin by retrieving available phone numbers linked to your WhatsApp Business account. These numbers will be used as sender IDs in campaigns.

Request Parameters:

  • workspace_id: Unique identifier for your workspace.
  • Optional query params like offset, limit, is_owned, and enabled for filtered results.

Example Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/{workspace_id}/phones?offset=0&limit=10' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key_here'

Response:

{
  "data": [
    {
      "name": "Sales Line",
      "phone": "+11234567890",
      "id": "phone_id_string"
    }
  ],
  "total": 1
}
FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization.e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of results to skip. Default is 0.0
limitinteger (query)Max number of results to return. Default is 10.10
is_ownedboolean (query)Filter for owned records only. Default is false.true, false
enabledboolean (query)Filter by enabled status. Default is true.true, false

2. Retrieve Contacts

Endpoint: GET /api/v1/workspace/{workspace_id}/contacts

Next, access your contact list that you wish to target with your WhatsApp campaign.

Request Parameters:

  • workspace_id: Unique identifier for your workspace.
  • Optional query params like offset, limit, and keyword for refined searches.

Example Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/api/v1/workspace/{workspace_id}/contacts?offset=0&limit=10' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key_here'

Response:

{
  "data": [
    {
      "name": "John Doe",
      "phone": "+1234567890",
      "id": "contact_id_string"
    }
  ],
  "total": 1
}
FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization.e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of rows to skip. Default is 0.0
limitinteger (query)Number of rows to return. Default is 10.10
keywordstring (query)Search keyword for contact names.+18111222333

3. Set Up WhatsApp Campaign

Endpoint: POST /api/v1/workspace/{workspace_id}/campaigns

IMPORTANT: This endpoint will immediately send the campaign to all selected contacts. Carefully select your target audience using contact labels.

To initiate a WhatsApp Business Platform campaign, you’ll need to configure various parameters based on your targeting and messaging requirements.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
namestringCampaign nameWhatsApp Holiday Sale 2025
typestringCampaign typeWHATSAPP_BUSINESS_PLATFORM_MESSAGE
messagestringMessage content🎉 Holiday Sale! Get 30% off all items. Use code HOLIDAY30. Valid until Dec 31st!
phone_idsarray[string]Phone number IDs to send from["020086f5-fb0e-4a0c-920a-bbdd04f4381c"]
any_contact_label_idsarray[string]Include contacts with any of these labels["11111111-2222-4444-3333-555555555555"]
all_contact_label_idsarray[string]Include contacts with all of these labels["22222222-3333-5555-4444-666666666666"]
exclude_contact_idsarray[string]Exclude specific contact IDs["11111111-2222-4444-3333-555555555555"]
exclude_any_contact_label_idsarray[string]Exclude contacts with any of these labels["33333333-4444-6666-5555-777777777777"]
start_timestring ($date-time)Campaign start time (for scheduling)2025-07-18T10:00:00+00:00
end_timestring ($date-time)Campaign end time (for scheduling)2025-07-18T18:00:00+00:00
is_schedulebooleanWhether the campaign is scheduledtrue, false
enable_link_shorteningbooleanEnable automatic link shortening in messagestrue, false
attach_contact_label_idsarray[string]Labels to attach to contacts after campaign["holiday_campaign_2025"]

Example: Basic WhatsApp Campaign

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "name": "WhatsApp Holiday Sale 2025",
    "type": "WHATSAPP_BUSINESS_PLATFORM_MESSAGE",
    "message": "🎉 Holiday Sale! Get 30% off all items. Use code HOLIDAY30. Shop now: https://example.com/sale",
    "phone_ids": ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"],
    "any_contact_label_ids": ["11111111-2222-4444-3333-555555555555"],
    "exclude_any_contact_label_ids": ["22222222-3333-5555-4444-666666666666"],
    "enable_link_shortening": true,
    "attach_contact_label_ids": ["33333333-4444-6666-5555-777777777777"],
    "is_schedule": false
  }'

Response:

{
  "id": "campaign_12345678-abcd-efgh-ijkl-123456789012",
  "name": "WhatsApp Holiday Sale 2025",
  "type": "WHATSAPP_BUSINESS_PLATFORM_MESSAGE",
  "message": "🎉 Holiday Sale! Get 30% off all items. Use code HOLIDAY30. Shop now: https://example.com/sale",
  "status": "sending",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:00:00.000Z",
  "start_time": "2025-07-17T19:00:00.000Z",
  "phones": [
    {
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "phone": "+1234567890",
      "name": "WhatsApp Business Line"
    }
  ],
  "target_contact_count": 850,
  "job_id": "job_12345678-abcd-efgh-ijkl-123456789012"
}

Example: Scheduled WhatsApp Campaign

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "name": "Weekend Flash Sale",
    "type": "WHATSAPP_BUSINESS_PLATFORM_MESSAGE",
    "message": "⚡ Flash Sale Alert! 48 hours only - 40% off everything!",
    "phone_ids": ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"],
    "any_contact_label_ids": ["vip_customers"],
    "start_time": "2025-07-18T08:00:00+00:00",
    "end_time": "2025-07-18T20:00:00+00:00",
    "is_schedule": true,
    "enable_link_shortening": true
  }'

4. Monitor Campaign Progress

Endpoint: GET /api/v1/workspace/{workspace_id}/campaigns/{campaign_id}

Get detailed information about a specific campaign to track performance and delivery status.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
campaign_idstring (path)Unique identifier of the campaigncampaign_12345678-abcd-efgh-ijkl-123456789012

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns/campaign_12345678-abcd-efgh-ijkl-123456789012' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "id": "campaign_12345678-abcd-efgh-ijkl-123456789012",
  "name": "WhatsApp Holiday Sale 2025",
  "type": "WHATSAPP_BUSINESS_PLATFORM_MESSAGE",
  "status": "finished",
  "message": "🎉 Holiday Sale! Get 30% off all items. Use code HOLIDAY30. Shop now: https://example.com/sale",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:15:00.000Z",
  "start_time": "2025-07-17T19:00:00.000Z",
  "end_time": "2025-07-17T19:15:00.000Z",
  "statistics": {
    "total_contacts": 850,
    "sent": 845,
    "failed": 5,
    "delivered": 820,
    "read": 680,
    "replied": 127
  },
  "phones": [
    {
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "phone": "+1234567890",
      "name": "WhatsApp Business Line"
    }
  ]
}

5. Get Campaign Logs

Endpoint: GET /api/v1/workspace/{workspace_id}/campaigns/{campaign_id}/logs

Retrieve detailed logs for individual message deliveries to understand specific delivery outcomes.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
campaign_idstring (path)Unique identifier of the campaigncampaign_12345678-abcd-efgh-ijkl-123456789012
message_statusesstring (query)Filter by message statussent,delivered,failed
offsetinteger (query)Number of rows to skip.
Default: 0
0
limitinteger (query)Number of rows to return.
Default: 10
10

Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/campaigns/campaign_12345678-abcd-efgh-ijkl-123456789012/logs?offset=0&limit=10&message_statuses=delivered,failed' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "id": "log_12345678-abcd-efgh-ijkl-123456789012",
      "contact_id": "11111111-2222-4444-3333-555555555555",
      "contact_name": "John Doe",
      "contact_phone": "+12345678900",
      "message_status": "delivered",
      "sent_time": "2025-07-17T19:01:00.000Z",
      "delivered_time": "2025-07-17T19:01:30.000Z",
      "read_time": "2025-07-17T19:05:15.000Z",
      "error_message": null,
      "message_id": "wamid_12345678-abcd-efgh-ijkl-123456789012"
    },
    {
      "id": "log_87654321-dcba-hgfe-lkji-210987654321",
      "contact_id": "22222222-3333-5555-4444-666666666666",
      "contact_name": "Jane Smith",
      "contact_phone": "+19876543210",
      "message_status": "failed",
      "sent_time": "2025-07-17T19:01:00.000Z",
      "delivered_time": null,
      "read_time": null,
      "error_message": "User is not registered on WhatsApp Business Platform",
      "message_id": "wamid_87654321-dcba-hgfe-lkji-210987654321"
    }
  ],
  "total": 845,
  "offset": 0,
  "limit": 10
}

6. Import Contacts (Optional)

Endpoint: POST /api/v1/workspace/{workspace_id}/import_contacts

Import contacts from a CSV file if you need to add new contacts to your workspace.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
filefile (form-data)CSV file containing contactswhatsapp_contacts.csv
duplicate_strategystring (query)How to handle duplicate contactsmark, skip, update
phone_countrystring (query)Default country code for phone numbersUS, GB, CA

Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/import_contacts?duplicate_strategy=mark&phone_country=US' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -F 'file=@whatsapp_contacts.csv'

Response:

{
  "id": "job_12345678-abcd-efgh-ijkl-123456789012",
  "status": "processing",
  "job_type": "import_contacts",
  "created_time": "2025-07-17T19:00:00.000Z",
  "updated_time": "2025-07-17T19:00:00.000Z",
  "progress": 0,
  "total_items": 500,
  "processed_items": 0,
  "failed_items": 0
}

7. Common Errors & Handling

Understanding typical error responses is key to troubleshooting:

Authentication Errors

{
  "error": "Unauthorized",
  "message": "Invalid API Key",
  "status_code": 401
}

Solution: Verify and refresh your API Key.

Missing Parameters

{
  "error": "Bad Request",
  "message": "Required field is missing",
  "status_code": 400
}

Solution: Ensure all required fields are included in your requests.

WhatsApp Business Platform Errors

{
  "error": "WhatsApp Business Platform Error",
  "message": "Message template not approved",
  "status_code": 422,
  "details": {
    "field": "message",
    "code": "TEMPLATE_NOT_APPROVED"
  }
}

Solution: Use approved message templates or ensure your business account has the necessary permissions.

Rate Limit Errors

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests",
  "status_code": 429,
  "retry_after": 60
}

Solution: Wait for the specified retry period before making additional requests.

8. Send Individual WhatsApp Messages

Endpoint: POST /api/v1/workspace/{workspace_id}/send_message/wabp_template_message

For sending individual WhatsApp messages to specific contacts (not bulk campaigns).

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
phone_numberstringSender WhatsApp Business phone number+1234567890
to_phone_numberstringRecipient WhatsApp phone number+19876543210
messagestringMessage contentThank you for your interest in our products!
media_urlsarray[string]Media URLs for rich media messages["https://example.com/product-catalog.pdf"]

Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/send_whatsapp_message' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
    "phone_number": "+1234567890",
    "to_phone_number": "+19876543210",
    "message": "Thank you for your recent inquiry! Here's our product catalog.",
    "media_urls": ["https://example.com/product-catalog.pdf"]
  }'

Response:

{
  "id": "wamsg_12345678-abcd-efgh-ijkl-123456789012",
  "status": "sent",
  "from_phone": "+1234567890",
  "to_phone": "+19876543210",
  "message": "Thank you for your recent inquiry! Here's our product catalog.",
  "created_time": "2025-07-17T19:00:00.000Z",
  "sent_time": "2025-07-17T19:00:01.000Z"
}

Best Practices

Contact Targeting

  1. Use Labels Effectively: Organize contacts with meaningful labels like premium_customers, new_subscribers, product_interested
  2. Exclude DNC Lists: Always exclude DNC (Do Not Contact) and unsubscribed labels
  3. Test with Small Groups: Test campaigns with a small subset before sending to large audiences
  4. Segment by Engagement: Use labels to track engagement levels and target accordingly
  5. WhatsApp Opt-ins: Ensure contacts have explicitly opted-in to receive WhatsApp messages

Message Content

  1. Follow WhatsApp Policies: Adhere to WhatsApp Business Platform messaging policies
  2. Use Approved Templates: For certain message types, use pre-approved message templates
  3. Personalization: Leverage contact fields for personalized messaging
  4. Rich Media: Utilize images, videos, and documents to enhance engagement
  5. Clear CTAs: Include clear call-to-action with trackable links
  6. Timing: Consider time zones and send during appropriate hours for your audience

Campaign Management

  1. Monitor Delivery: Check campaign logs regularly for delivery issues
  2. Track Performance: Monitor read rates, reply rates, and conversions
  3. Handle Failures: Review failed messages and update contact information
  4. Respect Opt-outs: Process unsubscribe requests immediately
  5. Link Shortening: Enable link shortening for better tracking and analytics
  6. Compliance: Ensure compliance with local messaging regulations and WhatsApp policies

WhatsApp-Specific Best Practices

  1. Business Verification: Ensure your WhatsApp Business account is properly verified
  2. Template Management: Manage and update message templates regularly
  3. Media Quality: Use high-quality media files that comply with WhatsApp’s size limits
  4. Response Time: Be prepared to handle replies promptly as WhatsApp users expect quick responses
  5. Conversation Context: Maintain conversation context when sending follow-up messages

Conclusion

Utilizing the SeaX API for WhatsApp Business Platform Campaigns enables efficient and dynamic interaction with your audience. Proper setup, continuous monitoring, and adherence to best practices will enhance your campaign’s effectiveness and outreach.

8 - Auto-Dialer Voice Campaigns

API endpoints for configuring and initiating bulk outbound voice call campaigns with AI agents.

Auto-Dialer Voice Campaigns

Overview

The Auto-Dialer Voice Campaigns endpoint enables automated placement of bulk outbound voice calls to selected contact lists, supporting both AI-powered conversational agents and pre-recorded voice drops. Through a structured configuration interface, users can define campaign parameters such as target groups, call scripts, scheduling windows, and fallback behaviors. The endpoint facilitates scalable voice outreach by handling call queuing, delivery tracking, and engagement logging. Each campaign instance generates detailed execution metrics and outcomes, enabling real-time monitoring and performance analysis. Secure access to campaign operations requires authentication via API key. Below we will cover the endpoints needed to customize, create, and monitor your own voice call campaigns. Note: in this tutorial we are assuming you have configured a phone number, contacts, and AI agents in your workspace.

After reading through this tutorial, try out the endpoints here

Getting Started

Authorization

You must provide your API key in the X-API-KEY header.

To set up your API Key

  • Go to Account → API Key tab.
  • Refresh the Key if needed
  • Copy the key and keep it safe. This key is required in the X-API-KEY header for all requests.

Get Phone Numbers

GET /api/v1/workspace/{workspace_id}/phones

First you must find the available phone numbers. You will need to collect the id of each number you would like to run the campaign from.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key for authorization. Required in header. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of results to skip before starting to return.
Minimum: 0
Default: 0
0
limitinteger (query)Max number of results to return after skipped offset. If 0, return all.
Minimum: 0
Default: 10
10
is_ownedboolean (query)Filter for owned records only.
Default: false
true, false
enabledboolean (query)Filter by whether the item is enabled.
Default: true
true, false
voice_availableboolean (query)Filter by voice capability availabilitytrue, false
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/phones?offset=0&limit=10&is_owned=false&enabled=true&voice_available=true' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "name": "tech support",
      "enabled": true,
      "phone": "+886912123456",
      "country": "US",
      "whatsapp_device_id": "1234567890:98@s.whatsapp.net",
      "whatsapp_status": "CONNECTING",
      "generic_reply_message": "Welcome! If you want to subscribe daily report, please reply 'DAILY'.",
      "dnc_reply_message": "Ok, we won't send you any other message.",
      "enabled_generic_reply": false,
      "enabled_dnc_reply": false,
      "type": "LOCAL",
      "source": "TWILIO",
      "phone_capability": {
        "voice": true,
        "fax": false,
        "whatsapp": false,
        "whatsapp_business_platform": false
      },
      "is_default": false,
      "enabled_recipient": false,
      "whatsapp_business_account_phone_id": "555555555555",
      "dialpad_available": false,
      "created_time": "2025-07-07T18:12:58.351633",
      "updated_time": "2025-07-07T18:12:58.351649",
      "id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "call_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "sms_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "wabp_recipient": {
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "type": "PHONE_NUMBER",
        "receiver": "+1234567890"
      },
      "verified_caller": {
        "created_time": "2025-07-07T18:12:58.351633",
        "updated_time": "2025-07-07T18:12:58.351649",
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "phone_number": "+1234567890",
        "name": "+1234567890",
        "validation_code": "813955",
        "status": "failed",
        "call_id": "CAca1ce90f90c7609477eee1f6bbc75a50"
      },
      "byoc_trunk": {
        "created_time": "2025-07-07T18:12:58.351633",
        "updated_time": "2025-07-07T18:12:58.351649",
        "id": "0354fb10-9e18-4923-a213-6253800f8d01",
        "sip_domain": "string",
        "acl_ip_addresses": [
          {
            "ip_address": "string",
            "port": 0,
            "id": "0354fb10-9e18-4923-a213-6253800f8d01"
          }
        ],
        "sip_auth_username": "string",
        "sip_auth_password": "string"
      },
      "users": [
        {
          "account": "satoshi",
          "first_name": "Satoshi",
          "last_name": "Nakamoto",
          "email": "satoshi@btc.com",
          "phone": "+1230000000",
          "language": "en-US",
          "theme": "dark",
          "date_format": "MM/dd/yyyy",
          "time_format": "HH:mm:ss",
          "created_time": "2009-01-03T18:15:00",
          "email_notification_enabled": false,
          "is_new_user": false,
          "email_notification_only_offline": false,
          "sms_notification_enabled": false,
          "sms_notification_only_offline": false
        }
      ],
      "keywords": [
        {
          "name": "want",
          "reply": "OK, we got it.",
          "enabled_auto_reply": true,
          "enabled_contact_label": true,
          "keep_dnc_label_only": false,
          "id": "11111111-2222-4444-3333-555555555555",
          "phone_id": "11111111-2222-4444-3333-555555555555",
          "priority": 10,
          "contact_labels": [
            {
              "name": "test",
              "color": "#19b9c3",
              "description": "This label is for vip customer",
              "id": "11111111-2222-4444-3333-555555555555",
              "is_system": true,
              "created_time": "2025-07-07T18:13:02.656081",
              "updated_time": "2025-07-07T18:13:02.656093"
            }
          ],
          "created_time": "2025-07-07T18:13:02.665302",
          "updated_time": "2025-07-07T18:13:02.665315"
        }
      ],
      "unread_count": 0
    }
  ],
  "total": 0
}

Get Contacts

GET /api/v1/workspace/{workspace_id}/contacts

Use this endpoint to retrieve the set of contacts you’d like to call during the campaign.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)Authorization with API key. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
offsetinteger (query)Number of rows to skip.
Minimum: 0
Default: 0
0
limitinteger (query)Number of rows to return after skipped offset. If 0, return all.
Minimum: 0
Default: 10
10
keywordstring (query)Optional search keyword for contact names and phones.
Default: empty
+18111222333
whatsapp_phonestring (query)Optional search for contacts by WhatsApp phone.
Default: empty
+18111222333
all_contact_label_idsstring (query)Search contacts that must match all specified label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
any_contact_label_idsstring (query)Search contacts that match any of the specified label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
exclude_contact_idsstring (query)Exclude contacts by contact IDs from the result.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
exclude_any_contact_label_idsstring (query)Exclude contacts that match any of the specified label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
exclude_all_contact_label_idsstring (query)Exclude contacts that match all of the specified label IDs.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
addition_contact_idsstring (query)Include contacts explicitly by contact IDs, in addition to label-based search.
Comma-separated UUIDs
11111111-2222-4444-3333-555555555555,11111111-2222-4444-3333-666666666666
order_bystring (query)Optional sorting. Comma-separated list of field:direction pairs.
Default: created_time:desc
phone:asc,created_time:desc,name:asc
exclude_labelsstring (query)Exclude contacts with one or more of these label names (not IDs).
Comma-separated values
DNC,invalid number,unreachable
whatsapp_phone_onlyboolean (query)If true, filters to only return contacts with a WhatsApp phone number.
Default: false
true, false
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/contacts?offset=0&limit=10&keyword=%2B18111222333&whatsapp_phone=%2B18111222333&all_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&any_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_contact_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_any_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&exclude_all_contact_label_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&addition_contact_ids=11111111-2222-4444-3333-555555555555%2C11111111-2222-4444-3333-666666666666&order_by=phone%3Aasc%2Ccreated_time%3Adesc%2Cname%3Aasc&exclude_labels=DNC%2Cinvalid%20number%2Cunreachable&whatsapp_phone_only=false' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "name": "Test1",
      "phone": "+12345678900",
      "note": "New contact",
      "whatsapp_phone": "+12345678900",
      "contact_field_data": {
        "field1": 1
      },
      "id": "11111111-2222-4444-3333-555555555555",
      "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_time": "2025-07-07T18:13:04.845276",
      "updated_time": "2025-07-07T18:13:04.845287",
      "contact_labels": [
        {
          "name": "test",
          "color": "#19b9c3",
          "description": "This label is for vip customer",
          "id": "11111111-2222-4444-3333-555555555555",
          "is_system": true,
          "created_time": "2025-07-07T18:13:02.656081",
          "updated_time": "2025-07-07T18:13:02.656093"
        }
      ]
    }
  ],
  "total": 0
}

Get Configured AI agents

GET /api/v1/workspace/{workspace_id}/ai_agents

Use this endpoint to get a list of available AI agents to use during the call. You’ll need the conversation_config_id in order to select a particular agent for the campaign creation.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)Authorization with API key. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
typesstring (query)Optional filter for AI agent integration types (comma-separated).SEAX_CALL, SEAX_SMS, SEAX_WABP
limitinteger (query)Optional. Number of rows to return after offset. 0 returns all.Default: 10
Example: 10
offsetinteger (query)Optional. Number of rows to skip before returning results.Default: 0
Example: 0
order_bystring (query)Optional. Order items by ascending/descending fields (: separated, comma-delimited list).Default: created_time:desc
Example: created_time:desc
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/ai_agents?limit=10&offset=0&order_by=created_time%3Adesc' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "name": "",
      "conversation_config_id": "0354fb10-9e18-4923-a213-6253800f8d01",
      "integrations": [
        {
          "inbound_pick_up_message": "Hello, how can I help you?",
          "outbound_starting_message": "Hello, how can I help you?",
          "outbound_voice": "en-US-SteffanNeural",
          "outbound_language": "string",
          "inbound_voice": "en-US-SteffanNeural",
          "inbound_language": "string",
          "type": "SEAX_CALL"
        }
      ]
    }
  ],
  "total": 1
}

Campaign Management

Create Campaign

Initiate Auto-Dialer Voice Campaign

  1. POST /api/v1/workspace/{workspace_id}/auto_dialer_campaigns

Use this endpoint to trigger an outbound auto dialer voice campaign.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)Authorization with API key. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
namestringCampaign nameTest
phone_idsarray[string]Phone ID(s) to use for the campaign["020086f5-fb0e-4a0c-920a-bbdd04f4381c"]
attach_contact_label_idsarray[string]Labels to attach to contacts after campaign[]
start_timestring ($date-time)Campaign start timestamp2025-07-08T03:06:09+00:00
end_timestring ($date-time)Campaign end timestamp2025-07-08T03:15:00+00:00
is_schedulebooleanWhether the campaign is scheduledfalse
is_timezone_awarebooleanWhether the schedule is timezone awarefalse
modestringCampaign execution modeWEB
stagestringProcessing stage of the campaignINSTANCE
messagestringMessage to be delivered (used by TTS or AI agent)Hi, do you have a few minutes to take our survey?
tts_languagestringTTS language code"" (Recommended to leave as empty string to use the default configured in your workspace)
tts_voicestringTTS voice typedefault
audio_urlstringOptional audio URL (if not using TTS)"" (Recommended to leave as empty string to use default configured on seachat)
typestringCampaign typeAI_AGENT
capture_keypressbooleanEnable DTMF (keypress) capturetrue
capture_sttbooleanEnable speech-to-text (STT) capturefalse
ai_agent_conversation_config_idstringConversation config ID used by the AI agent221316ae-8a9f-4f39-b7f8-f2e756b80a63
overwrite_phone_recipient.typestringThe type of the recipient to overwrite with.AI_AGENT
overwrite_phone_recipient.receiverstringThe identifier for the new recipient.221316ae-8a9f-4f39-b7f8-f2e756b80a63
exclude_contact_idsarray[string]Contact IDs to exclude["4667298e-8d5b-468e-8218-6a47925fe5f2","aa145964-6d17-488d-a9be-09a43191f329"]
any_contact_label_idsarray[string]Include contacts with any of these labels["dd20f7cd-03fb-4c79-9f3e-998372d1bec6"]
Example

Request:

curl -X 'POST' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/ffffffff-abcd-4000-0000-000000000000/auto_dialer_campaigns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28' \
  -d '{
  "name": "Test",
  "phone_ids": [
    "020086f5-fb0e-4a0c-920a-bbdd04f4381c"
  ],
  "attach_contact_label_ids": [],
  "start_time": "2025-07-08T03:06:09+00:00",
  "is_schedule": false,
  "is_timezone_aware": false,
  "mode": "WEB",
  "stage": "INSTANCE",
  "message": "您好,請問您現在方便講話嗎?",
  "tts_language": "",
  "audio_url": "",
  "type": "AI_AGENT",
  "capture_keypress": true,
  "end_time": "2025-07-08T03:15:00+00:00",
  "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
  "overwrite_phone_recipient": {
    "type": "AI_AGENT",
    "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
  },
  "exclude_contact_ids": [
      "4667298e-8d5b-468e-8218-6a47925fe5f2",
      "aa145964-6d17-488d-a9be-09a43191f329"
  ],
  "any_contact_label_ids": [
    "dd20f7cd-03fb-4c79-9f3e-998372d1bec6"
  ],
  "tts_voice": "default",
  "capture_stt": false
}'

overwrite_phone_recipient

This parameter is only required if any of the phone_ids have a default recipient that does not match the campaign recipient. It allows you to explicitly override the default recipient setting for those phone numbers. You must include the type (in this example AI_AGENT) and the receiver (in this example the conversation config of the ai agent)

Format:
"overwrite_phone_recipient": {
  "type": "AI_AGENT",
  "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
}

any_contact_label_ids and exclude_contact_ids

By default, the campaign will call every contact that matches the label ids under any_contact_label_ids. To exclude contacts you must include the contact ids in the exclude_contact_ids list.

Format:
  "exclude_contact_ids": [
      "4667298e-8d5b-468e-8218-6a47925fe5f2",
      "aa145964-6d17-488d-a9be-09a43191f329"
  ],

List Campaigns

GET /api/v1/workspace/{workspace_id}/auto_dialer_campaigns

Use this endpoint to gather information about past and current campaigns. Filter on various attributes such as campaign type, status, mode, and date range.

Allowed query parameters.

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)API key used for authenticating requestse91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
typesstring (query)Filter by one or more auto dialer campaign types (comma-separated)VOICE_DROP, PROGRESSIVE_DIALER, AI_AGENT
phone_numbersstring (query)Filter by one or more phone numbers (comma-separated)+15555550100,+15555550101
ai_agent_conversation_config_idstring (query)Filter by AI agent conversation config ID221316ae-8a9f-4f39-b7f8-f2e756b80a63
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/3fa85f64-5717-4562-b3fc-2c963f66afa6/auto_dialer_campaigns?stage=INSTANCE&limit=10&offset=0&order_by=created_time%3Adesc' \
  -H 'accept: application/json' \
  -H 'X-API-Key: e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28'

Response:

{
  "data": [
    {
      "start_time": "2025-07-08T03:19:39",
      "end_time": "2025-07-08T03:30:00",
      "name": "test",
      "draft_name": null,
      "type": "AI_AGENT",
      "message": "Hello this is a test",
      "tts_language": "en-US",
      "tts_voice": "en-US-default",
      "ai_agent_id": "51fefba9-c3ee-40e8-a392-8bc14c639719",
      "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
      "max_attempts": 1,
      "max_dialers": 20,
      "capture_keypress": true,
      "capture_stt": false,
      "is_timezone_aware": false,
      "is_schedule": false,
      "contact_file_url": null,
      "timezone": null,
      "campaign_metadata": {
        "all_contact_labels": [],
        "any_contact_labels": [
          {
            "id": "7082ae15-43ae-472f-a83c-ee6462a0af83",
            "name": "test group",
            "color": "#0cb3c3"
          }
        ],
        "exclude_contacts": [
          {
            "id": "6e612221-594d-4c22-a305-ffe193b3c51f",
            "name": "Test User 1",
            "phone": "+11234567890"
          },
          {
            "id": "c0c9965b-1809-45e2-bcb6-1e1484a79abb",
            "name": "Test User 2",
            "phone": "+11234567890"
          },
          {
            "id": "a43b4e5d-edc7-4264-be19-2d39ab99d52e",
            "name": "Test User 3",
            "phone": "+11234567890"
          }
        ],
        "addition_contacts": [],
        "exclude_any_contact_labels": [],
        "exclude_all_contact_labels": [],
        "whatsapp_phone_only": false
      },
      "status": "FINISHED",
      "created_time": "2025-07-08T03:19:40.160564",
      "updated_time": "2025-07-08T03:19:40.160564",
      "id": "448ea794-0368-4604-a56f-f2350229d9e5",
      "mode": "WEB",
      "stage": "INSTANCE",
      "audio": null,
      "phones": [
        {
          "name": "dev-number-1",
          "enabled": true,
          "phone": "+19987654321",
          "country": "US",
          "whatsapp_device_id": null,
          "whatsapp_status": null,
          "generic_reply_message": "Welcome!",
          "dnc_reply_message": "Ok, we won't send you any other message.",
          "enabled_generic_reply": false,
          "enabled_dnc_reply": false,
          "type": "LOCAL",
          "source": "TWILIO",
          "phone_capability": {
            "sms": true,
            "mms": true,
            "voice": true,
            "fax": false,
            "whatsapp": false,
            "whatsapp_business_platform": false
          },
          "is_default": false,
          "enabled_recipient": true,
          "whatsapp_business_account_phone_id": null,
          "dialpad_available": false,
          "created_time": "2024-05-14T12:25:05.892618",
          "updated_time": "2025-07-08T03:19:40.160564",
          "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
          "call_recipient": {
            "id": "dde4ffb2-4c8c-412a-a8cf-33b77843cdb0",
            "type": "AI_AGENT",
            "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
          },
          "sms_recipient": null,
          "wabp_recipient": null,
          "verified_caller": null,
          "byoc_trunk": null
        }
      ],
      "statistics": {
        "human": 0,
        "machine": 0,
        "unknown": 0,
        "no_answer": 0,
        "total": 1
      },
      "contact_fields": [],
      "relative_time_config": null
    }
  ]
}

Get Campaign Details

GET /api/v1/workspace/{workspace_id}/auto_dialer_campaigns/{auto_dialer_campaign_id}

Get the information of a campaign given the workspace_id and the desired campaign_id

FieldTypeDescriptionAllowed Values / ExampleRequired
X-API-Keystring (header)Authorization with API key. See Authorization Guidee91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28
workspace_idstring (path)Unique identifier of the workspace3fa85f64-5717-4562-b3fc-2c963f66afa6
auto_dialer_campaign_idstring (path)Unique identifier of the auto dialer campaign01e14e9e-ddd8-4e63-bad2-e026d5aa5698
Example

Request:

curl -X 'GET' \
  'https://seax.seasalt.ai/bulk-sms-api/api/v1/workspace/ffffffff-abcd-4000-0000-000000000000/auto_dialer_campaigns/448ea794-0368-4604-a56f-f2350229d9e5' \
  -H 'accept: application/json' \
  -H 'X-API-Key: 09a318b51673ce2e3b1c03387a7bfc8c2e9aa35f83e6295b4109402a0c65111c'

Response:

{
  "start_time": "2025-07-08T03:19:39",
  "end_time": "2025-07-08T03:30:00",
  "name": "test",
  "draft_name": null,
  "type": "AI_AGENT",
  "message": "Hello this is a test",
  "tts_language": "en-US",
  "tts_voice": "en-US-default",
  "ai_agent_id": "51fefba9-c3ee-40e8-a392-8bc14c639719",
  "ai_agent_conversation_config_id": "221316ae-8a9f-4f39-b7f8-f2e756b80a63",
  "max_attempts": 1,
  "max_dialers": 20,
  "capture_keypress": true,
  "capture_stt": false,
  "is_timezone_aware": false,
  "is_schedule": false,
  "contact_file_url": null,
  "timezone": null,
  "campaign_metadata": {
    "all_contact_labels": [],
    "any_contact_labels": [
      {
        "id": "7082ae15-43ae-472f-a83c-ee6462a0af83",
        "name": "test group",
        "color": "#0cb3c3"
      }
    ],
    "exclude_contacts": [
      {
        "id": "6e612221-594d-4c22-a305-ffe193b3c51f",
        "name": "Test User 1",
        "phone": "+11234567890"
      },
      {
        "id": "c0c9965b-1809-45e2-bcb6-1e1484a79abb",
        "name": "Test User 2",
        "phone": "+11234567890"
      },
      {
        "id": "a43b4e5d-edc7-4264-be19-2d39ab99d52e",
        "name": "Test User 3",
        "phone": "+11234567890"
      }
    ],
    "addition_contacts": [],
    "exclude_any_contact_labels": [],
    "exclude_all_contact_labels": [],
    "whatsapp_phone_only": false
  },
  "status": "FINISHED",
  "created_time": "2025-07-08T03:19:40.160564",
  "updated_time": "2025-07-08T03:19:40.160564",
  "id": "448ea794-0368-4604-a56f-f2350229d9e5",
  "mode": "WEB",
  "stage": "INSTANCE",
  "audio": null,
  "phones": [
    {
      "name": "dev-number-1",
      "enabled": true,
      "phone": "+19987654321",
      "country": "US",
      "whatsapp_device_id": null,
      "whatsapp_status": null,
      "generic_reply_message": "Welcome!",
      "dnc_reply_message": "Ok, we won't send you any other message.",
      "enabled_generic_reply": false,
      "enabled_dnc_reply": false,
      "type": "LOCAL",
      "source": "TWILIO",
      "phone_capability": {
        "sms": true,
        "mms": true,
        "voice": true,
        "fax": false,
        "whatsapp": false,
        "whatsapp_business_platform": false
      },
      "is_default": false,
      "enabled_recipient": true,
      "whatsapp_business_account_phone_id": null,
      "dialpad_available": false,
      "created_time": "2024-05-14T12:25:05.892618",
      "updated_time": "2025-07-08T03:19:40.160564",
      "id": "020086f5-fb0e-4a0c-920a-bbdd04f4381c",
      "call_recipient": {
        "id": "dde4ffb2-4c8c-412a-a8cf-33b77843cdb0",
        "type": "AI_AGENT",
        "receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
      },
      "sms_recipient": null,
      "wabp_recipient": null,
      "verified_caller": null,
      "byoc_trunk": null
    }
  ],
  "statistics": {
    "human": 0,
    "machine": 0,
    "unknown": 0,
    "no_answer": 0,
    "total": 1
  },
  "contact_fields": [],
  "relative_time_config": null
}