Nexmo Module Reference

Applies to

Bridge by Smartsheet

2FA Cancel Code

Cancel an active verification request.

2FA Cancel Code fields

  • Request Id: The Id of the request created by the 2FA Send Code module.

2FA Cancel Code Module

2FA Cancel Code returned data

  • Error Text
  • Status

2FA Check Code

Check the verification PIN code sent by 2FA Send Code module.

2FA Check Code fields

  • Name: The name of the module group in the designer.
  • Request Id: The Id of the request created by the 2FA Send Code module.
  • PIN Code: The PIN code sent to the user through SMS or Voice call.

2FA Check Code module group

Depending if the code returned by the user is valid or not the module will advance one of three state routes.

  • Valid: The code entered was valid.
  • Invalid: The code entered was invalid and there is no ability to try again.
  • Retry: The code entered was invalid but the user could try again.

2FA Junction Module Group

2FA Check Code returned data

  • Error Text
  • Status

2FA Send Code

Send a Verify PIN code to start the phone number verification process. This module returns a request Id that is used with the 2FA Check Code module.

2FA Send Code Fields

  • Number: The phone number that the PIN code is to be sent to. A phone number in international format, that is E.164, for example 447700900000.
  • Country: If you do not set a number in international format or you are not sure if the number is correctly formatted, you can set the two-character country code. For example, GB, US.
  • Brand: The name of the company or App you are using Verify for. This 18 character alphanumeric string is used in the body of Verify message. For example: Your BRAND code: 0000. Valid for 0 minutes.
  • Sender Id: An 11 character alphanumeric string to specify the SenderID for SMS sent by Verify. By default the sender id is VERIFY.
  • Code Length: The length of the PIN. Either 4 or 6 digit codes can be used.
  • Language: Use this parameter to explicitly set the language, accent, and gender used for the Verify request. The default value is en-us.
  • PIN Expiry: A value, in seconds, that represents the time the PIN remains valid. The value can be between 60 and 3600 seconds. The default value is 300. If Next Event Wait Time is specified then this value must be a multiple of the wait time, for example if the wait time is 60 then the PIN expiry could be 60,120,180 etc.
  • Next Event Wait Time: A value, in seconds, between 60 and 900 that specifies the wait time between attempts to deliver the PIN.

2FA Send Code

2FA Send Code returned data

  • Request ID
  • Status

JSON

{

    "request_id": "4a0135b97bb342b1b4c0ad455ec8303c",

    "status": "0"

}


Create Conference

Create a new conference call.

Create Conference fields

  • Record: State if you want to record the conference call.
  • Recording Options: Additional options when recording the conference call.
  • Format: The file format of the recording.
  • Workflow: The workflow that should be triggered to handle the recording. The recording data will be available in the trigger data.
  • States: State name and value to set on the workflow before it is invoked. This could be used to set details required for managing the recording such as who to send it to.

Create Conference fields

  • Has Moderator: State if the conference will have a moderator. A conference call with a moderator will not start until the moderator joins the call with the moderator_code.
  • Moderator Options: Additional options that are used when the conference uses a moderator.
  • Message: A message that is played to all the attendees waiting to join the conference call if the moderator has not already joined.
  • Music: A URL to an audio file that will be played to the attendees while they wait to join the conference call.
  • End on Exit: State if the conference call will end when the moderator exits. If this is not set then the call will end when the last attendee leaves.

Create Conference Recording fields

Create Conference returned data

  • Name
  • Code
  • Moderator Code

Delete Conference

Delete a conference call.

Conference calls will be deleted automatically after the call has been ended. This module is if you want to stop any new attendees from joining the conference call or to cancel it before it has started. It will not end a conference call that is currently in progress.

Delete Conference fields

  • Conference Code: The code of the conference you want to delete. This can be the attendee code or the moderator code.

Delete conference fields


Forward Call

Forward an existing call to another call endpoint.

Forward Call fields

  • Message: A message that will be played before the attempt to connect the call.
    • Message: The message that will be played to the user.
    • Voice: The voice that should be used when relaying the message. A complete list of the available voices can be found here.
    • Loop: The number of times the message will be repeated. The default value is 1. Set to 0 to loop infinitely.

Forward Call fields Message

  • From: The number of who the connecting call is from. If not set the active number will be used. This must be one of your Nexmo virtual numbers, another value will result in the caller ID being unknown.
  • Timeout: The length of time, in seconds, before the connection attempt will be cancelled.

Forward Call fields

  • Fallback Conversation: A workflow that will be triggered if the connection attempt fails, either due to timeout, failing, or being rejected by the endpoint.
    • Workflow: The workflow that will be invoked.
    • States: The names and values assigned to states when the workflow is invoked.
  • Machine Detection: State what should happen if Nexmo detects that it has connected to a machine, either Continue which will just continue with the call or Hangup which will end the call if a machine is detected.
  • Endpoint Type: The type of the endpoint that the call will be connected to, either Phone, Webhook, or SIP. 

forward call final fields


Join Conference

Have the current caller join a conference call.

Join Conference fields

  • Name: The name of the module group in the designer.
  • Conference Code: The code of the conference you want to join. This can be the attendee code or the moderator code.
  • Join Message: An optional message that will be played to the caller before they are connected to the conference call. This message will not be played if the user is waiting for the moderator and there is a moderator message.

Join conference fields

Join Conference module group

Depending on if the conference code is valid or not the conversation will continue down one of two paths.

  • Connected: If the code is valid and the user joins the conference call this state will be the next state. You will not be able to interact with the user over the call at this point.
  • Invalid: If the code is invalid this will be the next state. You can use this point to ask the user to confirm if they want to try again with a different code or perform other tasks.

Join Conference module group


Play Audio

Play an audio file over an existing call.

Play Audio fields

  • Send Media As: State how you want this stream to be treated, either as the next states question or as the current states answer.

The target states must have either a question or an answer in order for the module to be able to override the existing value.

  • Input Options: Optional input options that can be used to override the account defaults.
    • Timeout: The timeout, in seconds, for the user to make an input.
    • Submit On Hash: State if you want the users input to be sent on hash. If not set the users input will be sent after the timeout.
    • Max Digits: The number of digits the user can press. The maximum value is 20.

Play Audio Timeout fields

  • Stream URL: The URL for the source of the audio file.
  • Level: Set the audio level of the stream in the range -1 >=level<=1 with a precision of 0.1. The default value is 0.
  • Barge In: Set to true so this action is terminated when the user presses a button on the keypad.
  • Loop: The number of times audio is repeated before the Call is closed. The default value is 1. Set to 0 to loop infinitely.

Play Audio Fields


Record Call

Record a message at the end of a call.

This module will stop any more messages being sent to the current call, but the conversation flow will continue allowing you to manage the recording returned by the module

Record Call fields

  • Start Message: A message that is played before the recording is started. Use this to explain the recording, like if there will be a beep to start or if they are to press # to stop recording
    • Message: The message that will be played to the user.
    • Voice: The voice that should be used when relaying the message. A complete list of the available voices can be found here.
    • Loop: The number of times the message will be repeated. The default value is 1. Set to 0 to loop infinitely.

Record Call Start Message field

  • End Message: A message that is played after the user has stopped the recording.
    • Message: The message that will be played to the user.
    • Voice: The voice that should be used when relaying the message. A complete list of the available voices can be found here.
    • Loop: The number of times the message will be repeated. The default value is 1. Set to 0 to loop infinitely.

Record call end message fields

  • Format: The format of the recording audio file, either MP3 or WAV.
  • End On Silence: Stop recording after the specified number of seconds of silence. You can specify a value between 3 seconds and 10 seconds, inclusive. This will default to 3 seconds.
  • End On Key: Stop recording when a digit is pressed on the handset. Possible values are: * # or any single number e.g 9
  • Time Out: The maximum length of a recording in seconds. The range of possible values is between 3 seconds and 7200 seconds(2 hours).
  • Beep Start: Set to true to play a beep when a recording starts. This beep will also be audible in the recording.

Record Call general fields

 

Record Call returned data

  • Filename
  • Recording URL
  • Start Time
  • End Time
  • Length

Send Message

Send text as a voice message over Nexmo Voice channel.

Use this module if you want to have customized messages for the Nexmo Voice channel and use the default question or answer state fields for other channels

Send Message fields

  • Send Media As: State how you want this stream to be treated, either as the next states question or as the current states answer. Please note that the target states must have either a question or an answer in order for the module to be able to override the existing value.
  • Message: The message that is to be sent as a voice message.
  • Voice: The voice that should be used when relaying the message. A complete list of the available voices can be found here.
  • Barge In: State if the message can be interrupted by pressing a key.
  • Loop: The number of times the message will be repeated. The default value is 1. Set to 0 to loop infinitely.

Send Message voice fields

  • User Input Options: Options used to customise the user response input.
    • Timeout: The timeout, in seconds, for the user to make an input. Defaults to 3.
    • Submit On Hash: State if you want the users input to be sent on hash. If not set the users input will be sent after the timeout.
    • Max Digits: The number of digits the user can press. The maximum value is 20.

Send Message final fields


Send SMS

Send an SMS text message.

Send SMS fields

  • Message: The message that will be sent.
  • To: The number the SMS is sent to. A phone number in international format, that is E.164, for example 447700900000.
  • From: The number or name the SMS is sent from. A phone number in international format, that is E.164, for example 447700900000.

Send SMS

Send SMS returned data

  • Message Count
  • Messages
    • Message ID
    • Message Price
    • Network
    • Remaining Balance
    • Status
    • To

Start Call

Start an outgoing call with a specified endpoint.

Start Call fields

  • To: An array of one or more endpoints to start the call with. 
  • From Type: The type of the endpoint that the call will be started from, either Phone, Webhook, or SIP.
  • Conversation: The details of the workflow that will be triggered when the call is accepted.
    • Workflow: The workflow that will be invoked.
    • States: The names and values assigned to states when the workflow is invoked.

Start Call Conversation Fields

  • Machine Detection: State what should happen if Nexmo detects that it has connected to a machine, either Continue which will just continue with the call or Hangup which will end the call if a machine is detected.
  • Length Timer: Set the number of seconds that elapse before Nexmo hangs up after the call starts. The default value is 7200, two hours. This is also the maximum value.
  • Ringing Timer: Set the number of seconds that elapse before Nexmo hangs up after the call starts. The default value is 60, the maximum value is 120.

Call Endpoints

When connecting or starting a call there are multiple endpoint types that can be used.

Call Endpoint fields

  • Phone: The details if connecting to a phone number
    • Number: The number you will connect the call too
    • DTMF Answer: Set the digits that are sent to the user as soon as the call is answered. The * and # digits are respected. You create pauses using p. Each pause is 500ms.

Call Endpoints fields

 

  • Websocket: The details if connecting to a websocket.
    • URI: The URI to the websocket you are streaming to.
    • Content Type: The internet media type for the audio you are streaming. Currently, possible values are: audio/l16;rate=16000
  • Headers: Additional values sent as metadata.

Call Endpoints fields continued

  • SIP: Details if connecting to a SIP endpoint
    • URI: The SIP URI to the endpoint you are connecting to in the format sip:rebekka@sip.example.com.

Call Endpoints SIP fields