Troubleshooting

Issue: Unable to import TAC in your code.

The following are common causes:

• TAC not installed: The package hasn't been installed in your development environment.
• Wrong runtime environment: You're running the server with a different runtime than where TAC is installed (for example, system-level vs. project-level environment).
• Environment not activated: TAC was installed in an isolated environment (virtual environment, container, etc.) but that environment isn't active.
• PATH issues: The runtime executable you're using doesn't match the package manager that installed TAC.

Solution: Install TAC and its dependencies.

1
uv init
2
uv add twilio-agent-connect[server]

1
python -m venv .venv
2
source .venv/bin/activate
3
pip install twilio-agent-connect[server]

npm install twilio-agent-connect

Issue: Your application crashes with configuration errors.

Solution: Create a .env file with all required environment variables. See Configure environment variables for the complete list.

1
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
2
TWILIO_AUTH_TOKEN=your_auth_token
3
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4
TWILIO_API_SECRET=your_api_key_secret
5
TWILIO_PHONE_NUMBER=+1234567890
6
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxx

1
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
2
TWILIO_AUTH_TOKEN=your_auth_token
3
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4
TWILIO_API_SECRET=your_api_key_secret
5
TWILIO_PHONE_NUMBER=+1234567890
6
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxx

Issue: Your server is running, but SMS webhooks are not arriving.

Common causes:

• Twilio phone number is not added to the Conversations service.
• Webhook URL is not set up in the Conversations service.
• Local server doesn't have the correct webhook URL configured in the Conversations service.

Solution:

• Add your phone number to the Conversations service (if not already added).

• Set the webhook URL in the Conversations service:

  Copy code block

  https://your-ngrok-domain/webhook

Issue: Not receiving webhook events from Twilio when you text or call your Twilio number.

Common cause: Your local development server isn't publicly accessible from the internet.

Solution (for local development):

Use ngrok to expose your local server. See Expose your local server with ngrok for setup instructions.

1
# Start your server first, then in a new terminal:
2
ngrok http 8000

Update the Twilio Console with your ngrok URL:

https://your-ngrok-domain.ngrok.app/webhook

Issue: Calls to your Twilio number don't connect or drop immediately.

Solution: Check TwiML URL configuration.

Verify voice webhook configuration:

1. Log in to Twilio Console.
2. Navigate to Numbers and Senders.
3. Select your phone number.
4. Go to Configuration details.
5. Click Edit details in Voice Configuration.
6. Select Webhook as the method to configure your voice calls.
7. Verify that your webhook URL is set correctly and that the HTTP method is set to POST.

Correct webhook URL format:

https://your-ngrok-domain/twiml

Webhook configuration checklist:

• URL starts with https:// and not http://.
• URL ends with the /twiml endpoint path.
• HTTP method is set to POST.

Issue: The memory response in your callback is None (Python) or undefined (TypeScript).

Common causes:

• Conversation Memory is not configured for your account.
• Memory retrieval is not turned on in your channel configuration.
• No profile exists for the caller's phone number in Conversation Memory.

Solution:

Issue: Your custom tools are defined but the LLM never calls them.

Common causes:

• The tools are not included in the LLM request.
• The tool descriptions are unclear or don't match the conversation context.

Solution:

• Verify that you're passing the tools to your LLM's API request (for example, in the tools parameter for OpenAI).
• Write clear, specific tool descriptions that help the LLM understand when to use each tool.
• Test by explicitly asking your agent to perform the action the tool handles.

Issue: The LLM calls the handoff tool but the call doesn't route to your Studio Flow.

Common causes:

• TWILIO_STUDIO_HANDOFF_FLOW_SID is not set in your environment.
• The Studio Flow SID is incorrect or the flow is not published.
• The handoff tool is not created with the correct tac and session arguments.

Solution:

• Verify that TWILIO_STUDIO_HANDOFF_FLOW_SID is set in your .env file and starts with FW.
• Confirm the Studio Flow is published and active.
• Check that you're passing both the tac instance and the current context session to the tool factory:

1
from tac.tools import create_studio_handoff_tool
2

3
handoff_tool = create_studio_handoff_tool(tac, context)

Issue: After a voice handoff to Flex, each message appears twice in the conversation thread.

Cause: Your Conversation Configuration has Voice captureRules enabled alongside TAC's Conversation Relay. Both paths hydrate the same conversation, resulting in duplicate messages.

Solution: Remove Voice captureRules from your Conversation Configuration when using TAC with Conversation Relay. TAC handles voice conversation hydration through Conversation Relay automatically.