0
# Message Creation
1

2
Core functionality for creating push notification messages with data payloads, notification content, and delivery options. Messages support both data payloads (processed by app code) and notification payloads (displayed by the system).
3

4
## Capabilities
5

6
### Message Constructor
7

8
Creates a new message instance with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Message instance
13
 * @param {MessageOptions} options - Optional message configuration
14
 * @returns {Message} Message instance
15
 */
16
function Message(options);
17

18
// Can be called with or without 'new'
19
const message1 = new Message();
20
const message2 = Message({ data: { key: 'value' } });
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
const gcm = require('node-gcm');
27

28
// Create empty message
29
const message = new gcm.Message();
30

31
// Create message with initial configuration
32
const message = new gcm.Message({
33
    collapseKey: 'update',
34
    priority: 'high',
35
    timeToLive: 3600,
36
    data: {
37
        userId: '12345',
38
        action: 'update_profile'
39
    },
40
    notification: {
41
        title: 'Profile Updated',
42
        body: 'Your profile has been successfully updated',
43
        icon: 'ic_notification'
44
    }
45
});
46
```
47

48
### Data Payload Management
49

50
Add custom key-value data to messages for processing by client applications.
51

52
```javascript { .api }
53
/**
54
 * Add a single data key-value pair
55
 * @param {string} key - Data key
56
 * @param {string} value - Data value
57
 */
58
message.addData(key, value);
59

60
/**
61
 * Set data payload object (overwrites existing data)
62
 * @param {Object} data - Data object with string keys and values
63
 */
64
message.addData(data);
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
const message = new gcm.Message();
71

72
// Add individual data fields
73
message.addData('userId', '12345');
74
message.addData('action', 'new_message');
75
message.addData('messageCount', '3');
76

77
// Set data object (overwrites previous data)
78
message.addData({
79
    userId: '12345',
80
    action: 'profile_update',
81
    timestamp: '1635789012'
82
});
83
```
84

85
### Notification Payload Management
86

87
Add display notification content for system-level notifications.
88

89
```javascript { .api }
90
/**
91
 * Add a single notification key-value pair
92
 * @param {string} key - Notification key
93
 * @param {string} value - Notification value
94
 */
95
message.addNotification(key, value);
96

97
/**
98
 * Set notification payload object (overwrites existing notification)
99
 * @param {NotificationPayload} notification - Notification object
100
 */
101
message.addNotification(notification);
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
const message = new gcm.Message();
108

109
// Add individual notification fields
110
message.addNotification('title', 'New Message');
111
message.addNotification('body', 'You have received a new message');
112
message.addNotification('icon', 'ic_message');
113
message.addNotification('sound', 'default');
114

115
// Set notification object (overwrites previous notification)
116
message.addNotification({
117
    title: 'Alert',
118
    body: 'System maintenance scheduled',
119
    icon: 'ic_warning',
120
    color: '#FF0000',
121
    click_action: 'MAINTENANCE_ACTIVITY'
122
});
123
```
124

125
### Message Serialization
126

127
Convert message to FCM-compatible JSON format.
128

129
```javascript { .api }
130
/**
131
 * Convert message to FCM JSON format
132
 * @returns {Object} FCM-compatible message object
133
 */
134
message.toJson();
135
```
136

137
**Usage Example:**
138

139
```javascript
140
const message = new gcm.Message({
141
    data: { key1: 'value1' },
142
    notification: { title: 'Hello' },
143
    priority: 'high'
144
});
145

146
const json = message.toJson();
147
console.log(json);
148
// Output:
149
// {
150
//   data: { key1: 'value1' },
151
//   notification: { title: 'Hello' },
152
//   priority: 'high'
153
// }
154
```
155

156
### Deprecated Methods
157

158
These methods are deprecated but still functional for backward compatibility.
159

160
```javascript { .api }
161
/**
162
 * @deprecated Use addData(key, value) instead
163
 */
164
message.addDataWithKeyValue(key, value);
165

166
/**
167
 * @deprecated Use addData(object) instead
168
 */
169
message.addDataWithObject(object);
170
```
171

172
## Message Options
173

174
All message configuration options that can be passed to the Message constructor or set via the message instance.
175

176
### Delivery Options
177

178
```javascript { .api }
179
interface MessageOptions {
180
    /** Groups messages that can be collapsed, only latest delivered when device comes online */
181
    collapseKey?: string;
182
    
183
    /** Message priority: 'normal' (default) or 'high' */
184
    priority?: 'normal' | 'high';
185
    
186
    /** iOS: wake inactive app when notification received */
187
    contentAvailable?: boolean;
188
    
189
    /** iOS 10+: allow notification content modification via app extension */
190
    mutableContent?: boolean;
191
    
192
    /** Delay message delivery when device is idle */
193
    delayWhileIdle?: boolean;
194
    
195
    /** Message expiration time in seconds (max 4 weeks, default 4 weeks) */
196
    timeToLive?: number;
197
    
198
    /** Restrict delivery to specific package name */
199
    restrictedPackageName?: string;
200
    
201
    /** Test mode - validate request without sending */
202
    dryRun?: boolean;
203
    
204
    /** Custom data payload for app processing */
205
    data?: { [key: string]: string };
206
    
207
    /** System notification payload */
208
    notification?: NotificationPayload;
209
    
210
    /** FCM-specific options */
211
    fcm_options?: { [key: string]: any };
212
}
213
```
214

215
### Notification Payload Options
216

217
```javascript { .api }
218
interface NotificationPayload {
219
    /** Notification title */
220
    title?: string;
221
    
222
    /** Notification body text */
223
    body?: string;
224
    
225
    /** Notification icon resource name */
226
    icon?: string;
227
    
228
    /** Sound to play (filename or 'default') */
229
    sound?: string;
230
    
231
    /** iOS: badge number to display */
232
    badge?: string;
233
    
234
    /** Android: notification tag for replacement */
235
    tag?: string;
236
    
237
    /** Android: notification color in #rrggbb format */
238
    color?: string;
239
    
240
    /** Action when notification clicked */
241
    click_action?: string;
242
    
243
    /** Localization key for body text */
244
    body_loc_key?: string;
245
    
246
    /** Localization arguments for body */
247
    body_loc_args?: string[];
248
    
249
    /** Localization key for title */
250
    title_loc_key?: string;
251
    
252
    /** Localization arguments for title */
253
    title_loc_args?: string[];
254
}
255
```
256

257
## Important Notes
258

259
- **Data Values**: All data payload values must be strings
260
- **Notification Display**: Notifications are only displayed when the app is in the background
261
- **Size Limits**: Total message payload should not exceed 4KB
262
- **Reserved Keys**: Avoid using 'from' in data payload as it may cause FCM errors
263
- **Platform Differences**: Some notification options are platform-specific (iOS vs Android)