In this task, you’ll need to complete the following tasks:
  1. Activate Twilio Verify Service.
  2. Configure the Next Matter integration (the main workflow and the sub-workflow).

​
Before you begin

  • Have your Twilio API key at hand. If you don’t have it, read how to generate it.
  • Make sure you know where to find step ID, form field ID, and process ID in Next Matter.
  1. In your left-hand navigation, click the Workflows icon.
  2. Hover over the follow-up workflow and click on the menu icon.
  3. Click Edit workflow.
  4. Click the step to which you’d like to send data.
  5. Copy the step ID. It’s the last number in the URL you see in your browser.
Image of the Next Matter URL with the step ID highlighted
  1. In your left-hand navigation, click the Workflows icon.
  2. Hover over the follow-up process and click on the menu icon.
  3. Click Edit workflow.
  4. Click the step to which you’d like to send data.
  5. Click the ID icon for the field to which you want to copy data.
  6. Copy Form field ID.
An image of a step with the highlighted form fields ID
You can get the ID by clicking the follow-up workflow and copying the number from the URL in your browser.
Image of the Next Matter URL with the workflow ID highlighted
Good to know: Check out our ready-made templates available when you add a step and select Templates > 3rd party templates. You can use the templates to create a set of pre-configured steps. Need a specific template? Click the Contact us button in the top right of the page and let us know.

​
Activate Twilio Verify Service

  1. Sign in to Twilio as an administrator.
  2. Go to Explore Products.
  3. In All products, scroll to the Account security section.
  4. Click Verify.
  5. Go to Verify > Services.
  6. In the list of existing services, click the + icon. This will create a new service.
  7. Give the service a name and copy the SID. You will need it in the Next Matter process.

​
Configure the Next Matter integration

The OTP SMS Verification requires two workflows. One is the main process that you want to integrate with Twilio, and the other is a helper workflow that does the verification. The main process triggers the verification workflow.
The verification workflow can be used by more than one workflow. There is no need to create a separate verification workflow each time you create a new workflow.
To configure the integration, you’ll need to do the following:
  1. Create the verification workflow (if not previously created).
  2. Set up the verification workflow.
  3. Add the verification process trigger in the main workflow.
  4. Set up the verification trigger steps.

​
Create the verification sub-process

  1. Open your workflow and add a new form step right with the data you want to collect. For example, click + Add Form field and select Short Text -Input if you want to collect the user’s surname.
  2. To send the email to the user with the step to collect the data, you can create a custom integration step that will use Sendgrid integration. See how to configure Sendgrid.
  3. Configure the Sendgrid email step with the following data:
    • Method: POST
    • URL: https://api.sendgrid.com/v3/mail/send
    • Headers: Content-Type: application/json
    • Headers: Authorization: Bearer SENDGRID_ENCODED_API_KEY
    • Body might look like the following:
    JSON
    {
  "from": {
    "email": "service@[company-domain].com",
    "name": "Next Matter Notifications"
  },
  "personalizations": [{
    "to": [{
      "email": "{81. Provide details - Customer email - Input (plain)} "
    }],
    "dynamic_template_data": {
      "email-subject": "Your sandbox credentials are ready!",
      "email-content": "Hi {81. Provide details - Customer name - Input (plain)}, 
      <br><br>Setup for your sandbox has been completed and your credentials are ready. 
      Please provide your input here 
      <a href='{83. Verification Instructions - Public URL}'>with this secure form</a> 
      of where you want to get the following notifications and the SMS two-factor authentication."
    }
  }],
  "template_id": "d-1aa0b4cd59214c18924a28c96ed78f7f"
}
  4. Create a step that’s an instruction assigned to the external user. The user will see these instructions when they click the public link that’s provided in the email. Click Settings and enter the following in the Instruction field: 
    Click the Complete button, once you are ready to do the 2-Factor Authentification. 
Go to this page immediately and 
enter the code that you have received on your phone 
(will only work once you Click Complete): {89. Verify yourself - Public URL}
  5. Create a new step that’s Integration > Custom integration. This step will send a request to Twilio to send a code to the user’s phone. Enter the following in the step’s Settings:
    • Method: POST
    • URL: https://verify.twilio.com/v2/Services/TWILIO_VERIFY_SERVICE_SID/Verifications
    • Headers: Content-Type: application/x-www-form-urlencoded
    • Headers: Authorization: Basic TWILIO_ENCODED_API_KEY
    • Body might look like the following:
    To=%2B{81. Provide details - Phone number.  (Note: please include 1 before the area code.) - Input (plain)}&Channel=sms
    • Select to skip this step on failure.
    • Click + Add variable and create an error_message variable with the value of $.message and a status variable with the value of $.status.
  6. Save your changes.
  7. Click + Add step and select the step to be Integration > Custom integration. This step will automatically complete the verification process and send data to the main workflow. Enter the following in the step’s Settings:
    • Method: POST
    • URL: https://core.nextmatter.com/api/instances/{InstanceID}/complete_step/
    • Headers: Content-Type: application/json
    • Headers: Authorization: Api-Key NEXT_MATTER_API_KEY
    • Body might look like the following:
    {
  "step_id": "STEP_ID",
  "actions": [
    {
      "action_id": "ACTION_ID1",
      "input_object": {
        "radioItemSelected": "{84. Send Text - Integration step - status (plain)}"
      }
    },
    {
      "action_id": "ACTION_ID2",
      "input_object": {
        "radioItemSelected": "{84. Send Text - Integration step - error_message (plain)}"
      }
    },
    {
      "action_id": "ACTION_ID3",
      "input_object": {}
    }
  ]
}
    Note: Make sure to make the step non-blocking (… > Make non-blocking)
  8. Save your changes.
  9. Create a form step allowing internal users to verify if Twilio reported any error messages.
    Image of the form with a form field allowing internal users to verify if Twilio reported any error messages
    The next 4 steps below verify if the code entered by the user is correct.
  10. Create an integration step to inform the main process that the verification failed. Enter the following in the step’s Settings:
  • Method: POST
  • URL: https://core.nextmatter.com/api/instances/{2. Provide details - Output instance id - Input}/complete_step/
  • Headers: Content-Type: application/json
  • Headers: Authorization: API Key NEXT_MATTER_API_KEY
  • Body might look like the following:
{
  "step_id": "{2. Provide details - Target outcome of check step - Input (plain)}",
  "actions": [
    {
      "action_id": "{2. Provide details - Action ID of Radio Button - Input (plain)}",
      "input_object": {
        "radioItemSelected": "{5. Send Text - Integration step - error_message (plain)}"
      }
    }
  ]
}
  1. Save your changes.
  2. This step is conditional and is only triggered if the verification status is canceled. Click Add condition, and specify that the step should only be triggered if the previous step didn’t contain the pending status. A popup allowing users to add a condition to a step
  3. Save your condition.
  4. Create another Sendgrid integration step with a condition for when the status is pending. In this case, you want another email to be sent out to the user to complete the verification. Use the setting details from step 3, however, consider changing the Body to the following:
{
  "from": {
    "email": "service@[company-domain].com",
    "name": "Verify by Next Matter"
  },
  "personalizations": [{
    "to": [{
      "email": "{2. Provide details - Customer email - Input (plain)}"
    }],
    "dynamic_template_data": {
      "email-subject": "2 Factor Verification",
      "email-content": "Please provide your access token with <a href='{10. Verify yourself - Public URL}'> this secure link</a>. Never share your token with anyone."
    }
  }],
  "template_id": "d-1aa0b4cd59214c18924a28c96ed78f7f"
}
  1. Click Add conditions to create your condition for step 12.
  2. Create a form step with a field for the user to enter the verification code. Assign this step to the external user.
Image of the conditions pop-up
  1. Create an integration step for Twilio to verify the provided code. Click the Settings gear icon to configure the step:
  • Method: POST
  • URL: https://verify.twilio.com/v2/Services/TWILIO_VERIFY_SERVICE_SID/VerificationCheck
  • Headers: Content-Type: application/x-www-form-urlencoded
  • Headers: Authorization: Basic TWILIO_ENCODED_API_KEY
  • Body might look like the following:
To=%2B{2. Provide details - Phone number.  (Note: please include 1 before the area code.) - Input (plain)}&Code={10. Verify yourself - Please enter the code that you have received on your device. Your code is valid for 10 minutes.  This is automatically blocked after 5 failed attempts. Write NOTRECEIVED if you didn't receive the code. - Input (plain)}
  • Select to skip this step on failure.
  • Click + Add variable and create an error_message variable with the value of $.message and an isOTPvalid variable with the value of $.status.
  1. Save your changes.
  2. Click Add conditions, and create a condition for step 15 to run when step 14 didn’t contain the NOTRECEIVED input.
  3. Create a form step with the field to show the verification result (and any errors Twilio might have sent). Add a condition to this step to run if the verification step (step 10 was successfully completed).
Image of the form step with a fields asking to specify the verification result
  1. Create a step with a routing form field to verify how to proceed in case of verification errors. The step can go back to the step to re-send the code, but in the case of a wrong number can be modified. You can add the following description for the user: OTP code entered was not valid. Please select how to proceed. Consider that ‘Return to 2. Send OTP’ option will send the same code again to allow another attempt. After 5 attempts, the system gets blocked. The step should have the following options:
    • Confirm and continue
    • Return to the Provide details step
    • Decline and stop workflow
  2. Click Add conditions to create the conditions for the step to run in the case the verification was not successful (code was not received, got stuck on send, or was not approved)
Image of multiple configured conditons
The next 2 steps are conditional steps informing the main workflow of a verification failure or success.
  1. Create an integration step to inform the main workflow of verification failure. Click the Settings gear icon to configure the step:
  • Method: POST
  • URL: https://core.nextmatter.com/api/instances/{2. Provide details - Output instance id - Input}/complete_step/
  • Headers: Content-Type: application/json
  • Headers: Authorization: API-Key NEXTMATTER_API_KEY
  • Body might look like the following:
{
  "step_id": "{2. Provide details - Target outcome of check step - Input (plain)}",
  "actions": [
    {
      "action_id": "{2. Provide details - Action ID of Radio Button - Input (plain)}",
      "input_object": {
        "radioItemSelected": "{11. Verify Code - Integration step - error_message (plain)}"
      }
    }
  ]
}
  1. Click Add conditions to add the conditions to the step to run when verification was not successful: Image of the conditions pop-up showing conditions to run the step when verification was not successful
  2. Click … in the left-hand process panel and select Make non-blocking.
  3. Create an integration step to inform the main workflow of verification failure. Click the Settings gear icon to configure the step:
  • Method: POST
  • URL: https://core.nextmatter.com/api/instances/{2. Provide details - Output instance id - Input}/complete_step/
  • Headers: Content-Type: application/json
  • Headers: Authorization: API-Key NEXTMATTER_API_KEY
  • Body might look like the following:
{
  "step_id": "{2. Provide details - Target outcome of check step - Input (plain)}",
  "actions": [
    {
      "action_id": "{2. Provide details - Action ID of Radio Button - Input (plain)}",
      "input_object": {
        "radioItemSelected": "Successful"
      }
    }
  ]
}
  1. Click Add conditions to add the conditions to the step to run when the verification was successful.
Image of the condition pop-up with the configuration to run when the verification was successful
  1. Click … in the left-hand workflow panel and select Make non-blocking.

​
Create the main workflow

  1. Create an integration step to launch verification. In this step, you’ll be calling the Next Matter API to launch the subworkflow. Click the Settings gear icon to configure the step:
    • Method: POST
    • URL: https://core.nextmatter.com/api/instances/
    • Headers: Content-Type: application/json
    • Headers:: Authorization: API-Key NEXTMATTER_API_KEY
    • Body might look like the following:
      JSON
      {
    "process": "https://core.nextmatter.com/api/processes/VERIFICATION_WORKFLOW_ID/",//this is the ID of the sub-workflow described above
    "name": "{Instance name}-Verification"
}
  2. Create the following variables:
    NameValue
    id$.id
    url$.url
    step_id$.process_snapshot.steps[0].id
    name_aid$.process_snapshot.steps[0].actions[0].id
    email_aid$.process_snapshot.steps[0].actions[1].id
    phone_aid$.process_snapshot.steps[0].actions[2].id
    instance_aid$.process_snapshot.steps[0].actions[3].id
    step_aid$.process_snapshot.steps[0].actions[4].id
    action_aid$.process_snapshot.steps[0].actions[5].id
  3. Save your changes.
  4. Create a step to send the details to the verification sub-workflow. Again, you’ll be calling Next Matter API. Click the Settings gear icon to configure the details:
    • Method: POST
    • URL: https://core.nextmatter.com/api/instances/{2. Launch OTP SMS Verification - Launch workflow automatically - id (plain)}/complete_step/
    • Headers: Content-Type: application/json
    • Headers:: Authorization: API-Key NEXTMATTER_API_KEY
    • Body might look like the following: Note that the data in are data references.
JSON
      {"step_id":{2. Launch OTP SMS Verification - Launch process automatically - step_id (plain)}
  ,"actions":[
    {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - name_aid (plain)},
      "input_object":{
                 "inputValue":"{2. Launch OTP SMS Verification - Launch process automatically - name_aid (plain)}"}}, 
  {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - email_aid (plain)},
      "input_object":{
                 "inputValue":"{2. Launch OTP SMS Verification - Launch process automatically - email_aid (plain)}"}}, 
  {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - phone_aid (plain)},
      "input_object":{
                 "inputValue":"{2. Launch OTP SMS Verification - Launch process automatically - phone_aid (plain)}"
        }},  
  {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - instance_aid (plain)},
      "input_object":{
                 "inputValue":"{Instance ID}"
        }},  
  {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - step_aid (plain)},
      "input_object":{
                 "inputValue":"RESULT_STEP_ID"// this is a placeholder for the step ID of the next step
        }},  
  {
      "action_id":{2. Launch OTP SMS Verification - Launch process automatically - action_aid (plain)},
      "input_object":{
                 "inputValue":"RESULT_ACTION_ID"// this is a placeholder for the action ID from the next step
        }
     }
  ]}
  1. Save your changes.
  2. Create a radio form field step with the following details as radio items:
    • Successful
    • Max send attempts reached
    • Challenge expired
    Image of the radio form filed with 3 radio items configured
  3. Create a routing step with the following condition to run when verification has reached the send attempts limit.
    Image of the condition for the step to run when step 4 of the workflow has a maximum send attempts reached
    The step should have the option to confirm and continue or return to step 2.
  4. Create a form step with the field to share data with the verified user. Make sure you create the condition for this step to run when user verification has been successful.
    Image of the condition for the step to run when user verification has been successful