Skip to main content

​
Crossbow Campaigns Guide

Complete guide to creating and executing high-volume marketing campaigns using the Crossbow API with Meta’s Marketing Messages Lite API.

​
Overview

Crossbow enables you to send marketing messages to thousands of contacts efficiently using Meta’s optimized delivery system. It handles rate limiting, retries, and provides detailed statistics.

​
Prerequisites

  • WhatsApp Business Account with Meta
  • Approved WhatsApp templates
  • Channel configured in Plati AI
  • Contact identities created

​
Workflow

1

Create Campaign

Define your campaign template and parameter strategy
2

Prepare Contacts

Ensure all contacts have required identity data
3

Create Flow

Create a flow with campaign and contact list
4

Monitor Execution

Track flow status and statistics in real-time
5

Review Results

Analyze delivery rates and errors

​
Step 1: Create a Campaign

Campaigns define reusable templates and parameter mappings. 
curl -X POST https://api.plati.ai/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelUid": "your-channel-uid",
    "name": "Black Friday 2024",
    "status": "ACTIVE",
    "templateName": "black_friday_promo",
    "templateParamsStrategy": "USE_CONTACT_ASSOCIATION",
    "templateParameters": {
      "customerName": "name",
      "discount": "discountCode, default",
      "product": "lastPurchase, favoriteCategory, default"
    }
  }'

​
Template Parameters

Use fallback chains to handle missing data: 
{
  "customerName": "name",                    // Direct mapping
  "discount": "discountCode, default",       // Try discountCode, fallback to default
  "product": "lastPurchase, favoriteCategory, default"  // Multiple fallbacks
}

​
Step 2: Prepare Contacts

Ensure contacts have the required identity data: 
curl -X PUT https://api.plati.ai/identity/contact_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "+5511999999999",
    "metadata": {
      "discountCode": "BF2024",
      "lastPurchase": "Product A",
      "favoriteCategory": "Electronics"
    }
  }'

​
Step 3: Create a Flow

Create a flow to execute the campaign: 
curl -X POST https://api.plati.ai/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelUid": "your-channel-uid",
    "campaignUid": "campaign-uuid-from-step-1",
    "contactUids": [
      "contact-uuid-1",
      "contact-uuid-2",
      "contact-uuid-3"
    ],
    "description": "Black Friday campaign execution",
    "configuration": {
      "maxRetries": 3,
      "pauseBetweenContactsMs": 5000,
      "pauseBetweenContactsSaltMs": 1000,
      "retryDelayMs": 5000,
      "timeoutMs": 300000,
      "maxConcurrentMessages": 1
    }
  }'

​
Configuration Best Practices

  • Small campaigns (less than 100 contacts): maxConcurrentMessages: 1, pauseBetweenContactsMs: 2000
  • Medium campaigns (100-1000 contacts): maxConcurrentMessages: 2, pauseBetweenContactsMs: 5000
  • Large campaigns (more than 1000 contacts): maxConcurrentMessages: 1, pauseBetweenContactsMs: 5000-10000

​
Step 4: Monitor Execution

Check flow status and statistics: 
curl -X GET https://api.plati.ai/flows/flow-uuid \
  -H "Authorization: Bearer YOUR_API_KEY"
Response includes:
  • Current status
  • Statistics (sent, delivered, read rates)
  • Error details
  • Estimated completion time

​
Step 5: Manage Flows

​
Pause a Running Flow

curl -X PATCH https://api.plati.ai/flows/flow-uuid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

​
Resume a Paused Flow

curl -X PATCH https://api.plati.ai/flows/flow-uuid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "running"}'

​
Cancel a Flow

curl -X PATCH https://api.plati.ai/flows/flow-uuid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'

​
Best Practices

​
Rate Limiting

  • Start conservative: 1 message per 5 seconds
  • Monitor delivery rates
  • Adjust based on Meta’s rate limits
  • Use salt to avoid pattern detection

​
Error Handling

  • Set appropriate retry counts (3-5)
  • Use reasonable timeouts (5-10 minutes)
  • Monitor error metadata for patterns
  • Handle opt-outs gracefully

​
Template Design

  • Keep templates simple and clear
  • Use fallback chains for optional parameters
  • Test templates before large campaigns
  • Ensure templates are approved by Meta

​
Contact Management

  • Verify contact data before creating flows
  • Use identity metadata for personalization
  • Handle missing data with fallbacks
  • Respect opt-out preferences

​
Common Scenarios

​
Scenario 1: Promotional Campaign

Send a promotional message to all active customers:
  1. Create campaign with promotional template
  2. Query identities with active: true
  3. Create flow with contact list
  4. Monitor delivery rates

​
Scenario 2: Segmented Campaign

Send different messages to different segments:
  1. Create multiple campaigns (one per segment)
  2. Filter contacts by segment
  3. Create separate flows per segment
  4. Compare performance across segments

​
Scenario 3: Scheduled Campaign

Schedule a campaign for a specific time:
  1. Create campaign
  2. Use Scheduled Tasks API to create flow at scheduled time
  3. Flow executes automatically

​
Troubleshooting

​
Low Delivery Rates

  • Check Meta template approval status
  • Verify contact phone numbers
  • Review rate limiting configuration
  • Check for opt-outs

​
High Error Rates

  • Review error metadata in flow response
  • Verify contact data completeness
  • Check template parameter mapping
  • Ensure channel is properly configured

​
Flow Stuck in Queued

  • Check channel status
  • Verify campaign is ACTIVE
  • Review system status
  • Contact support if persists

​
Next Steps

Campaigns API

Detailed campaign documentation

Flows API

Detailed flow documentation

Crossbow Overview

Crossbow API overview

Identity API

Manage contacts