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.
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.
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 Key Authentication (Recommended)
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
- 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:
- Log into your SeaX account
- Navigate to the “Settings” tab
- Generate your API key in the API Access section
- 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()}")
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'
})
});
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
}
# 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
- Success400
- 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:
- Update API calls to specify channel types
- Add channel preferences to existing contacts
- Create channel-specific templates for consistent messaging
- Configure webhooks for multi-channel events
- 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.
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:
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.
Field | Type | Required | Used By Metrics | Description | Allowed Values / Example |
---|
metrics | array of strings | ✅ | All | List 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_type | string | | activity_trend | Whether to analyze messages or calls | messages , calls |
time_unit | string | | activity_trend , label_usage | Aggregation level for time-based data | day , month , year |
timezone | string | | All time-based metrics | Timezone used for grouping and filtering | Example: UTC , Asia/Taipei , America/Los_Angeles see a list of tz database time zones here |
start_date | string (ISO 8601 datetime) | | Date range metrics (see individual metrics) | Custom start of the date range | Example: 2024-06-01T00:00:00 or 2024-06-01T23:59:59-07:00 (with timezone) |
end_date | string (ISO 8601 datetime) | | Date range metrics (see individual metrics) | Custom end of the date range | Example: 2024-06-01T23:59:59 or 2024-06-01T23:59:59-07:00 (with timezone) |
range_type | string | | conversation_overview , agent_activity | Predefined time range (alternative to start/end dates) | last_day , last_7_days , last_30_days , last_90_days , last_180_days |
exclude_empty_response | boolean | | conversation_overview | Exclude conversations with no bot or agent replies | true , false |
labels | array of strings | | label_usage | Filter by specific label names | Example: ["support", "sales"] |
agents | array of strings | | agent_activity | Filter by specific agent user accounts | Example: ["agent_user_1", "agent_user_2"] |
year | string (YYYY) | | conversation_overview_yearly | Year for yearly report metrics | Example: 2024 |
Metrics Use Case
Metric | Compatible With | Best Use Case |
---|
conversation_overview | Any metric | Dashboard overview with other metrics |
communication_volume | conversation_overview | Voice vs text communication analysis |
activity_trend | label_usage | Trend analysis with label patterns |
label_overview | label_usage | Label management and usage analysis |
conversation_breakdown | activity_trend | Detailed activity pattern analysis |
total_usage | Any metric | High-level usage summaries |
conversation_overview_yearly | Standalone recommended | Annual reporting (resource intensive) |
agent_activity | Any metric | Agent 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:
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:
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:
Status | Description |
---|
AVAILABLE | Agent is online and ready to handle conversations |
OFFLINE | Agent is not logged in or has gone offline |
ON_THE_CALL | Agent is currently handling a voice call |
CALL_RINGING | An incoming call is ringing for the agent |
OUTBOUND | Agent is making an outbound call |
WRAP_UP | Agent is in post-call wrap-up time |
MEAL | Agent is on a meal break |
BREAK | Agent 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
Error | Cause | Solution |
---|
“Range type is required” | Missing range_type for overview | Add range_type field |
“Year is required” | Missing year for yearly overview | Add year field in YYYY format |
“Start date and end date are required” | Missing dates for time-range metrics | Add both start_date and end_date |
“Invalid year format” | Incorrect year format | Use 4-digit year format (e.g., “2024”) |
“Unsupported metric” | Typo in metric name | Check spelling against supported metrics |
Best Practices
Request Optimization
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
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
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
- 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);
}
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)
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
Timezone Handling:
- Always specify timezone for business reporting
- Use the same timezone across related dashboard widgets
- Consider user’s local timezone for UI display
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:
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
Field | Type | Required | Description |
---|
webhook_url | string | ✅ | The publicly accessible URL to receive webhook events. |
event_types | array of string | ✅ | List of event types to subscribe to. See supported event types below. |
created_by | string | | Identifier of the user creating the subscription. |
is_enabled | boolean | ✅ | Whether the subscription is active (true ) or paused (false ). |
type | string | | Subscription 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.
Name | Type | Required | Default | Description |
---|
order_by | string | | created_at:desc | Order items by field and direction. Format: field:direction |
type | string | | | Filter 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 Value | Description |
---|
created_at:asc | Oldest subscriptions first |
created_at:desc | Newest subscriptions first (default) |
updated_at:asc | Least recently updated subscriptions first |
updated_at:desc | Most recently updated subscriptions first |
id:asc | Sort by subscription ID (A–Z) |
id:desc | Sort by subscription ID (Z–A) |
created_by:asc | Creator A–Z |
created_by:desc | Creator Z–A |
updated_by:asc | Last updater A–Z |
updated_by:desc | Last updater Z–A |
is_enabled:asc | Inactive subscriptions first |
is_enabled:desc | Active subscriptions first |
type:asc | Subscription type A–Z (SEASALT , ZAPIER ) |
type:desc | Subscription 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
Field | Type | Required | Description |
---|
webhook_url | string | No | The URL to which webhook events will be delivered. |
event_types | string[] | No | A list of event types you want to subscribe to. |
is_enabled | boolean | No | Whether the subscription is active. |
type | string | No | Type of subscription. Enum: SEASALT , ZAPIER . |
updated_by | string | Yes | Email 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
Name | Type | Required | Description |
---|
event_type | string | Yes | The type of event to simulate (e.g. conversation.new ) |
webhook_url | string | Yes | The 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.
Name | Type | Description |
---|
event_type | string | Filter logs by event type (e.g. conversation.new ) |
delivery_status | string | Filter by delivery status (success , failed ) |
start_date | datetime | Return 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_date | datetime | Return 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_by | string | Sort results (default: created_at:desc ). Format: field:direction |
limit | integer | Maximum number of results (default: 0 for unlimited) |
offset | integer | Number 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 Value | Description |
---|
created_at:asc | Oldest logs first |
created_at:desc | Newest logs first (default) |
event_type:asc | Event type A–Z |
event_type:desc | Event type Z–A |
delivery_status:asc | Status A–Z (e.g. failed before success) |
delivery_status:desc | Status Z–A |
status_code:asc | Lower HTTP status codes first (e.g. 200 → 500) |
status_code:desc | Higher 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.
Name | Type | Description |
---|
event_type | string | Filter logs by event type (e.g. conversation.new ) |
delivery_status | string | Filter by delivery status (success , failed ) |
start_date | datetime | Return 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_date | datetime | Return 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_by | string | Sort results (default: created_at:desc ). Format: field:direction |
limit | integer | Maximum number of results (default: 0 for unlimited) |
offset | integer | Number 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 Value | Description |
---|
created_at:asc | Oldest logs first |
created_at:desc | Newest logs first (default) |
event_type:asc | Event type A–Z |
event_type:desc | Event type Z–A |
delivery_status:asc | Status A–Z (e.g. failed before success) |
delivery_status:desc | Status Z–A |
status_code:asc | Lower HTTP status codes first (e.g. 200 → 500) |
status_code:desc | Higher 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
Name | Type | Required | Description |
---|
email | string | ✅ | The email address to receive the download link. |
start_date | datetime | | Start 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_date | datetime | | End 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) |
lang | string | | Either 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "conversation.new" |
affect | string | Type of change, usually "add" |
version | string | Event schema version, e.g. "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source (e.g., AI agent ID) |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the new conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel where the conversation started |
data.customer.id | string | Customer ID |
data.customer.name | string | Customer name |
data.customer.email | string | Customer email address |
data.customer.phone | string | Customer phone number |
data.customer.address | string | Address or source identifier |
data.customer.channel | string | Customer’s channel (should match data.channel ) |
data.latest_inbound_message.id | string | ID of the latest inbound message |
data.latest_inbound_message.direction | string | Always "INBOUND" |
data.latest_inbound_message.text | string | Message content |
data.latest_inbound_message.type | string | Type of message (e.g. "text" ) |
data.latest_inbound_message.created_at | string | Timestamp of message creation (ISO 8601) |
data.latest_outbound_message.id | string | ID of the latest outbound message |
data.latest_outbound_message.direction | string | Always "OUTBOUND" |
data.latest_outbound_message.text | string | Message content |
data.latest_outbound_message.type | string | Type of message (e.g. "text" ) |
data.latest_outbound_message.created_at | string | Timestamp 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "conversation.updated" |
affect | string | Type of change, typically "change" |
version | string | Event schema version, e.g. "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source (e.g., AI agent ID) |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the updated conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel where the conversation takes place |
data.customer.id | string | Customer ID |
data.customer.name | string | Customer name |
data.customer.email | string | Customer email address |
data.customer.phone | string | Customer phone number |
data.customer.address | string | Address or source identifier |
data.customer.channel | string | Customer’s channel (should match data.channel ) |
data.updated_fields | array of string | List of fields that were updated |
data.previous | object | Previous values before the update |
data.current | object | Current values after the update |
data.updated_by.id | string (optional) | ID of the user or agent who made the update |
data.updated_by.name | string (optional) | Name of the user or agent who made the update |
data.updated_by.type | string (optional) | Type of entity (e.g., agent , system ) |
data.updated_at | string | Timestamp 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "conversation.ended" |
affect | string | Always "delete" |
version | string | Event schema version, e.g. "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source (e.g., AI agent ID) |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the ended conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel where the conversation took place |
data.customer.id | string | Customer ID |
data.customer.name | string | Customer name |
data.customer.email | string | Customer email address |
data.customer.phone | string | Customer phone number |
data.customer.address | string | Address or source identifier |
data.customer.channel | string | Customer’s channel (should match data.channel ) |
data.updated_fields | array of string | List of fields that were changed before the conversation ended |
data.previous | object | Previous values before the final update |
data.current | object | Final values at the moment the conversation ended |
data.updated_by.id | string (optional) | ID of the user or agent who ended the conversation |
data.updated_by.name | string (optional) | Name of the user or agent |
data.updated_by.type | string (optional) | Type of entity (e.g., agent , system ) |
data.updated_at | string | Timestamp 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "message.new" |
affect | string | Always "add" |
version | string | Event schema version, e.g. "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source (e.g., AI agent ID) |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the conversation the message belongs to |
data.conversation_title | string | Title of the conversation |
data.message_id | string | Unique identifier of the message |
data.direction | string | Message direction (INBOUND or OUTBOUND ) |
data.created_at | string | When the message was created (ISO 8601 format) |
data.sender.type | string | Sender type (CUSTOMER , BOT , AGENT , etc.) |
data.sender.id | string | ID of the sender |
data.sender.name | string (optional) | Name of the sender |
data.content.type | string | Type of content (text , image , etc.) |
data.content.text | string | Textual content of the message |
data.content.data | object (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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "conversation.label.added" |
affect | string | Always "add" |
version | string | Event schema version, e.g., "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel type of the conversation |
data.customer | object | Customer information (id, name, contact info, etc.) |
data.updated_fields | array of string | List of updated fields (likely includes labels ) |
data.previous | object (optional) | Previous values of updated fields |
data.current | object (optional) | Current values of updated fields |
data.added_by | object (optional) | The user or bot who added the label |
data.added_at | string | Timestamp when the label was added |
data.labels | array of object | List 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "conversation.label.deleted" |
affect | string | Always "delete" |
version | string | Event schema version, e.g., "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel type of the conversation |
data.customer | object | Customer information (id, name, contact info, etc.) |
data.updated_fields | array of string | List of updated fields (likely includes labels ) |
data.previous | object (optional) | Previous values of updated fields |
data.current | object (optional) | Current values of updated fields |
data.removed_by | object (optional) | The user or bot who removed the label |
data.removed_at | string | Timestamp when the label was removed |
data.labels | array of object | List 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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "call.new" |
affect | string | Always "add" |
version | string | Event schema version, e.g., "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source |
source.type | string | Channel type (e.g., WEBCHAT , MESSENGER , etc.) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the associated conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel where the call took place |
data.direction | string | INBOUND or OUTBOUND |
data.call_from | object | Entity initiating the call (type, id, name, address) |
data.call_to | object | Entity receiving the call (type, id, name, address) |
data.started_at | string | Timestamp when the call started (ISO 8601 format) |
data.metadata | object (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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "call.ended" |
affect | string | Always "delete" |
version | string | Event schema version, e.g., "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source |
source.type | string | Channel type (e.g., SEAX_CALL , WHATSAPP ) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the associated conversation |
data.conversation_title | string | Title of the conversation |
data.channel | string | Channel where the call took place |
data.direction | string | INBOUND or OUTBOUND |
data.duration_seconds | integer | Duration of the call in seconds |
data.finish_reason | string | Reason the call ended (e.g., completed , abandoned , failed ) |
data.call_from | object | Caller info (type, id, name, address) |
data.call_to | object | Callee info (type, id, name, address) |
data.finished_at | string | When the call ended (ISO 8601) |
data.finished_by | string | Who ended the call (timestamp) |
data.recording_available | boolean | Whether a recording is available |
data.recording_url | string (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
Field | Type | Description |
---|
id | string | Unique identifier of the event |
event_type | string | Always "call.updated" |
affect | string | Always "update" |
version | string | Event schema version, e.g., "0.0.1" |
timestamp | string | When the event occurred, in ISO 8601 format |
workspace.id | string | Workspace ID associated with the event |
workspace.name | string | Workspace name |
source.id | string | ID of the event source |
source.type | string | Channel type (e.g., SEAX_CALL , WHATSAPP ) |
source.identifier | string | Identifier or name of the bot or integration |
data.conversation_id | string | ID of the associated conversation |
data.conversation_title | string | Title of the conversation |
data.call_id | string (optional) | ID of the call being updated |
data.update_reason | string (optional) | Description of why the call was updated |
data.previous | object (optional) | Previous values of updated fields |
data.current | object (optional) | New/current values of updated fields |
data.updated_at | string | When the update occurred (ISO 8601 format) |
data.resources | object (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",
}
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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of results to skip before starting to return. Default: 0 | 0 | |
limit | integer (query) | Max number of results to return. Default: 10 | 10 | |
is_owned | boolean (query) | Filter for owned records only. Default: false | true , false | |
enabled | boolean (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
}
GET /api/v1/workspace/{workspace_id}/contacts
Retrieve and filter contacts to target in your campaign.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of rows to skip. Default: 0 | 0 | |
limit | integer (query) | Number of rows to return. Default: 10 | 10 | |
keyword | string (query) | Search keyword for contact names and phones | +18111222333 | |
any_contact_label_ids | string (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_ids | string (query) | Include contacts with all of these label IDs. Comma-separated UUIDs | 11111111-2222-4444-3333-555555555555,22222222-3333-5555-4444-666666666666 | |
exclude_contact_ids | string (query) | Exclude specific contact IDs. Comma-separated UUIDs | 11111111-2222-4444-3333-555555555555,22222222-3333-5555-4444-666666666666 | |
exclude_labels | string (query) | Exclude contacts with these label IDs. Comma-separated values | f47ac10b-58cc-4372-a567-0e02b2c3d479,550e8400-e29b-41d4-a716-446655440000 | |
order_by | string (query) | Sort order. Default: created_time:desc | phone: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
}
POST /api/v1/workspace/{workspace_id}/import_contacts
Import contacts from a CSV file if you need to add new contacts.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
file | file (form-data) | CSV file containing contacts | contacts.csv | ✅ |
duplicate_strategy | string (query) | How to handle duplicate contacts | mark , skip , update | |
phone_country | string (query) | Default country code for phone numbers | US , 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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
name | string | Campaign name | Spring Sale 2025 | ✅ |
type | string | Campaign type | SMS , MMS , AI_AGENT , WHATSAPP_BUSINESS_PLATFORM_MESSAGE | ✅ |
message | string | Message content | 🌸 Spring Sale Alert! Get 25% off all items. Use code SPRING25. Valid until March 31st. | ✅ |
phone_ids | array[string] | Phone number IDs to send from | ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"] | ✅ |
any_contact_label_ids | array[string] | Include contacts with any of these labels | ["11111111-2222-4444-3333-555555555555"] | |
all_contact_label_ids | array[string] | Include contacts with all of these labels | ["22222222-3333-5555-4444-666666666666"] | |
exclude_contact_ids | array[string] | Exclude specific contact IDs | ["11111111-2222-4444-3333-555555555555"] | |
exclude_any_contact_label_ids | array[string] | Exclude contacts with any of these labels | ["33333333-4444-6666-5555-777777777777"] | |
media_urls | array[string] | Media URLs for MMS campaigns | ["https://example.com/image.jpg"] | |
start_time | string ($date-time) | Campaign start time (for scheduling) | 2025-07-18T10:00:00+00:00 | |
end_time | string ($date-time) | Campaign end time (for scheduling) | 2025-07-18T18:00:00+00:00 | |
is_schedule | boolean | Whether the campaign is scheduled | true , false | |
enable_link_shortening | boolean | Enable automatic link shortening in messages | true , false | |
attach_contact_label_ids | array[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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
campaign_id | string (path) | Unique identifier of the campaign | campaign_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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
campaign_id | string (path) | Unique identifier of the campaign | campaign_12345678-abcd-efgh-ijkl-123456789012 | ✅ |
message_statuses | string (query) | Filter by message status | sent,delivered,failed | |
offset | integer (query) | Number of rows to skip. Default: 0 | 0 | |
limit | integer (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).
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
phone_number | string | Sender phone number | +1234567890 | ✅ |
to_phone_number | string | Recipient phone number | +19876543210 | ✅ |
content | string | Message content | Thank you for your recent purchase! | ✅ |
media_urls | array[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
- Use Labels Effectively: Organize contacts with meaningful labels like
vip_customers
, new_subscribers
, location_nyc
- Exclude DNC Lists: Always exclude
DNC
(Do Not Contact) and unsubscribed
labels - Test with Small Groups: Test campaigns with a small subset before sending to large audiences
- Segment by Engagement: Use labels to track engagement levels and target accordingly
Message Content
- Keep It Concise: SMS messages have character limits; be clear and direct
- Include Clear CTAs: Use clear calls-to-action with shortened links
- Personalization: Use contact fields for personalized messaging
- Timing: Consider time zones and send during appropriate hours
Campaign Management
- Monitor Delivery: Check campaign logs regularly for delivery issues
- Track Performance: Monitor open rates, click rates, and conversions
- Handle Failures: Review failed messages and update contact information
- 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.
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
- Navigate to Account → API Key tab in your dashboard.
- Generate or refresh your API Key if necessary.
- 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
}
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of results to skip. Default is 0. | 0 | |
limit | integer (query) | Max number of results to return. Default is 10. | 10 | |
is_owned | boolean (query) | Filter for owned records only. Default is false. | true , false | |
enabled | boolean (query) | Filter by enabled status. Default is true. | true , false | |
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
}
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of rows to skip. Default is 0. | 0 | |
limit | integer (query) | Number of rows to return. Default is 10. | 10 | |
keyword | string (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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
name | string | Campaign name | WhatsApp Holiday Sale 2025 | ✅ |
type | string | Campaign type | WHATSAPP_BUSINESS_PLATFORM_MESSAGE | ✅ |
message | string | Message content | 🎉 Holiday Sale! Get 30% off all items. Use code HOLIDAY30. Valid until Dec 31st! | ✅ |
phone_ids | array[string] | Phone number IDs to send from | ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"] | ✅ |
any_contact_label_ids | array[string] | Include contacts with any of these labels | ["11111111-2222-4444-3333-555555555555"] | |
all_contact_label_ids | array[string] | Include contacts with all of these labels | ["22222222-3333-5555-4444-666666666666"] | |
exclude_contact_ids | array[string] | Exclude specific contact IDs | ["11111111-2222-4444-3333-555555555555"] | |
exclude_any_contact_label_ids | array[string] | Exclude contacts with any of these labels | ["33333333-4444-6666-5555-777777777777"] | |
start_time | string ($date-time) | Campaign start time (for scheduling) | 2025-07-18T10:00:00+00:00 | |
end_time | string ($date-time) | Campaign end time (for scheduling) | 2025-07-18T18:00:00+00:00 | |
is_schedule | boolean | Whether the campaign is scheduled | true , false | |
enable_link_shortening | boolean | Enable automatic link shortening in messages | true , false | |
attach_contact_label_ids | array[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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
campaign_id | string (path) | Unique identifier of the campaign | campaign_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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
campaign_id | string (path) | Unique identifier of the campaign | campaign_12345678-abcd-efgh-ijkl-123456789012 | ✅ |
message_statuses | string (query) | Filter by message status | sent,delivered,failed | |
offset | integer (query) | Number of rows to skip. Default: 0 | 0 | |
limit | integer (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
}
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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
file | file (form-data) | CSV file containing contacts | whatsapp_contacts.csv | ✅ |
duplicate_strategy | string (query) | How to handle duplicate contacts | mark , skip , update | |
phone_country | string (query) | Default country code for phone numbers | US , 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.
{
"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).
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
phone_number | string | Sender WhatsApp Business phone number | +1234567890 | ✅ |
to_phone_number | string | Recipient WhatsApp phone number | +19876543210 | ✅ |
message | string | Message content | Thank you for your interest in our products! | ✅ |
media_urls | array[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
- Use Labels Effectively: Organize contacts with meaningful labels like
premium_customers
, new_subscribers
, product_interested
- Exclude DNC Lists: Always exclude
DNC
(Do Not Contact) and unsubscribed
labels - Test with Small Groups: Test campaigns with a small subset before sending to large audiences
- Segment by Engagement: Use labels to track engagement levels and target accordingly
- WhatsApp Opt-ins: Ensure contacts have explicitly opted-in to receive WhatsApp messages
Message Content
- Follow WhatsApp Policies: Adhere to WhatsApp Business Platform messaging policies
- Use Approved Templates: For certain message types, use pre-approved message templates
- Personalization: Leverage contact fields for personalized messaging
- Rich Media: Utilize images, videos, and documents to enhance engagement
- Clear CTAs: Include clear call-to-action with trackable links
- Timing: Consider time zones and send during appropriate hours for your audience
Campaign Management
- Monitor Delivery: Check campaign logs regularly for delivery issues
- Track Performance: Monitor read rates, reply rates, and conversions
- Handle Failures: Review failed messages and update contact information
- Respect Opt-outs: Process unsubscribe requests immediately
- Link Shortening: Enable link shortening for better tracking and analytics
- Compliance: Ensure compliance with local messaging regulations and WhatsApp policies
WhatsApp-Specific Best Practices
- Business Verification: Ensure your WhatsApp Business account is properly verified
- Template Management: Manage and update message templates regularly
- Media Quality: Use high-quality media files that comply with WhatsApp’s size limits
- Response Time: Be prepared to handle replies promptly as WhatsApp users expect quick responses
- 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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key for authorization. Required in header. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of results to skip before starting to return. Minimum: 0 Default: 0 | 0 | |
limit | integer (query) | Max number of results to return after skipped offset. If 0, return all. Minimum: 0 Default: 10 | 10 | |
is_owned | boolean (query) | Filter for owned records only. Default: false | true , false | |
enabled | boolean (query) | Filter by whether the item is enabled. Default: true | true , false | |
voice_available | boolean (query) | Filter by voice capability availability | 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&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 /api/v1/workspace/{workspace_id}/contacts
Use this endpoint to retrieve the set of contacts you’d like to call during the campaign.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | Authorization with API key. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
offset | integer (query) | Number of rows to skip. Minimum: 0 Default: 0 | 0 | |
limit | integer (query) | Number of rows to return after skipped offset. If 0, return all. Minimum: 0 Default: 10 | 10 | |
keyword | string (query) | Optional search keyword for contact names and phones. Default: empty | +18111222333 | |
whatsapp_phone | string (query) | Optional search for contacts by WhatsApp phone. Default: empty | +18111222333 | |
all_contact_label_ids | string (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_ids | string (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_ids | string (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_ids | string (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_ids | string (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_ids | string (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_by | string (query) | Optional sorting. Comma-separated list of field:direction pairs. Default: created_time:desc | phone:asc,created_time:desc,name:asc | |
exclude_labels | string (query) | Exclude contacts with one or more of these label names (not IDs). Comma-separated values | DNC,invalid number,unreachable | |
whatsapp_phone_only | boolean (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 /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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | Authorization with API key. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
types | string (query) | Optional filter for AI agent integration types (comma-separated). | SEAX_CALL , SEAX_SMS , SEAX_WABP | |
limit | integer (query) | Optional. Number of rows to return after offset. 0 returns all. | Default: 10 Example: 10 | |
offset | integer (query) | Optional. Number of rows to skip before returning results. | Default: 0 Example: 0 | |
order_by | string (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
- POST /api/v1/workspace/{workspace_id}/auto_dialer_campaigns
Use this endpoint to trigger an outbound auto dialer voice campaign.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | Authorization with API key. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
name | string | Campaign name | Test | ✅ |
phone_ids | array[string] | Phone ID(s) to use for the campaign | ["020086f5-fb0e-4a0c-920a-bbdd04f4381c"] | ✅ |
attach_contact_label_ids | array[string] | Labels to attach to contacts after campaign | [] | |
start_time | string ($date-time) | Campaign start timestamp | 2025-07-08T03:06:09+00:00 | ✅ |
end_time | string ($date-time) | Campaign end timestamp | 2025-07-08T03:15:00+00:00 | ✅ |
is_schedule | boolean | Whether the campaign is scheduled | false | |
is_timezone_aware | boolean | Whether the schedule is timezone aware | false | |
mode | string | Campaign execution mode | WEB | ✅ |
stage | string | Processing stage of the campaign | INSTANCE | ✅ |
message | string | Message to be delivered (used by TTS or AI agent) | Hi, do you have a few minutes to take our survey? | |
tts_language | string | TTS language code | "" (Recommended to leave as empty string to use the default configured in your workspace) | |
tts_voice | string | TTS voice type | default | |
audio_url | string | Optional audio URL (if not using TTS) | "" (Recommended to leave as empty string to use default configured on seachat) | |
type | string | Campaign type | AI_AGENT | ✅ |
capture_keypress | boolean | Enable DTMF (keypress) capture | true | |
capture_stt | boolean | Enable speech-to-text (STT) capture | false | |
ai_agent_conversation_config_id | string | Conversation config ID used by the AI agent | 221316ae-8a9f-4f39-b7f8-f2e756b80a63 | ✅ |
overwrite_phone_recipient.type | string | The type of the recipient to overwrite with. | AI_AGENT | |
overwrite_phone_recipient.receiver | string | The identifier for the new recipient. | 221316ae-8a9f-4f39-b7f8-f2e756b80a63 | |
exclude_contact_ids | array[string] | Contact IDs to exclude | ["4667298e-8d5b-468e-8218-6a47925fe5f2","aa145964-6d17-488d-a9be-09a43191f329"] | |
any_contact_label_ids | array[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)
"overwrite_phone_recipient": {
"type": "AI_AGENT",
"receiver": "221316ae-8a9f-4f39-b7f8-f2e756b80a63"
}
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.
"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.
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | API key used for authenticating requests | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
types | string (query) | Filter by one or more auto dialer campaign types (comma-separated) | VOICE_DROP , PROGRESSIVE_DIALER , AI_AGENT | |
phone_numbers | string (query) | Filter by one or more phone numbers (comma-separated) | +15555550100,+15555550101 | |
ai_agent_conversation_config_id | string (query) | Filter by AI agent conversation config ID | 221316ae-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
Field | Type | Description | Allowed Values / Example | Required |
---|
X-API-Key | string (header) | Authorization with API key. See Authorization Guide | e91772ccb5e6ce5f932d6417eacd9a1e031b957101cdb68be76d417defa7fd28 | ✅ |
workspace_id | string (path) | Unique identifier of the workspace | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | ✅ |
auto_dialer_campaign_id | string (path) | Unique identifier of the auto dialer campaign | 01e14e9e-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
}