Skip to main content
POST
/
messaging
/
sms
/
campaign
curl -X POST https://api.avoca.ai/v1/messaging/sms/campaign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_type": "maintenance_reminder",
    "recipients": [
      {
        "phone": "+13105551234",
        "name": "John Smith",
        "custom_fields": {
          "last_service": "July 2023",
          "equipment_type": "AC Unit"
        }
      },
      {
        "phone": "+13105555678",
        "name": "Jane Doe",
        "custom_fields": {
          "last_service": "August 2023",
          "equipment_type": "Furnace"
        }
      }
    ],
    "message_template": "Hi {name}, your {equipment_type} is due for maintenance (last service: {last_service}). Reply YES to schedule or call 555-0123.",
    "schedule_time": "2024-01-22T10:00:00Z",
    "settings": {
      "include_opt_out": true,
      "respect_quiet_hours": true
    }
  }'

{
  "data": {
    "campaign_id": "camp_abc123",
    "status": "sending",
    "recipients_count": 1543,
    "messages_sent": 487,
    "estimated_cost": 23.15,
    "scheduled_time": "2024-01-22T10:00:00Z",
    "completion_time": null
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-22T10:02:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.avoca.ai/llms.txt

Use this file to discover all available pages before exploring further.

Create and send SMS campaigns to customer segments for marketing, maintenance reminders, or service notifications. All campaigns comply with SMS regulations including opt-out management.

​
Request

​
campaign_type
string
required
Type of campaign:
  • maintenance_reminder - Service due reminders
  • seasonal_promotion - Seasonal offers
  • service_follow_up - Post-service follow-ups
  • appointment_reminder - Bulk appointment reminders
  • emergency_notification - Urgent notifications
  • marketing - General marketing messages
​
recipients
array
required
List of recipients (max 10,000 per campaign)
​
message_template
string
required
Message template with merge variables using syntax
​
schedule_time
string
ISO 8601 timestamp to send campaign (omit for immediate)
​
settings
object
Campaign settings
​
segmentation
object
Recipient filtering criteria
​
fallback_message
string
Message to use if personalization fails

​
Response

​
campaign_id
string
Unique campaign identifier
​
status
string
Campaign status:
  • scheduled - Scheduled for future
  • sending - Currently sending
  • completed - Finished sending
  • cancelled - Campaign cancelled
​
recipients_count
number
Total number of recipients
​
messages_sent
number
Number of messages sent so far
​
estimated_cost
number
Estimated total cost in dollars
​
scheduled_time
string
When campaign will/did start
​
completion_time
string
When campaign finished (if completed)
curl -X POST https://api.avoca.ai/v1/messaging/sms/campaign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_type": "maintenance_reminder",
    "recipients": [
      {
        "phone": "+13105551234",
        "name": "John Smith",
        "custom_fields": {
          "last_service": "July 2023",
          "equipment_type": "AC Unit"
        }
      },
      {
        "phone": "+13105555678",
        "name": "Jane Doe",
        "custom_fields": {
          "last_service": "August 2023",
          "equipment_type": "Furnace"
        }
      }
    ],
    "message_template": "Hi {name}, your {equipment_type} is due for maintenance (last service: {last_service}). Reply YES to schedule or call 555-0123.",
    "schedule_time": "2024-01-22T10:00:00Z",
    "settings": {
      "include_opt_out": true,
      "respect_quiet_hours": true
    }
  }'

{
  "data": {
    "campaign_id": "camp_abc123",
    "status": "sending",
    "recipients_count": 1543,
    "messages_sent": 487,
    "estimated_cost": 23.15,
    "scheduled_time": "2024-01-22T10:00:00Z",
    "completion_time": null
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-22T10:02:00Z"
  }
}

​
Campaign Status Webhook

{
  "event": "sms_campaign.completed",
  "timestamp": "2024-01-22T10:15:00Z",
  "data": {
    "campaign_id": "camp_abc123",
    "status": "completed",
    "final_counts": {
      "sent": 1534,
      "failed": 9,
      "opted_out": 12
    },
    "engagement": {
      "replies": 234,
      "link_clicks": 145,
      "conversions": 89
    },
    "total_cost": 23.01
  }
}

​
Best Practices

  1. Timing: Send between 10 AM - 6 PM recipient time
  2. Personalization: Use customer name and relevant details
  3. Clear CTA: Include one clear action (Reply YES, Call, Click link)
  4. Compliance: Always include opt-out for marketing messages
  5. Segmentation: Target relevant customers to improve engagement