{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":855,"path":"api-reference/server-api-reference/NotifySMSAPI.md","title":"NotifySMS - Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# NotifySMS- Global\n\nThe NotifySMS script include provides methods that enable you to send Short Message Service \\(SMS\\) messages from Notify telephone numbers to devices using either their telephone numbers or a GlideRecord that has a field that contains telephone number information.\n\nTo use this script include you must activate the Notify \\(com.snc.notify\\) plugin.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## NotifySMS - NotifySMS\\(\\)\n\nCreates an instance of a NotifySMS object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| ||\n\nThis example shows how to instantiate a NotifySMS object.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n var fromNumber = getFromNumber();\n var groupId = sourceRecord.assignment_group + '';\n var toGr = getRecipientGRs(groupId);\n var message = 'An Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to your group';\n if (fromNumber && toGr) {\n var notifySMS = new NotifySMS();\n notifySMS.sendToUsers(fromNumber, toGr, message, sourceRecord);\n } \n}\n```\n\n## NotifySMS - sendBulkSMS\\(String fromNumber, Array toNumber, String message, GlideRecord sourceRecord\\)\n\nTriggers an asynchronous flow action that sends a Short Message Service \\(SMS\\) message from a specified Notify phone number to a list of phone numbers.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nfromNumber\n\n\n\nString\n\n\n\nNotify telephone number sending the SMS message.\n\n
\n\ntoNumber\n\n\n\nArray\n\n\n\nList of telephone numbers to receive the SMS message.\n\n
\n\nmessage\n\n\n\nString\n\n\n\nMessage to send.\n\n
\n\nsourceRecord\n\n\n\nGlideRecord\n\n\n\nOptional. Incident GlideRecord to store in the Source field of the associated SMS message record in the Notify Message \\[notify\\_message\\] table. This links the Incident record that caused the SMS message to be generated to that SMS message.Default: None. If this parameter is not passed in, this information is not tracked.\n\n
|Type|Description|\n|----|-----------|\n|ScriptableFlowRunnerResult|[ScriptableFlowRunnerResult - Scoped](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/ScriptableFlowRunnerResultScopedAPI.md) object.|\n\nThe follow code example shows how you can use this method to send a bulk SMS message.\n\n```\nvar fromNumber = getFromNumber();\nvar toNumbers = getRecipientNumbers();\nvar message = 'This is an example SMS';\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n var notifySMS = new NotifySMS();\n notifySMS.sendBulkSMS(fromNumber, toNumbers, message, sourceRecord); \n}\n\nfunction getRecipientNumbers() {\n var userGr = new GlideRecord('sys_user');\n userGr.addActiveQuery();\n userGr.addQuery('first_name', 'STARTSWITH', 'A');\n userGr.setLimit(5);\n userGr.query();\n var userIds = []; \n while (userGr.next()) { \n userIds.push(userGr.getUniqueValue());\n } \n if (userIds.length > 0) { \n var nUtil = new NotifyUtil();\n return nUtil.getUniquePhoneNumbersForUsersAndGroups(null, userIds, null, 'sms', false); \n } \n} \n\nfunction getFromNumber() {\n var prop = gs.getProperty('custom_property_name', '');\n if (!prop){\n return getFallbackFromNumber();\n }\n return prop;\n}\n\nfunction getFallbackFromNumber() {\n var notifyNumGr = new GlideRecord(\"notify_number\");\n notifyNumGr.addActiveQuery();\n notifyNumGr.addQuery('has_sms_out', 'yes');\n notifyNumGr.query();\n if (notifyNumGr.next()) {\n return notifyNumGr.number + '';\n }\n return '';\n}\n```\n\n## NotifySMS - sendToNumber\\(String fromNumber, String toNumber, String message, Object sourceRecord\\)\n\nSends a Short Message Service \\(SMS\\) message from a specified Notify telephone number to a specified telephone number.\n\nIn addition, you can optionally associate the Incident record that caused the SMS message to be generated to the SMS message.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nfromNumber\n\n\n\nString\n\n\n\nNotify telephone number sending the SMS message.\n\n
\n\nmessage\n\n\n\nString\n\n\n\nMessage to send.\n\n
\n\nsourceRecord\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nOptional. Incident GlideRecord to store in the Source field of the associated SMS message record in the Notify Message \\[notify\\_message\\] table. This links the Incident record that caused the SMS message to be generated to that SMS message.Default: None. If this parameter is not passed in, this information is not tracked.\n\n
\n\ntoNumber\n\n\n\nString\n\n\n\nTelephone number of the device to receive the SMS message.\n\n
|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example illustrates how to send an SMS message to a specified phone number and stamp the associated Incident record with the message information.\n\n```\nvar fromNumber = getFromNumber(); \nvar toNumber = '+123456789'; \nvar message = 'This is an example SMS'; \nvar sourceRecord = new GlideRecord('incident'); \nsourceRecord.query(); \nif (sourceRecord.next()) { \n var notifySMS = new NotifySMS();\n notifySMS.sendToNumber(fromNumber, toNumber, message, sourceRecord); \n} \n\nfunction getFromNumber() { \n var prop = gs.getProperty('custom_property_name', ''); \n if (!prop){ \n return getFallbackFromNumber(); \n } \n return prop;\n} \n\nfunction getFallbackFromNumber() { \n var notifyNumGr = new GlideRecord(\"notify_number\");\n notifyNumGr.addActiveQuery();\n notifyNumGr.addQuery('has_sms_out', 'yes');\n notifyNumGr.query();\n if (notifyNumGr.next()) { \n return notifyNumGr.number + '';\n } \n return ''; \n} \n```\n\n## NotifySMS - sendToNumbers\\(String fromNumber, Array toNumber, String message, Object sourceRecord\\)\n\nSends a Short Message Service \\(SMS\\) message from a specified Notify phone number to a list of phone numbers.\n\nIn addition, you can optionally associate the Incident record that caused the SMS message to be generated with the SMS message.\n\n**Note:** Internally this method uses the [NotifySMS - sendBulkSMS\\(String fromNumber, Array toNumber, String message, GlideRecord sourceRecord\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/NotifySMSAPI.md) method to trigger an asynchronous flow action.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nfromNumber\n\n\n\nString\n\n\n\nNotify telephone number sending the SMS message.\n\n
\n\nmessage\n\n\n\nString\n\n\n\nMessage to send.\n\n
\n\nsourceRecord\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nOptional. Incident GlideRecord to store in the Source field of the associated SMS message record in the Notify Message \\[notify\\_message\\] table. This links the Incident record that caused the SMS message to be generated to that SMS message.Default: None. If this parameter is not passed in, this information is not tracked.\n\n
\n\ntoNumber\n\n\n\nArray\n\n\n\nList of telephone numbers to receive the SMS message.\n\n
|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example illustrates how to send an SMS message to multiple telephone numbers and store the information in the associated Incident record.\n\n```\nvar fromNumber = getFromNumber();\nvar toNumbers = getRecipientNumbers()\nvar message = 'This is an example SMS';\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n var notifySMS = new NotifySMS();\n notifySMS.sendToNumbers(fromNumber, toNumbers, message, sourceRecord); \n}\n\nfunction getRecipientNumbers() {\n var userGr = new GlideRecord('sys_user');\n userGr.addActiveQuery();\n userGr.addQuery('first_name', 'STARTSWITH', 'A');\n userGr.setLimit(5);\n userGr.query();\n var userIds = []; \n while (userGr.next()) { \n userIds.push(userGr.getUniqueValue());\n } \n if (userIds.length > 0) { \n var nUtil = new NotifyUtil();\n return nUtil.getUniquePhoneNumbersForUsersAndGroups(null, userIds, null, 'sms', false); \n } \n} \n\nfunction getFromNumber() {\n var prop = gs.getProperty('custom_property_name', '');\n if (!prop){\n return getFallbackFromNumber();\n }\n return prop;\n}\n\nfunction getFallbackFromNumber() {\n var notifyNumGr = new GlideRecord(\"notify_number\");\n notifyNumGr.addActiveQuery();\n notifyNumGr.addQuery('has_sms_out', 'yes');\n notifyNumGr.query();\n if (notifyNumGr.next()) {\n return notifyNumGr.number + '';\n }\n return '';\n} \n```\n\n## NotifySMS - sendToUser\\(String fromNumber, Object toGr, String message, Object sourceRecord\\)\n\nSends a Short Message Service \\(SMS\\) message from a specified phone number to the user identified in a specified GlideRecord.\n\nThis method extracts the telephone number from the specified GlideRecord. In addition, you can optionally associate the Incident record that caused the SMS message to be generated with the SMS message.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nfromNumber\n\n\n\nString\n\n\n\nNotify telephone number sending the SMS message.\n\n
\n\nmessage\n\n\n\nString\n\n\n\nMessage to send.\n\n
\n\nsourceRecord\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nOptional. Incident GlideRecord to store in the Source field of the associated SMS message record in the Notify Message \\[notify\\_message\\] table. This links the Incident record that caused the SMS message to be generated to that SMS message.Default: None. If this parameter is not passed in, this information is not tracked.\n\n
\n\ntoGr\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nGlideRecord of a record type that contains a field that resolves to a user's telephone number. The record type must correlate with the record type used by the phone number resolver that is currently implemented. A phone number resolver is simply a method that obtains the user telephone number from a specific type of GlideRecord, such as a User record or a Case record. When using the default resolver, the records correspond to the User \\[sys\\_user\\] table. To change the type of record that the resolver uses to obtain the telephone number, use the [NotifySMS - setRecordToNumberResolver\\(Object scriptIncludeInstance, String methodName\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/NotifySMSAPI.md) method.\n\n
|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example illustrates how to send an SMS message to a user identified in the associated Incident record and stamp the associated Incident record with the message information.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n var fromNumber = getFromNumber();\n var toGr = sourceRecord.assigned_to.getRefRecord();\n var message = 'An Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to you'; \n if (fromNumber && toGr.isValidRecord()) { \n var notifySMS = new NotifySMS();\n notifySMS.sendToUser(fromNumber, toGr, message, sourceRecord);\n }\n}\n\nfunction getFromNumber() {\n var prop = gs.getProperty('custom_property_name', '');\n if (!prop){\n return getFallbackFromNumber();\n }\n return prop; \n}\n\nfunction getFallbackFromNumber() {\n var notifyNumGr = new GlideRecord(\"notify_number\");\n notifyNumGr.addActiveQuery();\n notifyNumGr.addQuery('has_sms_out', 'yes');\n notifyNumGr.query();\n if (notifyNumGr.next()) {\n return notifyNumGr.number + '';\n }\n return ''; \n} \n```\n\n## NotifySMS - sendToUsers\\(String fromNumber, Object toGr, String message, Object sourceRecord\\)\n\nSends a Short Message Service \\(SMS\\) message from a specified Notify phone number to users found in a specified GlideRecord.\n\nThis method extracts the destination telephone numbers from the passed-in GlideRecord. In addition, you can optionally associate the Incident record that caused the SMS message to be generated with the SMS message.\n\n**Note:** Internally this method uses the [NotifySMS - sendBulkSMS\\(String fromNumber, Array toNumber, String message, GlideRecord sourceRecord\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/NotifySMSAPI.md) method to trigger an asynchronous flow action.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nfromNumber\n\n\n\nString\n\n\n\nNotify telephone number sending the SMS message.\n\n
\n\nmessage\n\n\n\nString\n\n\n\nMessage to send.\n\n
\n\nsourceRecord\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nOptional. Incident GlideRecord to store in the Source field of the associated SMS message record in the Notify Message \\[notify\\_message\\] table. This links the Incident record that caused the SMS message to be generated to that SMS message.Default: None. If this parameter is not passed in, this information is not tracked.\n\n
\n\ntoGr\n\n\n\n[GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n\n\nGlideRecord of a record type that contains a field that resolves to a user's telephone number. The record type must correlate with the record type used by the phone number resolver that is currently implemented. A phone number resolver is simply a method that obtains the user telephone number from a specific type of GlideRecord, such as a User record or a Case record. When using the default resolver, the records correspond to the User \\[sys\\_user\\] table. To change the type of record that the resolver uses to obtain the telephone number, use the [NotifySMS - setRecordToNumberResolver\\(Object scriptIncludeInstance, String methodName\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/NotifySMSAPI.md) method.\n\n
|Type|Description|\n|----|-----------|\n|None| |\n\nThis example shows how to send an SMS message to users within a specified incident record.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n var fromNumber = getFromNumber();\n var groupId = sourceRecord.assignment_group + '';\n var toGr = getRecipientGRs(groupId);\n var message = 'An Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to your group';\n if (fromNumber && toGr) {\n var notifySMS = new NotifySMS();\n notifySMS.sendToUsers(fromNumber, toGr, message, sourceRecord);\n } \n} \n\nfunction getFromNumber() {\n var prop = gs.getProperty('custom_property_name', '');\n if (!prop){\n return getFallbackFromNumber();\n }\n return prop;\n}\n\nfunction getFallbackFromNumber() {\n var notifyNumGr = new GlideRecord(\"notify_number\");\n notifyNumGr.addActiveQuery();\n notifyNumGr.addQuery('has_sms_out', 'yes');\n notifyNumGr.query();\n if (notifyNumGr.next()) {\n return notifyNumGr.number + '';\n }\n return ''; \n}\n\nfunction getRecipientGRs(groupId) {\n if (!groupId)\n return;\n var userMemberGr = new GlideRecord('sys_user_grmember');\n userMemberGr.addQuery('group', groupId);\n userMemberGr.query();\n var userIds = [];\n while (userMemberGr.next()) {\n userIds.push(userMemberGr.user + ''); \n }\n var userGr = new GlideRecord('sys_user');\n userGr.addActiveQuery();\n userGr.addQuery('sys_id', 'IN', userIds.join(','));\n userGr.query();\n return userGr; \n} \n```\n\n## NotifySMS - setRecordToNumberResolver\\(Object scriptIncludeInstance, String methodName\\)\n\nSets the method within a script include to use to obtain the target telephone number in the GlideRecord that is passed in the NotifySMS.sendToUser\\(\\) and NotifySMS.sendToUsers\\(\\) methods.\n\nBy default, the NotifyUtil.getSMSNumberForUser\\(\\) method is used to obtain the telephone number from a User \\[sys\\_user\\] based GlideRecord. Use the setRecordToNumberResolver\\(\\) method if you need to create a custom method to obtain this information from a different record type, such as a Case record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|methodName|String|Name of the method to use to obtain the target telephone number in a GlideRecord.|\n|scriptIncludeInstance|Object|Instance of the script include that contains the specified number resolver method.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThis example shows how to set the phone number resolver to the getSMSNumberForConsumer\\(\\) method within the csmUtils script include.\n\n```\n// Script include that contains the logic to retrieve a phone number for a consumer.\nvar csmUtils = new global.CSMExampleUtils();\n \n// Example Case record used as source for sending SMS\nvar caseGr = new GlideRecord('sn_customerservice_case');\ncaseGr.get('3af265b3d1cb5010f877cb055160faxx'); // Case sys_id\n \nvar notifySms = new global.NotifySMS();\n \n// Use the getSMSNumberForConsumer method of the csmUtils script include (CSMExampleUtils) to obtain the phone number of the consumer.\nnotifySms.setRecordToNumberResolver(csmUtils, 'getSMSNumberForConsumer');\n \n// Send an SMS message to a user whose telephone number is in the specified Case GlideRecord.\nvar smsText = 'This is a test message for ' + caseGr.getValue('number');\nnotifySms.sendToUser('+1xxxxxxxxxx', caseGr.getValue('consumer'), smsText, caseGr); // First param is the Notify phone number\n```\n\nThis example shows the code needed for the telephone resolver method getSMSNumberForConsumer\\(\\).\n\n```\ngetSMSNumberForConsumer: function(consumerGrOrId) {\n if (!consumerGrOrId)\n return;\n \n var consumerId, consumerGr;\n if (typeof consumerGrOrId === \"string\")\n consumerId = consumerGrOrId;\n if (typeof consumerGrOrId === \"object\" && consumerGrOrId[\"isValidRecord\"]) {\n consumerGr = consumerGrOrId;\n consumerId = consumerGr.getUniqueValue();\n }\n \n if (!consumerId)\n return;\n \n if (!consumerGr) {\n consumerGr = new GlideRecord('csm_consumer');\n consumerGr.get(consumerId);\n }\n \n if (consumerGr.isValidRecord()) {\n return consumerGr.getValue('mobile_phone');\n }\n}\n```\n\n"}}