{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1072,"path":"api-reference/server-api-reference/c_NotifyNow.md","title":"NotifyNow \\(Legacy\\) - Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# NotifyNow \\(Legacy\\)- Global\n\nThe legacy NotifyNow API provides functionality for sending emails, sending SMS messages, and setting up conference calls.\n\nUse this when you want to use Notify functionality with applications on your system.\n\n**Note:** This API is included with the legacy Notify functionality. For APIs included in the current Notify feature, see the Notify, NotifyAction, NotifyPhoneNumber, and NotifyClient APIs.\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## NotifyNow - addConferenceCallParticipant\\(String conferenceCall, String participant\\)\n\nAdds ad-hoc users to an ongoing conference call.\n\nWhen the method is called with a phone number for the participant parameter and there is exactly one sys\\_user record that matches the phone number, that sys\\_user record will be related to the participant. The participant's phone number field will be left blank because the phone number is in the sys\\_user record. If there are several sys\\_user records that match the phone number, or if there are no results, the participant's phone number field will be filled in, and there will be no stored reference to sys\\_user because the user is not known.\n\n|Name|Type|Description|\n|----|----|-----------|\n|conferenceCall|String or GlideRecord|The sys\\_id or GlideRecord of an active conference call.|\n|participant|String or GlideRecord|The sys\\_id or GlideRecord of a user with an E.164-compliant phone number, or an E.164-compliant phone number.|\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|The participant record of the new participant that was added to the conference call.|\n\n```\n// add a new participant by conference call sys_id (string) and phone number (string) \nvar nn = new SNC.NotifyNow();\ngs.log(nn.addConferenceCallParticipant('d193b242eb020100a04d4910f206fe39', '+31612345678'));\n```\n\n```\n// add a new participant by conference call sys_id (string) and user record (GlideRecord)\nvar user = new GlideRecord('sys_user');\nuser.query('user_name', 'myUserName');\nif (user.hasNext() && user.next()) {\n var nn = new SNC.NotifyNow();\n gs.log(nn.addConferenceCallParticipant('d193b242eb020100a04d4910f206fe39', user));\n \n // you could have added the user by sys_id as well:\n // nn.addConferenceCallParticipant('d193b242eb020100a04d4910f206fe39', user.getValue('sys_id'));\n} else {\n gs.log('no such user');\n}\n```\n\n```\n// add a new participant by conference call record (GlideRecord) and phone number (string)\nvar conferenceCall = new GlideRecord('notifynow_conference_call');\nconferenceCall.query('title', 'IA0001001');\nif (conferenceCall.hasNext() && conferenceCall.next()) {\n var nn = new SNC.NotifyNow();\n gs.log(nn.addConferenceCallParticipant(conferenceCall, '+31612345678'));\n} else {\n gs.log('no such conference call');\n}\n```\n\n## NotifyNow - convertLocalPhoneNumberToE164\\(String userID, String phoneNumber\\)\n\nConverts a local phone number to an E.164-compliant phone number based on a user's location.\n\n|Name|Type|Description|\n|----|----|-----------|\n|userID|String|The sys\\_id of a sys\\_user record to get location information from.|\n|phoneNumber|String|The phone number.|\n\n|Type|Description|\n|----|-----------|\n|String|The E.164-compliant phone number.|\n\n```\nvar localPhoneNumber = '01784 221600';\nvar userName = 'Heath Vanalphen';\n \nvar user = new GlideRecord('sys_user');\nuser.get('name',userName);\nvar E164Number = new SNC.NotifyNow().convertLocalPhoneNumberToE164(user.getUniqueValue(), localPhoneNumber);\ngs.log('converted: ' + localPhoneNumber + ' to ' + E164Number + ' based on ' + user.getValue('name') + \n '\\'s location (' + user.getValue('location') + ')');\n```\n\n## NotifyNow - getConferenceCallParticipants\\(String conferenceCallId, Boolean isCallable\\)\n\nReturns all participants for a conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|conferenceCallId|String|The ID of the conference call.|\n|isCallable|Boolean|An optional flag to return either only the users you can call \\(true\\) or those you cannot call \\(false\\).|\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|The participants|\n\n```\nvar nn = new SNC.NotifyNow();\nvar user = nn.getConferenceCallParticipants('c2e91710eb120100f34087b9d106fe37');\n \nwhile (user.hasNext() && user.next()) {\n if (user.getValue('participant')) {\n gs.log('user: ' + user.getValue('sys_id'));\n } else {\n gs.log('phone number: ' + user.getValue('phone_number'));\n }\n}\n```\n\n```\nvar nn = new SNC.NotifyNow();\nvar user = nn.getConferenceCallParticipants('c2e91710eb120100f34087b9d106fe37', true);\n \nwhile (user.hasNext() && user.next()) {\n if (user.getValue('participant')) {\n gs.log('user: ' + user.getValue('sys_id'));\n } else {\n gs.log('phone number: ' + user.getValue('phone_number'));\n }\n}\n```\n\n```\nvar conferenceCallId = '32b11430eb1201003cf587b9d106feb8';\n \n// get all participants\ngs.log('all conference call participants:');\nvar nn = new SNC.NotifyNow();\nvar user = nn.getConferenceCallParticipants(conferenceCallId);\ngs.log(user);\n \n// get all callable participants\ngs.log('all conference call participants we can call:');\nuser = nn.getConferenceCallParticipants(conferenceCallId, true);\ngs.log(user);\n \n// get all un callable participants\ngs.log('all conference call participants that are already in an active session and whom we cannot call:');\nuser = nn.getConferenceCallParticipants(conferenceCallId, false);\ngs.log(user);\n```\n\n## NotifyNow - getFrequentlyCalledUsers\\(Number limit\\)\n\nReturns a number of frequently-called users, up to the limit parameter, in alphabetical order.\n\n|Name|Type|Description|\n|----|----|-----------|\n|limit|Number|The maximum number of results.|\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|The frequently called users in alphabetical order.|\n\n```\nvar nn = new SNC.NotifyNow();\nvar fc = nn.getFrequentlyCalledUsers(10);\n \nwhile (fc.hasNext() && fc.next()) {\n gs.log(\"got user \" + fc.getValue('name') + ' - ' + fc.getValue('sys_id'));\n}\n```\n\n## NotifyNow - getPreferredE164SMSNumber\\(GlideRecord user\\)\n\nReturns a user's preferred E.164-compliant phone number for SMS messages.\n\n|Name|Type|Description|\n|----|----|-----------|\n|user|GlideRecord or String|The user record or the sys\\_id of a user to get the E.164-compliant phone number from.|\n\n|Type|Description|\n|----|-----------|\n|String|The E.164-compliant phone number or null.|\n\n```\nvar userID = \"\";\nvar E164Number = new SNC.NotifyNow().getPreferredE164SMSNumber(userID);\ngs.log('the preferred phone number for sending SMS notifications is ' + E164Number + ' for user with id: ' + userID);\n```\n\n## NotifyNow - getPreferredE164VoiceNumber\\(GlideRecord user\\)\n\nReturns a user's preferred E.164-compliant phone number for voice calls.\n\n|Name|Type|Description|\n|----|----|-----------|\n|user|GlideRecord or String|The user record or the sys\\_id of a user to get the E.164-compliant phone number from.|\n\n|Type|Description|\n|----|-----------|\n|String|The E.164-compliant phone number or null.|\n\n```\nvar userID = \"\";\nvar E164Number = new SNC.NotifyNow().getPreferredE164VoiceNumber(userID);\ngs.log('the preferred phone number for setting up voice calls is ' + E164Number + ' for user with id: ' + userID);\n```\n\n## NotifyNow - getPreferredEmailAddress\\(GlideRecord user\\)\n\nReturns a user's preferred email address\n\n|Name|Type|Description|\n|----|----|-----------|\n|user|GlideRecord or String|The user record or the sys\\_id of a user to get the email address from.|\n\n|Type|Description|\n|----|-----------|\n|String|The email address or null.|\n\n```\nvar userID = \"some user sys id\";\nvar email = new SNC.NotifyNow().getPreferredEmailAddress(userID);\ngs.log('the preferred email address for sending email notifications is ' + email + ' for user with id: ' + userID);\n```\n\n## NotifyNow - getReadyState\\(\\)\n\nIndicates whether Notify is set up correctly or not.\n\nThis method can only be accessed by administrators or users with the notifynow\\_admin role. Users with all other roles get the message False when trying to run the function in a script.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Boolean|True if Notify is set up correctly, otherwise false.|\n\n```\nvar nn = new SNC.NotifyNow();\ngs.log(((nn.getReadyState()) ? \"OK\" : \"NOT OK\"));\n```\n\n## NotifyNow - getStatus\\(\\)\n\nReturns the current status of Notify configuration.\n\nThis method can only be accessed by administrators or users with the notifynow\\_admin role. Users with all other roles get the message Unauthorized when trying to run the function in a script.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nString\n\n\n\nOne of the possible status messages.\n
\n\nStatus\n\n\n\nDescription\n\n
\n\nNO\\_NUMBER\\_MESSAGE\n\n\n\nThe account does not have a telephone number set up. Ensure that you set up the telephone number for the account.\n\n
\n\nNO\\_ENDPOINTS\\_MESSAGE\n\n\n\nThe account does not have its endpoints set up correctly. Ensure that you set up the endpoints for the account.\n\n
\n\nACCOUNT\\_OK\\_MESSAGE\n\n\n\nThe account is active and ready for use.\n\n
\n\nACCOUNT\\_NO\\_AUTH\n\n\n\nThe Twilio AuthToken is not valid.\n\n
\n\nACCOUNT\\_NOT\\_CONFIGURED\n\n\n\nThe Twilio AccountSID or AuthToken is not valid.\n\n
\n\n
```\nvar nn = new SNC.NotifyNow();\ngs.log(nn.getStatus());\n```\n\n## NotifyNow - initiateConferenceCall\\(String\\[\\] conferenceCallParticipants, String conferenceCallTitle\\)\n\nInitiate a new conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|conferenceCallParticipants|String|One or more users, conference call participants, identified by the sys\\_ids from the sys\\_user table or E.164-compliant phone numbers.|\n|conferenceCallTitle|String|Title of the conference call. This parameter has a maximum length of 40 characters.|\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|The conference call record, or null if there was an error.|\n\nThis initiates a conference call with E.164-compliant phone numbers for participants, without the optional source record parameter and and does not send any conference call details via SMS or email.\n\n```\nvar participants = ['+31205655548', '+31205655552', '+31652825393'];\n// set up conference call\nvar nn = new SNC.NotifyNow();\nvar conferenceCall = nn.initiateConferenceCall(participants, \"testing12\");\ngs.log('started conference call: ' + conferenceCall.getUniqueValue());\n```\n\n## NotifyNow - initiateConferenceCall\\(String\\[\\] conferenceCallParticipants, String conferenceCallTitle, GlideRecord sourceRecord, Boolean private\\)\n\nInitiate a new conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|conferenceCallParticipants|String|One or more users, conference call participants, identified by the sys\\_ids from the sys\\_user table or E.164-compliant phone numbers.|\n|conferenceCallTitle|String|Title of the conference call. This parameter has a maximum length of 40 characters.|\n|sourceRecord|GlideRecord|Source record to associate to the conference call such as an incident or problem number.|\n|private|Boolean|Value to control if a conference call is private. This value defaults to false.|\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|The conference call record, or null if there was an error.|\n\nThis initiates a conference call with participants that have a E.164-compliant phone number and participants from the sys\\_user table and sends conference call details via SMS and email to all participants.\n\n```\n// define phone number participants\nvar participants = ['+31205655548', '+31205655552', '+31652825393'];\n \n// we also want to add two Dutch sys_user participants\nvar user = new GlideRecord('sys_user');\nuser.addNotNullQuery('mobile_phone');\nuser.addQuery('mobile_phone', 'STARTSWITH', '+316');\nuser.setLimit(2);\nuser.query();\n \n// add users to the participant array\nwhile (user.hasNext() && user.next()) {\n\tgs.log('adding user ' + user.getValue('name') + ' with phone number ' + \n user.getValue('mobile_phone') + ' to the participant array');\n\tparticipants.push(user.getUniqueValue());\n}\n \n// define a source record to associate with the conference call\nvar source = new GlideRecord(\"cmdb_ci\");\nsource.query(\"asset_tag\", \"P1000167\");\nif (source.hasNext() && source.next()) {\n\t// set up conference call\n\tvar nn = new SNC.NotifyNow();\n\tvar conferenceCall = nn.initiateConferenceCall(participants, \"testing 1 2\", source);\n \n\t// check if the conference call was successfully created\n\tif (conferenceCall != null) {\n\t\tgs.log('started conference call: ' + conferenceCall.getUniqueValue());\n\t} else {\n\t\tgs.log('could not start the conference call :(');\n\t}\n}\n```\n\n## NotifyNow - isCallable\\(String participant\\)\n\nDetermines whether a user is callable or not.\n\nA user must have a valid phone number to be callable. A user who is already in an active session is not callable.\n\n|Name|Type|Description|\n|----|----|-----------|\n|participant|String or GlideRecord|A sys\\_user or notifynow\\_participant record, or an E.164-compliant phone number.|\n\n|Type|Description|\n|----|-----------|\n|boolean|Whether this participant can be called or not.|\n\n```\nvar nn = new SNC.NotifyNow();\ngs.log('by number: ' + nn.isCallable('+31612345678'));\n \nvar user = GlideRecord('sys_user');\nuser.query('sys_id', '13d39544eb5201003cf587b9d106fea9');\nif (user.hasNext() && user.next())\n gs.log('by user: ' + nn.isCallable(user));\n \nvar participant = GlideRecord('notifynow_participant');\nparticipant.query('sys_id', '33b11430eb1201003cf587b9d106feb9');\nif (participant.hasNext() && participant.next())\n gs.log('by participant: ' + nn.isCallable(participant));\n```\n\n## NotifyNow - isSMSCapable\\(\\)\n\nChecks if the telephone number associated with the Twilio account is capable of sending SMS messages.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Boolean|Whether the telephone number associated with the Twilio account is capable of sending SMS messages.|\n\n```\ngs.log('The twilio number is SMS capable: ' + ((new SNC.NotifyNow().isSMSCapable()) ? 'yes' : 'no'));\n```\n\n## NotifyNow - isSMSCapable\\(String userID\\)\n\nChecks if a user is able to send SMS messages.\n\n|Name|Type|Description|\n|----|----|-----------|\n|userID|String|The sys\\_id of the user you want to check for an SMS-capable phone number.|\n\n|Type|Description|\n|----|-----------|\n|Boolean|If the user can send SMS messages.|\n\n```\ngs.log('the user is able to send SMS messages (e.g. has a SMS device): ' + ((new SNC.NotifyNow().isSMSCapable('')) ? \n 'yes' : 'no'));\n```\n\n## NotifyNow - isVoiceCapable\\(\\)\n\nChecks if the telephone number associated with the Twilio account is capable of setting up phone calls.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Boolean|Whether the telephone number associated with the Twilio account is capable of setting up phone calls.|\n\n```\ngs.log('the Twilio number is Voice capable: ' + ((new SNC.NotifyNow().isVoiceCapable()) ? 'yes' : 'no'));\n```\n\n## NotifyNow - isVoiceCapable\\(String userID\\)\n\nChecks if a user is able to make voice calls.\n\n|Name|Type|Description|\n|----|----|-----------|\n|userID|String|The sys\\_id of the user you want to check for a voice-call capable phone number.|\n\n|Type|Description|\n|----|-----------|\n|boolean|Whether the user has a voice-call capable phone number.|\n\n```\ngs.log('the user is able to send SMS messages (e.g. has a SMS device): ' + \n ((new SNC.NotifyNow().isVoiceCapable('someuserid')) ? 'yes' : 'no'));\n```\n\n## NotifyNow - kick\\(GlideRecord participant\\)\n\nRemoves a participant from a conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|participant|GlideRecord|The conference call participant to remove from the call.|\n\n|Type|Description|\n|----|-----------|\n|Boolean|True if the participant was removed, otherwise false.|\n\n```\nvar participantId = \"\";\nvar participant = new GlideRecord('notifynow_participant');\nparticipant.get(participantId);\nif (participant.isValid()) {\n // kick participant\n result = new SNC.NotifyNow().kick(participant);\n gs.log('participant kicked: ' + result);\n}\n```\n\n## NotifyNow - mute\\(GlideRecord participant\\)\n\nMutes a participant on a conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|participant|GlideRecord|The conference call participant to mute.|\n\n|Type|Description|\n|----|-----------|\n|Boolean|True if the participant was muted, otherwise false.|\n\n```\nvar participantId = \"\";\nvar participant = new GlideRecord('notifynow_participant');\nparticipant.get(participantId);\nif (participant.isValid()) {\n // mute participant\n result = new SNC.NotifyNow().mute(participant);\n gs.log('participant muted: ' + result);\n}\n```\n\n## NotifyNow - sendEmailQuestion\\(String emailAddress, String question, GlideRecord sourceRecord, String emailSubject\\)\n\nSend an email question to an email address.\n\nThe sendEmailQuestion method produces a question body and requires users to click a link to indicate their choice.\n\n|Name|Type|Description|\n|----|----|-----------|\n|emailAddress|String|Email address to send the question to.|\n|question|String or GlideRecord|The question record to send or the sys\\_id of a question record.|\n|sourceRecord|GlideRecord|An optional source record to associate to the SMS question, such as an incident.|\n|emailSubject|String|Optional text to override the default email subject.|\n\n|Type|Description|\n|----|-----------|\n|String|The conversation sys\\_id.|\n\nThis example demonstrates using the default email subject.\n\n```\nvar user = GlideRecord(\"sys_user\");\nuser.get(\"email\", \"someone@somedomain.com\");\n \nnew SNC.NotifyNow().sendEmailQuestion(user.getValue('email'), \"b6b34500bf3111003cf585ce2c0739ce\", user);\n```\n\nThis example uses dot-walking and specifies a source record and email subject.\n\n```\nnew SNC.NotifyNow().sendEmailQuestion(\"someone@somedomain.com\", \"b6071733bf1111003cf585ce2c07390f\", current, \n \"Please answer this question\");\n```\n\nThis example uses dot-walking and specifies an email subject but no source record.\n\n```\nnew SNC.NotifyNow().sendEmailQuestion(\"someone@somedomain.com\", \"b6071733bf1111003cf585ce2c07390f\", \n \"Please answer this question\");\n```\n\n## NotifyNow - sendSMS\\(String phoneNumber, String smsBody\\)\n\nSends an SMS message to an E.164-compliant mobile phone number.\n\nNotify supports international numbers. Using this method with a number that does not support sending SMS messages results in an error being logged.\n\n|Name|Type|Description|\n|----|----|-----------|\n|phoneNumber|String|The E.164-compliant phone number to send the message to.|\n|smsBody|String|The message to send, maximum 1600 characters.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nnew SNC.NotifyNow().sendSMS(\"+31612345678\", \"This is a message without source record\");\n```\n\n## NotifyNow - sendSMS\\(String phoneNumber, String smsBody, GlideRecord source\\)\n\nSends an SMS message to an E.164-compliant mobile phone number.\n\nNotify supports international numbers. Using this method with a number that does not support sending SMS messages results in an error being logged.\n\nSee also: [Advanced configuration for SMS](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/t_ConfigureNotifyforVoiceandSMS.md).\n\n|Name|Type|Description|\n|----|----|-----------|\n|phoneNumber|String|The E.164-compliant phone number to send the message to.|\n|smsBody|String|The message to send, maximum 1600 characters.|\n|source|GlideRecord|The source record to associate with this SMS message.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar source = new GlideRecord(\"my_table\");\nsource.query(\"my_field\", \"my_value\");\n\nif (source.hasNext() && source.next()) {\n // send a text message\n var nn = new SNC.NotifyNow();\n var message = \"this is just a test\";\n var number = \"+31612345678\";\n nn.sendSMS(number, message, source);\n}\n```\n\nThis example uses dot-walking and the current record as the source record.\n\n```\nnew SNC.NotifyNow().sendSMS(\"+31612345678\", \"this is a test\", current);\n```\n\n## NotifyNow - sendSMSQuestion\\(String phoneNumber, String question, GlideRecord sourceRecord\\)\n\nSends an SMS question.\n\n|Name|Type|Description|\n|----|----|-----------|\n|phoneNumber| |An E.164-compliant phone number to send the message to.|\n|question|String or GlideRecord|The question record to send or the sys\\_id of a question record.|\n|sourceRecord| |An optional source record to associate to the SMS question, such as an incident.|\n\n|Type|Description|\n|----|-----------|\n|String|The conversation sys\\_id, or null if the SMS was not sent successfully.|\n\n```\nvar question = new GlideRecord(\"notifynow_question\");\nquestion.query();\n \n// get the first question\nif (question.hasNext() && question.next()) {\n\t// send the sms question\n var number = \"+31612345678\";\n\tvar nn = new SNC.NotifyNow();\n\tnn.sendSMSQuestion(number, question.getUniqueValue(), current);\n}\n```\n\n## NotifyNow - umute\\(GlideRecord participant\\)\n\nUnmutes a participant on a conference call.\n\n|Name|Type|Description|\n|----|----|-----------|\n|participant|GlideRecord|The muted conference call participant to unmute.|\n\n|Type|Description|\n|----|-----------|\n|Boolean|True if the participant was unmuted, otherwise false.|\n\n```\nvar participantId = \"\";\nvar participant = new GlideRecord('notifynow_participant');\nparticipant.get(participantId);\nif (participant.isValid()) {\n // unmute participant\n result = new SNC.NotifyNow().unmute(participant);\n gs.log('participant unmuted: ' + result);\n}\n```\n\n"}}