Skip to main content

WhatsApp

Send WhatsApp messages using approved templates through the WhatsApp Business API.

Send WhatsApp Message​

Send to Direct Phone Number​

const result = await sendmator.whatsapp.send({
  recipient_type: 'direct_whatsapp',
  direct_whatsapp: '+14155552671',
  template_key: 'order-confirmation',
  conversation_category: 'UTILITY',
  variables: {
    orderNumber: '#12345',
    total: '$99.99'
  }
});

console.log('WhatsApp sent:', result.success);

Send to Contact​

await sendmator.whatsapp.send({
  recipient_type: 'contact',
  contact_external_id: 'CRM-12345',
  template_key: 'appointment-reminder',
  conversation_category: 'UTILITY',
  variables: {
    customerName: 'John Doe',
    appointmentDate: 'Feb 1, 2024',
    appointmentTime: '2:00 PM'
  }
});

Send to Tags​

await sendmator.whatsapp.send({
  recipient_type: 'tag',
  tag: ['customer', 'premium'],
  template_key: 'new-feature-announcement',
  conversation_category: 'MARKETING',
  variables: {
    featureName: 'AI Assistant',
    featureUrl: 'https://example.com/features/ai'
  }
});

Conversation Categories​

WhatsApp requires specifying a conversation category:

CategoryUse CaseExamples
UTILITYAccount updates, order statusOrder confirmations, shipping updates
MARKETINGPromotional contentNew features, sales, newsletters
AUTHENTICATIONAccount verificationOTP codes, login verification

Complete Request Options​

await sendmator.whatsapp.send({
  // Recipient selection (required)
  recipient_type: 'direct_whatsapp',   // 'direct_whatsapp' | 'contact' | 'tag' | 'all'
  direct_whatsapp: '+14155552671',     // For direct_whatsapp type
  contact_external_id: 'CRM-123',      // For contact type
  tag: ['customer'],                   // For tag type

  // Template (required)
  template_key: 'order-confirmation',  // Approved template name
  conversation_category: 'UTILITY',    // UTILITY | MARKETING | AUTHENTICATION
  variables: {                         // Template variables
    orderNumber: '#12345'
  },

  // Optional
  whatsapp_identity_id: 'identity-uuid', // Specific WhatsApp Business Account
  campaign_name: 'holiday-sale',        // Campaign tracking
  metadata: {                           // Custom tracking data
    campaign: 'black-friday',
    source: 'web'
  },
  triggerAt: '2024-02-01T10:00:00Z'    // Schedule for future
});

Execution Status​

const status = await sendmator.whatsapp.getExecutionStatus('execution-uuid');

console.log('Status:', status.data.status);
console.log('Sent at:', status.data.executed_at);

List Executions​

const executions = await sendmator.whatsapp.listExecutions({
  page: 1,
  limit: 20
});

console.log('Total:', executions.data.total);

Examples​

Order Confirmation​

async function sendOrderConfirmation(phone: string, order: any) {
  await sendmator.whatsapp.send({
    recipient_type: 'direct_whatsapp',
    direct_whatsapp: phone,
    template_key: 'order-confirmation',
    conversation_category: 'UTILITY',
    variables: {
      orderNumber: order.number,
      items: order.items.map(i => i.name).join(', '),
      total: `$${order.total}`,
      estimatedDelivery: order.estimatedDelivery
    },
    metadata: {
      order_id: order.id
    }
  });
}

Authentication OTP​

async function sendWhatsAppOTP(phone: string, code: string) {
  await sendmator.whatsapp.send({
    recipient_type: 'direct_whatsapp',
    direct_whatsapp: phone,
    template_key: 'authentication-otp',
    conversation_category: 'AUTHENTICATION',
    variables: {
      code,
      expiresIn: '5 minutes'
    }
  });
}

Appointment Reminder​

async function sendAppointmentReminder(externalId: string, appointment: any) {
  await sendmator.whatsapp.send({
    recipient_type: 'contact',
    contact_external_id: externalId,
    template_key: 'appointment-reminder',
    conversation_category: 'UTILITY',
    variables: {
      customerName: appointment.customerName,
      date: appointment.date,
      time: appointment.time,
      location: appointment.location,
      confirmUrl: appointment.confirmUrl
    }
  });
}

Marketing Campaign​

async function sendMarketingCampaign() {
  await sendmator.whatsapp.send({
    recipient_type: 'tag',
    tag: ['customer', 'opted-in-whatsapp'],
    template_key: 'flash-sale',
    conversation_category: 'MARKETING',
    campaign_name: 'weekend-flash-sale',
    variables: {
      discount: '30%',
      endDate: 'Sunday',
      shopUrl: 'https://shop.example.com/sale'
    },
    metadata: {
      campaign: 'flash-sale',
      date: '2024-01-20'
    }
  });
}

Template Requirements​

WhatsApp templates must be:

  • ✅ Pre-approved by WhatsApp
  • ✅ Created in your WhatsApp Business Manager
  • ✅ Synced to Sendmator dashboard
  • ✅ Use approved variable placeholders
info

Templates must be approved by WhatsApp before use. This typically takes 24-48 hours.

Best Practices​

  1. Use Approved Templates - Only use templates approved by WhatsApp
  2. Choose Correct Category - Use the right conversation category to avoid billing issues
  3. Respect Opt-Ins - Only message users who opted in
  4. 24-Hour Window - Initiate conversations within 24 hours of last user message for free
  5. Rich Media - Use templates with images, buttons, and quick replies
  6. Track Campaigns - Use campaign_name for campaign analytics
  7. Test First - Test templates in sandbox before production

Conversation Pricing​

WhatsApp charges based on conversation category:

  • Authentication: Lowest cost (for OTP, login codes)
  • Utility: Medium cost (transactional, service messages)
  • Marketing: Highest cost (promotional content)

Choose the appropriate category to optimize costs.

Recipient Types​

TypeUse CaseRequired Field
direct_whatsappSend to phone without creating contactdirect_whatsapp
contactSend to existing contactcontact_external_id
tagSend to contacts with specific tagstag (array)
allSend to all contacts with WhatsApp numbersNone

Next Steps​