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.

resources:
  '#bot:::front-desk-voice-agent':
    type: bot
    data:
      name: Front Desk Voice Agent
      description: Answers inbound Twilio calls and forwards callers when needed.
      backstory: |-
        You are a calm, concise front desk voice agent.

        You are speaking with a caller over the phone through Twilio.
        Keep responses short and natural to say out loud.

        Your job is to:
        - Greet the caller
        - Ask briefly how you can help
        - Answer simple questions when possible
        - Forward the active call when the caller asks for a person, sales,
          support, billing, or a transfer

        When you need to forward the call, use the Forward Active Call ability.

        Before forwarding, say a short phrase such as:
        "Sure, I will connect you now."
      model: claude-4.6-sonnet
      skillsetId: '#skillset:::call-routing-tools'
      privacy: false
      moderation: false
      visibility: private
      meta: null
  '#skillset:::call-routing-tools':
    type: skillset
    data:
      name: Call Routing Tools
      description: Tools that let the voice agent route live Twilio calls.
      visibility: private
      meta: null
  '#ability:::forward-active-call':
    type: ability
    data:
      skillsetId: '#skillset:::call-routing-tools'
      name: Forward Active Call
      description: >-
        Route the current live Twilio call to the configured destination
        phone number.
      instruction: |-
        template: twilio/call/route[by-id]
        parameters:
          twilioIntegrationId: '#twilioIntegration:::main-phone-line'
          callSid: $[callSid! ys|the current live call ID]
          to: $[to! ys|the destination phone number in international format, e.g. +14155550100]
      meta: null
  '#twilioIntegration:::main-phone-line':
    type: twilioIntegration
    data:
      name: Main Phone Line
      description: Inbound Twilio voice integration for the front desk agent.
      botId: '#bot:::front-desk-voice-agent'
      accountSid: ''
      authToken: ''
      voice: twilio/language=en-US/voice=Polly.Joanna
      contactCollection: true
      sessionDuration: 86400000
      allowFrom: '*'
      meta: null

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:

twilio_abc123...

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:

resources:
  '#ability:::forward-active-call':
    type: ability
    data:
      skillsetId: '#skillset:::call-routing-tools'
      name: Forward Active Call
      description: Forward the current Twilio call to the main office line.
      instruction: |-
        template: twilio/call/route[by-id]
        parameters:
          twilioIntegrationId: '#twilioIntegration:::main-phone-line'
          callSid: $[callSid! ys|the current live call ID]
          to: '+14155550100'
      meta: null

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:

https://api.chatbotkit.com/v1/integration/twilio/{twilioIntegrationId}/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.

resources:
  '#skillset:::department-routing-tools':
    type: skillset
    data:
      name: Department Routing Tools
      description: Routes callers to sales, support, or billing.
      visibility: private
      meta: null
  '#ability:::route-to-sales':
    type: ability
    data:
      skillsetId: '#skillset:::department-routing-tools'
      name: Route to Sales
      description: Forward the current Twilio call to the sales team.
      instruction: |-
        template: twilio/call/route[by-id]
        parameters:
          twilioIntegrationId: '#twilioIntegration:::main-phone-line'
          callSid: $[callSid! ys|the current live call ID]
          to: '+14155550101'
      meta: null
  '#ability:::route-to-support':
    type: ability
    data:
      skillsetId: '#skillset:::department-routing-tools'
      name: Route to Support
      description: Forward the current Twilio call to the support team.
      instruction: |-
        template: twilio/call/route[by-id]
        parameters:
          twilioIntegrationId: '#twilioIntegration:::main-phone-line'
          callSid: $[callSid! ys|the current live call ID]
          to: '+14155550102'
      meta: null
  '#ability:::route-to-billing':
    type: ability
    data:
      skillsetId: '#skillset:::department-routing-tools'
      name: Route to Billing
      description: Forward the current Twilio call to the billing team.
      instruction: |-
        template: twilio/call/route[by-id]
        parameters:
          twilioIntegrationId: '#twilioIntegration:::main-phone-line'
          callSid: $[callSid! ys|the current live call ID]
          to: '+14155550103'
      meta: null

Then update the bot backstory:

If the caller asks about pricing, quotes, or buying, route to sales.
If the caller has a product problem or needs help, route to support.
If the caller asks about invoices, payments, or refunds, route to billing.

Before routing, briefly confirm the destination:
"I can connect you with support now."

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