Objective

This article explains how to block unwanted or spam calls in Twilio Studio Flow using a Twilio Function as a blocklist checker. By following these steps, you will be able to reject calls from specific phone numbers before they are answered, preventing any charges from being incurred and avoiding signals to spam bots that your line is active.

Product

Twilio Studio, Twilio Functions, TwiML Bins

Environment

Twilio Console

User Account Permission/Role(s) Required 

Administrator or Developer access to the Twilio Console.

Procedure 

Step 1: Create the Blocklist Function

1. In the Twilio Console, go to Functions > Services and click Create Service.
2. Give the service a name (for example, blocklist-checker) and click Next.
3. Click Add Function and set the function path (for example, /check-blocklist).
4. Replace the default code with the following:

exports.handler = function(context, event, callback) {
  const blockedNumbers = ['+10000000000']; // Add blocked numbers here
  const rawCallerId = event.From || event.Called || '';
  const callerId = rawCallerId.trim();
  if (blockedNumbers.includes(callerId)) {
    return callback(null, { blocked: true });
  }
  return callback(null, { blocked: false });
};

Add one phone number per entry in the blockedNumbers array, using E.164 format (for example, +13123456789).

5. Click Save, then click Deploy All. Wait for the deployment to complete before moving to the next step.

Step 2: Create a TwiML Bin to Reject Blocked Calls

1. In the Twilio Console, go to Explore Products > TwiML Bins and click the + button to create a new TwiML Bin.
2. Give it a descriptive name (for example, Reject Spam).
3. Replace the default content with the following:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject reason="busy" />
</Response>

Using <Reject reason="busy" /> ensures the call is dropped before it is answered, so no charges are incurred and the line does not appear active to automated spam systems.

4. Click Save and copy the TwiML Bin URL.

Step 3: Configure the Studio Flow

1. Open your Studio Flow in the Twilio Console.
2. Connect the Trigger (Incoming Call) transition to a Run Function widget.
3. In the Run Function widget:

• Select the Function Service and Function path you created in Step 1.
• Under Function Parameters, click Add Parameter and set:
• Key: From
• Value: {{contact.channel.address}}

This parameter explicitly passes the caller's phone number to the Function. Without it, the Function will not receive the caller's number and will return blocked: false for every call.

4. Click Save.

Step 4: Add a Split Based On Widget

1. Connect the Run Function widget's Success transition to a Split Based On widget.
2. Set the Variable to Test field to:

{{widgets.<run_function_widget_name>.parsed.blocked}}

Replace <run_function_widget_name> with the actual name of your Run Function widget.

3. Add the following two conditions (click Save after each one):

• Condition 1 — Blocked: Operand: Equal To | Value: true | Transition To: the Add TwiML Redirect widget pointing to the TwiML Bin URL from Step 2.
• Condition 2 — Not Blocked: Operand: Equal To | Value: false | Transition To: your normal call flow.

4. Connect the No Condition Matches (noMatch) transition to your normal call flow as well, to ensure legitimate calls are never accidentally blocked due to unexpected function responses.

Step 5: Configure the TwiML Redirect Widget

1. Add an Add TwiML Redirect widget and connect it to the true branch of the Split Based On widget.
2. Set the URL field to the TwiML Bin URL copied in Step 2.
3. Set the Timeout field to 30 seconds. This ensures the Flow execution ends automatically after the call is rejected, preventing the execution from remaining open indefinitely.
4. Click Save.

Step 6: Publish and Test

1. Click Publish to deploy your Studio Flow.
2. Make a test call from a blocked number and verify that:

• The call receives a busy signal and is not answered.
• No charges appear for the blocked call in your Twilio account.

3. Make a test call from a non-blocked number and verify that it reaches your normal call flow.

Additional Information 

• To add more numbers to the blocklist, edit the blockedNumbers array in the Function, then click Save and Deploy All again. For example: const blockedNumbers = ['+10000000000', '1234567891'];

Below you will find references to useful documents:

• Reject Incoming Calls with a Phone Number Block List
• Twilio Functions
• TwiML Bins
• Studio | Run Function Widget
• Studio | twiML Redirect Widget