Use Twilio verification system
Connect Next Matter and Twilio to use the One-Time-Password SMS Verification.
In this task, you’ll need to complete the following tasks:
To configure the integration, you’ll need to do the following:
The next 2 steps are conditional steps informing the main workflow of a verification failure or success.
- 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 step ID
- In your left-hand navigation, click the Workflows icon.
- Hover over the follow-up workflow and click on the menu icon.
- Click Edit workflow.
- Click the step to which you’d like to send data.
- Copy the step ID. It’s the last number in the URL you see in your browser.
Where is the form field ID
Where is the form field ID
- In your left-hand navigation, click the Workflows icon.
- Hover over the follow-up process and click on the menu icon.
- Click Edit workflow.
- Click the step to which you’d like to send data.
- Click the ID icon for the field to which you want to copy data.
- Copy Form field ID.
Where is the workflow ID
Where is the workflow ID
You can get the ID by clicking the follow-up workflow and copying the number from the URL in your browser.
- 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.
- 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
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 -
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:
-
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:
- Select to skip this step on failure.
- Click + Add variable and create an
error_messagevariable with the value of$.messageand astatusvariable 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:
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:
- 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:
- 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:
- Select to skip this step on failure.
- Click + Add variable and create an
error_messagevariable with the value of$.messageand anisOTPvalidvariable 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)
- 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:
- 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:
- 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
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
-
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
- 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.
