Use Twilio verification system

In this task, you’ll need to complete the following tasks:

Activate Twilio Verify Service.
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.

Where is the step ID

Where is the form field ID

Where is the workflow ID

Make sure you know how to use data references. See Data references.

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

Sign in to Twilio as an administrator.
Go to Explore Products.
In All products, scroll to the Account security section.
Click Verify.
Go to Verify > Services.
In the list of existing services, click the + icon. This will create a new service.
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:

Create the verification workflow (if not previously created).
Set up the verification workflow.
Add the verification process trigger in the main workflow.
Set up the verification trigger steps.

Create the verification sub-process

Detailed steps

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.
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.

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"
}

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}

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.
Save your changes.

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)

Save your changes.
Create a form step 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.
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)}"
      }
    }
  ]
}

Save your changes.
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.
Save your condition.
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"
}

Click Add conditions to create your condition for step 12.
Create a form step with a field for the user to enter the verification code. Assign this step to the external user.

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.

Save your changes.
Click Add conditions, and create a condition for step 15 to run when step 14 didn’t contain the NOTRECEIVED input.
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).

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
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)

The next 2 steps are conditional steps informing the main workflow of a verification failure or success.

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)}"
      }
    }
  ]
}

Click Add conditions to add the conditions to the step to run when verification was not successful:
Click … in the left-hand process panel and select Make non-blocking.
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"
      }
    }
  ]
}

Click Add conditions to add the conditions to the step to run when the verification was successful.

Click … in the left-hand workflow panel and select Make non-blocking.

Create the main workflow

Detailed steps

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" }

Create the following variables:

Name	Value
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

Save your changes.
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
        }
     }
  ]}

Save your changes.
Create a radio form field step with the following details as radio items:
- Successful
- Max send attempts reached
- Challenge expired
Create a routing step with the following condition to run when verification has reached the send attempts limit.

The step should have the option to confirm and continue or return to step 2.
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.

Overview

API

No-code

Custom integrations

Before you begin

Activate Twilio Verify Service

Configure the Next Matter integration

Create the verification sub-process

Create the main workflow

Overview

API

No-code

Custom integrations

​Before you begin

​Activate Twilio Verify Service

​Configure the Next Matter integration

​Create the verification sub-process

​Create the main workflow

Before you begin

Activate Twilio Verify Service

Configure the Next Matter integration

Create the verification sub-process

Create the main workflow