Send SMS Automation Processor

Overview

The Send SMS automation sends text messages to contacts associated with deals when they enter a specific pipeline stage. It uses Twilio API, validates phone numbers, and tracks delivery status.

Source File: queue-manager/queues/deals/automations/sms.js
Triggered By: queue-manager/services/deals/automations.js
Business Impact: HIGH - Customer communication

Processing Logic

sequenceDiagram
    participant AUTO as Automation Service
    participant QUEUE as SMS Queue
    participant DEAL as Deals
    participant CONTACT as Persons/Businesses
    participant SMS as SMS Utility
    participant TWILIO as Twilio API

    AUTO->>QUEUE: Add automation job
    QUEUE->>DEAL: Find eligible deals
    QUEUE->>CONTACT: Fetch contact phone numbers

    loop For Each Deal
        QUEUE->>QUEUE: Prepare SMS content<br/>(merge fields)
        QUEUE->>SMS: Send SMS
        SMS->>TWILIO: Deliver via API
        TWILIO-->>SMS: SMS ID
        SMS-->>QUEUE: SMS record created
        QUEUE->>DEAL: Log SMS sent
    end

Key Features

SMS Components

1. Recipients: Phone numbers from person/business contacts
2. Content: Text message with merge fields (max 1600 chars)
3. From: Twilio phone number
4. Origin: 'automation' for tracking

Merge Fields

Supports dynamic fields:

• {{deal.name}}
• {{person.first_name}}
• {{business.company}}
• {{user.name}}
• Custom deal fields

Phone Validation

• Validates E.164 format
• Checks for valid Twilio number
• Rejects invalid numbers before sending

Core Code Pattern

// Get SMS data
const smsData = await getSMSData(automationData);
const { account, user, deals, stage_id, automation, type } = smsData;
const smsBody = smsData.smsBody;

// Send each SMS
const smsUtil = new SMS();
for (const s of smsBody) {
  const { from, contents, origin, business, person, deal, recipients, fallback_entity } = s;

  const sentSms = await smsUtil.send({
    accountID: account,
    userID: user,
    smsData: {
      contents,
      recipients,
      from,
      origin,
    },
    personID: person,
    businessID: business,
    fallbackValues: fallback_entity,
  });

  if (sentSms.data.sentSmsDetails && sentSms.data.sentSmsDetails.length) {
    // Success: SMS record created
  }
}

Collections Used

Input: deal-automation

• SMS configuration

Query: deal

• Find eligible deals

Query: person / business

• Get contact phone numbers

Create: communication

• SMS records

SMS Data Structure

{
    recipients: ['+15551234567'],
    contents: 'Hi {{person.first_name}}, your proposal is ready!',
    from: '+15559876543', // Twilio number
    origin: 'automation'
}

Error Handling

Common Errors

1. Invalid Phone Number: Not E.164 format
2. No Phone Number: Contact has no phone
3. Twilio Failure: API error (unverified, insufficient funds)
4. Content Too Long: Exceeds 1600 chars
5. Template Error: Merge field missing

Error Response

{
    message: "Invalid phone number",
    deal: dealID,
    business: businessID,
    person: personID,
    additional_info: {...}
}

Use Cases

Example 1: Quick Follow-Up

// Automation
{
  stage_id: "demo_scheduled",
  action: "send_sms",
  data: {
    content: "Hi {{person.first_name}}, looking forward to your demo tomorrow at {{deal.demo_time}}!",
    recipients: "person"
  },
  delay: 0
}

Example 2: Reminder SMS

// Automation
{
  stage_id: "proposal_sent",
  action: "send_sms",
  data: {
    content: "Hi {{person.first_name}}, just checking if you had a chance to review the proposal we sent?",
    recipients: "person"
  },
  delay: 259200 // 3 days
}

Twilio Integration

Phone Number Format

// Valid formats
'+15551234567'; // E.164 (preferred)
'15551234567'; // Will be formatted
'+1 555-123-4567'; // Will be normalized

// Invalid formats
'555-123-4567'; // Missing country code
'(555) 123-4567'; // Not normalized

Rate Limiting

• Twilio: 1 message per second per account
• Queue handles throttling automatically
• Batch sends distributed over time

Performance

Execution Time: 300-1000ms per SMS
Batch Size: All eligible deals (sent in parallel)
Rate Limiting: Twilio throttling applies
Retry Strategy: 3 attempts with exponential backoff

---

Complexity: MEDIUM
Lines of Code: 250