How to Set Up Twilio Call Forwarding with ChatBotKit

In this tutorial you will build a Twilio voice agent that answers an incoming call, speaks with the caller, and forwards the active call to another phone number when the caller asks for a human, sales, support, or any other routed destination.

The forwarding step uses the twilio/call/route[by-id] ability. ChatBotKit handles the live call details for the agent, so the blueprint can focus on when and where to route the caller.

What You'll Build

• A ChatBotKit bot that answers Twilio voice calls
• A Twilio integration connected to that bot
• A skillset with a call forwarding ability
• A Twilio phone number webhook that sends calls into ChatBotKit
• An optional multi-destination routing blueprint for sales and support

Prerequisites

• A ChatBotKit account
• A Twilio account with a voice-capable phone number
• Your Twilio Account SID and Auth Token
• A destination phone number in international format, such as +14155550100
• About 15 minutes

How the Flow Works

1. A caller dials your Twilio number.
2. Twilio sends the call webhook to your ChatBotKit Twilio integration.
3. ChatBotKit starts a voice conversation using Twilio ConversationRelay.
4. When the caller asks to be transferred, the agent calls twilio/call/route[by-id].
5. ChatBotKit redirects the live call to the destination number.

Step 1: Create the Voice Forwarding Blueprint

Start by creating a blueprint with a bot, a skillset, one forwarding ability, and one Twilio integration.

1. Open Blueprints in ChatBotKit.
2. Click Create.
3. Name the blueprint "Twilio Call Forwarding".
4. Open the Designer.
5. Use the blueprint below as your starting point.

Click Build after adding the resources.

Step 2: Configure the Twilio Integration

After building the blueprint, open the Main Phone Line Twilio integration that the blueprint created.

Set these fields:

• Account SID: your Twilio account SID
• Auth Token: your Twilio auth token
• Bot: the front desk voice agent from the blueprint
• Voice: keep the generated setting or choose another language and voice

Save the integration.

Copy the Twilio integration ID from the integration URL. You will use it in the forwarding ability. It looks like this:

Step 3: Configure the Forwarding Ability

Open the Forward Active Call ability in the blueprint designer or skillset screen.

The ability has three parameters:

Keep callSid dynamic so the ability can route the current call. For the destination number, you can either leave it dynamic or hard-code your main forwarding number.

For a single forwarding destination, configure the ability like this:

Replace +14155550100 with your real destination number. The temporary #twilioIntegration:::main-phone-line reference is resolved by the blueprint import/build process.

Step 4: Point Your Twilio Number at ChatBotKit

In Twilio, open the phone number you want to use.

Under Voice Configuration, set the incoming call webhook:

Replace {twilioIntegrationId} with the ID of your ChatBotKit Twilio integration.

Use these settings:

• A call comes in: Webhook
• URL: the ChatBotKit webhook URL above
• HTTP method: POST

Save the Twilio phone number configuration.

Step 5: Test the Call

Call your Twilio number from a phone.

Try prompts like:

• "Can you connect me to someone?"
• "I need to speak with support."
• "Please transfer me to the office."

The agent should acknowledge the request, call the forwarding ability, and redirect the live call to the destination number.

Step 6: Route to Multiple Departments

If you want the agent to route callers to different teams, create one ability per destination. The agent can choose the right ability based on the caller's intent.

Then update the bot backstory:

Troubleshooting

The agent says it cannot find the call SID

Make sure the call is happening through the Twilio integration webhook. If you test the bot in a normal chat conversation, there is no active Twilio call to route.

The forwarding ability asks for the Twilio integration ID

Set twilioIntegrationId directly in the ability instruction after the blueprint is built, or make sure the bot has enough context to choose the correct integration ID. For most production phone lines, hard-coding the integration ID in the ability is the simplest option.

Twilio rejects the route request

Check that:

• The Twilio integration has a valid Account SID and Auth Token
• The destination number uses international format
• The call is still active when the ability runs
• The request is being made from the active Twilio voice conversation

The call forwards to the wrong person

If you use multiple routing abilities, keep each ability name and description specific. Names like Route to Sales and Route to Support help the agent select the right destination.

Next Steps

Once basic forwarding works, you can extend the blueprint:

• Add a dataset with office hours, policies, or FAQs
• Use one dynamic routing ability and let the agent choose the right number from its backstory, a dataset, an internal manual, a web page, or another trusted source
• Create separate fixed routing abilities for each team when you want tighter control over destinations
• Add a fallback SMS ability for missed calls
• Use allowFrom on the Twilio integration if only known callers should reach the agent
• Add contact collection so callers become trusted contacts in ChatBotKit