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"
  }
}
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