Skip to main content

sendPush()

Sends a push notification to a user's registered device(s).

Signature​

async sendPush(request: SendPushRequest): Promise<any>

Parameters​

request​

  • Type: SendPushRequest
  • Required: Yes
  • Description: Push notification configuration

Returns​

Promise<any> - Response from the API containing delivery status.

Throws​

  • CDPPushError: Custom error with details about the failure
  • Validation errors: If required fields are missing or invalid

SendPushRequest Interface​

interface SendPushRequest {
  // Required
  identifiers: {
    id?: string;
    email?: string;
    cdp_id?: string;
  };
  transactional_message_id: string | number;
  
  // Optional
  title?: string;
  body?: string;
  message_data?: Record<string, any>;
}

Required Fields​

  • identifiers - User identifier (exactly one of: id, email)
  • transactional_message_id - Template ID for the push notification
Use Consistent Identifiers

The identifier must match the one used in identify(). See Consistent Identifiers for best practices.

Usage Examples​

Basic Push Notification​

await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'WELCOME_PUSH',
  title: 'Welcome!',
  body: 'Thank you for joining us!'
});

Push with Message Data​

await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'ORDER_UPDATE',
  message_data: {
    order_number: '12345',
    status: 'shipped',
    tracking_number: 'TRK789',
    estimated_delivery: '2025-11-02'
  }
});

Using Email Identifier​

await client.sendPush({
  identifiers: { email: '[email protected]' },
  transactional_message_id: 'PROMO_ALERT',
  title: 'Special Offer!',
  body: 'Get 20% off your next purchase'
});

Identifiers​

You must provide exactly ONE identifier type:

// ✅ Valid - Using user ID
identifiers: { id: 'user123' }
Use Consistent Identifiers

The identifier must match the one used in identify(). See Consistent Identifiers for best practices.

// ❌ Error - Multiple identifiers
identifiers: {
  id: 'user123',
  email: '[email protected]'
}

// ❌ Error - No identifier
identifiers: {}

Validation​

The SDK validates your request:

// ❌ Error: identifiers is required
await client.sendPush({
  transactional_message_id: 'WELCOME'
});

// ❌ Error: transactional_message_id is required
await client.sendPush({
  identifiers: { id: 'user123' }
});

// ❌ Error: body cannot be empty if provided
await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'WELCOME',
  body: '   '  // Empty/whitespace only
});

// ✅ Valid - Minimal required fields
await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'WELCOME'
});

// ✅ Valid - With optional fields
await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'WELCOME',
  title: 'Welcome',
  body: 'Thanks for signing up!'
});

Device Registration Required​

Device Must Be Registered

Users must have at least one registered device to receive push notifications.

See registerDevice() for details on device registration.

// First, register a device
await client.registerDevice('user123', {
  deviceId: 'device_abc123',
  platform: 'ios',
  fcmToken: 'fcm_token_here',
  appVersion: '1.0.0'
});

// Then send push notifications
await client.sendPush({
  identifiers: { id: 'user123' },
  transactional_message_id: 'WELCOME_PUSH',
  title: 'Welcome!',
  body: 'Thanks for installing our app'
});

Error Handling​

The SDK throws CDPPushError with detailed information:

try {
  const response = await client.sendPush({
    identifiers: { id: 'user123' },
    transactional_message_id: 'WELCOME_PUSH',
    title: 'Welcome!',
    body: 'Thank you for joining us!'
  });
  
  console.log('Push sent:', response);
} catch (error) {
  console.error('Push send failed:', {
    name: error.name,           // 'CDPPushError'
    code: error.code,           // 'PUSH_SEND_FAILED'
    message: error.message,     // Error description
    status: error.status,       // HTTP status code
    summary: error.summary      // Detailed error summary
  });
  
  // Handle specific errors
  if (error.status === 401) {
    console.error('Invalid API key');
  } else if (error.status === 404) {
    console.error('User or template not found');
  } else if (error.message.includes('No registered devices')) {
    console.error('User has no registered devices');
  }
}

Dual-Write Behavior​

Push NOT forwarded to Customer.io

Like emails, push notifications are NOT forwarded to Customer.io even when dual-write is enabled. This prevents duplicate notifications.

If sendToCustomerIo is true, you'll see this warning:

[CDP] Warning: Transactional messaging push will NOT be sent to Customer.io 
to avoid sending twice. To turn this warning off set `sendToCustomerIo` to false.