Conversation Intelligence quickstart

The following diagram illustrates the architecture of the quickstart application and how Conversation Intelligence works with TAC:

1
Phone call (PSTN)
2
  └── Twilio routes to /tac/twiml (Conversation Relay)
3

4
FastAPI Server (server.py)
5
  ├── /tac/*             → TAC VoiceChannel (Conversation Relay WebSocket)
6
  ├── /webhook/cintel    → receives Script Adherence + Summary results
7
  └── /api/events        → SSE stream to browser dashboard
8

9
TAC VoiceChannel
10
  └── Conversation Relay ↔ WebSocket ↔ TAC ↔ handle_message_ready()
11
                                             └── OpenAI GPT-4o (AI customer)
12

13
Twilio Conversation Intelligence
14
  ├── Script Adherence operator  → fires per utterance → /webhook/cintel → SSE checkpoint-update
15
  └── Summary operator           → fires on call end   → /webhook/cintel → SSE summary-update

When a call arrives, Twilio sends an HTTP request to the voice webhook on your TAC server. TAC responds with TwiML that includes a <ConversationRelay> verb with your Conversation Configuration ID:

1
<Response>
2
  <Connect>
3
    <ConversationRelay
4
      url="wss://your-domain.ngrok.io/ws"
5
      conversationConfiguration="conv_configuration_xxx" />
6
  </Connect>
7
</Response>

Twilio reads the conversationConfiguration attribute and automatically creates a Conversation in the Conversation Orchestrator, adds the caller as a participant, and opens a WebSocket connection to your server for the audio stream. From that point, Twilio handles transcription and streams each utterance to TAC over the WebSocket. TAC invokes your handle_message_ready callback with the transcribed text, and your response is sent back through the same WebSocket as synthesized speech. This means you never call the Conversations API directly. Passing the ID in TwiML is sufficient for Twilio to manage the entire conversation lifecycle.

This quickstart uses the following billable products in addition to Conversation Intelligence operator charges:

• Conversation Relay
• Inbound voice minutes
• Phone numbers

Learn more about Conversation Intelligence billing and Twilio Voice pricing.

Before you begin, complete the following prerequisites:

• Sign up for Twilio and buy a Twilio phone number with voice capabilities.
• Get an OpenAI API key for the conversational AI agent.
• Install Python 3.10+.
• Install uv.
• Install and set up ngrok.
• Install Git.

In a terminal, clone the quickstart application repository and navigate to the project directory:

1
git clone --branch feature/cintel-quickstart https://github.com/twilio/twilio-agent-connect-python.git
2
cd twilio-agent-connect-python

To start ngrok and create a tunnel to your localhost, run:

ngrok http 3340

The ngrok console displays your forwarding URL (for example, https://your-domain.ngrok.app or https://abc123.ngrok.app).

The TAC setup wizard provisions all required Twilio resources and configures your phone number automatically.

1. From the repo root, run:

make setup

2. In a browser, open http://localhost:8080.

3. Under Twilio Credentials, enter your Twilio credentials (API key SID, API key secret, Account SID, Auth token) and your Twilio phone number in E.164 format.

4. Under Memory Store, select a memory store. If you want to create a new one, click Create New and enter a Display name and Description for the memory store, then click Create.

5. Under Conversation Configuration, enter a Display name and Description.

6. Enter your ngrok domain (without https://) and OpenAI API key.

7. Under Profile Information, enter Email and Phone number.

8. Click Set Up Services.

   The wizard creates:

   • Memory store: Stores customer memory and conversation history
   • Conversation configuration: Captures inbound voice calls to your number and links to the memory store and intelligence configuration

9. Click Detect ngrok Tunnel.

10. Click Create Intelligence Configuration & Configure phone number.

    The wizard creates an Intelligence Configuration with two operators:

    • Script Adherence (trigger: on: COMMUNICATION): Evaluates agent speech against a preset support script in real-time. Sends results to https://<ngrok-domain>/webhook/cintel.
    • Summary (trigger: on: CONVERSATION_END): Generates a post-call summary. Sends results to the same webhook.

    The wizard also configures your Twilio phone number's voice webhook to https://<ngrok-domain>/tac/twiml so incoming calls are handled by the demo server.

When the wizard completes, it displays all required environment variable values. Copy them.

To configure the application, create a .env file in the getting_started/examples/cintel directory:

1
cd getting_started/examples/cintel
2
cp .env.example .env

Paste the setup wizard output into .env.

Install the demo application's Python dependencies, then start the local development server:

1
make install
2
make dev

Open http://localhost:3340. You'll see a dashboard with two panels:

• Live transcript
• Script checkpoints

Call the phone number shown in the dashboard banner. An AI customer (GPT-4o playing a frustrated internet subscriber) will answer. Follow the Owl Internet support script:

Watch the checkpoints turn green in real-time as you follow each step. After you hang up, the summary appears automatically in the right panel.

You can also view the operator results in Twilio Console.

1. In Twilio Console, go to Products & services > Conversation Intelligence > Intelligence configurations.
2. Select your configuration, then open the Conversations tab.
3. Click a conversation to view its operator results.

See the following common issues and resolutions.

1. Verify ngrok is running and TWILIO_TAC_VOICE_PUBLIC_DOMAIN in .env matches the current domain.
2. In Twilio Console, go to Develop > Troubleshoot > Debugger to see failed webhook deliveries to /webhook/cintel.
3. Go to Products & services > Conversation Intelligence. Click your configuration, then click the Conversations tab to confirm operators ran.

1. In .env, update TWILIO_TAC_VOICE_PUBLIC_DOMAIN.
2. Re-run the setup wizard to update both the Intelligence Configuration webhook URL and the phone number voice webhook.
3. To restart the server, run make dev.

1. In .env, verify OPENAI_API_KEY is valid (starts with sk-).
2. Check server logs for OpenAI errors.

• To build tailored analysis for your use case, create custom language operators.
• Learn how to integrate results with your application.
• Explore language operator results.
• Learn more about TAC.