Skip to main content

Twilio setup

Stellar integrates directly with Twilio to handle inbound voice calls with your AI agents. Twilio forwards calls to Stellar via a TwiML webhook, and Stellar streams audio in real time to power the conversation.

Prerequisites​

Twilio​

  • Twilio account with voice capabilities
  • One or more Twilio phone numbers
  • Admin access to the Twilio console

Stellar​

  • Agent configured and tested in Studio
  • Per-environment configuration set up (secrets, variables, auth connectors)

Setup​

Step 1: Create a phone connector in Studio​

  1. Navigate to Phone connectors in Studio
  2. Click Add connector
  3. Select Twilio as the type
  4. Choose which agent should handle calls
  5. Select the environment (Development, Staging, or Production)
  6. Choose the version mode:
    • Published: Always uses the latest published version
    • Draft: Uses the current draft version
    • Pinned: Uses a specific agent version
  7. Save the connector

The connector generates a webhook URL in the format:

https://platform.stellarcs.ai/v1/agents/{connector-identifier}/twilio-config

Step 2: Configure Twilio​

  1. Log in to the Twilio Console
  2. Navigate to Phone Numbers > Manage > Active Numbers
  3. Select the phone number to integrate
  4. Scroll to Voice Configuration
  5. Under A Call Comes In, select Webhook
  6. Enter the webhook URL from your Stellar connector
  7. Select HTTP GET as the method
  8. Click Save

To route multiple phone numbers, configure each number's webhook to point to the same connector, or create separate connectors for different agents, environments, or versions.

Step 3: Test the integration​

  1. Call your Twilio number
  2. Verify the AI agent answers
  3. Test the conversation flow and actions
  4. Trigger a handover and verify it completes
  5. Check that recordings and transcripts appear in Studio

Step 4: Go live​

  • Monitor the first production calls closely
  • Use listen & intervene if needed
  • Gradually increase call volume

Handover configuration​

Twilio handovers transfer calls to phone numbers:

  1. Go to your agent's Actions tab in Studio
  2. Create an action of type Handover
  3. Select handover type: Phone
  4. Enter the destination phone number with country code (e.g., +31201234567)

You can create multiple handover actions for different destinations (e.g., transfer_to_sales, transfer_to_support). The agent chooses the appropriate handover based on the conversation.

Twilio Studio integration​

You can use Twilio Studio for initial call routing before handing off to Stellar:

  1. Build an IVR flow in Twilio Studio (e.g., "Press 1 for sales, 2 for support")
  2. Route the selected option to the Stellar webhook URL
  3. Stellar's AI agent handles the conversation from there

Troubleshooting​

Calls not reaching Stellar​

  • Verify the webhook URL is correct in the Twilio console
  • Confirm the URL uses HTTPS and the method is HTTP POST
  • Check that the phone number is active in Twilio
  • Review error logs in the Twilio console

Audio quality issues​

  • Check network connectivity and bandwidth
  • Review Twilio's call quality metrics in the console
  • Contact Stellar support for diagnostics

Handover not working​

  • Verify the destination phone number format (include country code)
  • Confirm the destination number can receive calls
  • Check that outbound calling is enabled on your Twilio account
  • Test calling the handover number directly