Quickstart
This quickstart runs the bundled examples from the TAC repositories to connect an AI agent (built with OpenAI) to Twilio's SMS and Voice channels. TAC supports Python and TypeScript — choose the language that fits your development environment.
You'll build a customer service agent that can:
- Respond to customers through SMS and Voice
- Retrieve customer context and conversation history by using Twilio Conversation Memory
- Provide personalized responses based on customer profile
Before you begin, gather the following information from the Console:
| Credential | Where to find it |
|---|---|
| Twilio Account SID | In the Console Dashboard. Starts with AC. |
| Twilio Auth Token | In the Console, go to Develop > API Key & creds > API Keys & auth tokens, go to the Auth Tokens tab. Click to reveal your Primary auth token. |
| API Key SID | In the Console, go to Develop > API Key & creds > API Keys & auth tokens, go to the API Keys tab. Click Create API Key and create a standard API key. Copy and store your SID (starts with SK) and Client secret. |
| API Key Secret | Shown once when creating the API key. Save it securely. |
| Twilio Phone Number | In the Console, go to Products & services > Numbers & senders > Numbers & senders. |
You'll also need:
- Ngrok domain: A public URL for webhooks, for example, your-app.ngrok.app.
- OpenAI API key: Required for the OpenAI agent used in this quickstart. You can obtain an API key from the OpenAI Console.
- Python 3.10+ or Node.js 22.13.0+: Depending on your chosen language.
This quickstart uses the bundled examples from the TAC repository. For your own projects, install the SDK directly from the package registry — see Add TAC to your agent for pip/npm installation instructions.
-
Clone the TAC repository and navigate to it:
1git clone https://github.com/twilio/twilio-agent-connect-python.git2cd twilio-agent-connect-python -
Install
uv, a Python package manager. See the uv installation guide for instructions.1# macOS/Linux2curl -sSL https://install.astral.sh | sh3# or with Homebrew (macOS)4brew install uv5# or with pip6pip install uv -
Install dependencies:
make sync
Twilio needs a public URL to send webhooks to your local server. In the next step, you'll configure your environment with your ngrok domain, so start ngrok first.
Choose one of the following options based on your ngrok plan:
-
Start ngrok:
ngrok http 8000 -
Ngrok generates a random URL (for example,
https://abc123xyz.ngrok.app). Copy the domain from the ngrok terminal output (for example,abc123xyz.ngrok.app).
Info
Each time you restart ngrok on a free plan, it generates a new URL. You'll need to update the ngrok domain in your .env file and in the Console webhook configuration after each restart.
If you have a paid ngrok plan with a static domain, you can use the same URL every time:
-
Start ngrok with your static domain:
ngrok http --url=your-static-domain.ngrok.app 8000 -
With a static domain, you won't need to update your configuration when you restart ngrok.
Note: For production use, replace ngrok with your own custom domain.
Info
Both SDKs use the same environment variable for the ngrok domain:
Set TWILIO_VOICE_PUBLIC_DOMAIN to the domain only, without https:// (for example, abc123xyz.ngrok.app). The SDK prepends the protocol automatically.
The Python SDK includes a setup wizard that creates the required Twilio services and generates your environment variables.
-
In a new terminal window (keep ngrok running), start the setup wizard from the repository root:
make setup -
Open
http://localhost:8080in your browser. -
Fill out the form with the following information and click Set Up Services:
- Twilio Credentials: API Key SID, API Secret, Account SID, Auth Token, and your Twilio phone number.
- Conversation Orchestrator Configuration: Display name and description for the configuration.
- Conversation Memory Configuration: Display name and description for the memory store.
- Optional Configuration: Your ngrok domain (required for voice) and OpenAI API key (required to run the example in this quickstart).
- Profile Information: Email, phone number, and optionally a first name to create a test customer profile.
-
Create the
.envfile in thegetting_started/examplesfolder:1cd getting_started/examples2cp .env.example .env -
Back in the wizard, click Copy and paste the values into the
.envfile you just created.
Use the ngrok domain from the earlier step to configure webhooks in the Console.
- In the Console, go to Products & services > Conversation Orchestrator > Conversation Configurations.
- Select your conversation configuration.
- In the Overview tab, click the Edit button.
- Set Webhook > Callback method to
https://your-domain.ngrok.app/webhook.- Replace
your-domainwith your actual ngrok domain from the previous section (either the random domain likeabc123xyzor your static domain).
- Replace
- Select
POSTas the HTTP method. - Click Save changes.
- In the Console, go to Products & services > Numbers & senders.
- Select your Twilio phone number.
- Under Configuration details, locate Voice configuration and click Edit details:
- Select Webhook, TwiML Bin, Function, Studio Flow, Proxy Service as a method.
- Choose Use Webhooks as the primary method.
- For the primary webhook URL, enter:
https://your-domain.ngrok.app/twiml. You can also set up a secondary webhook URL for if the primary webhook URL fails.- Replace
your-domainwith your actual ngrok domain from the previous section (either the random domain likeabc123xyzor your static domain)
- Replace
- Select
POSTas the HTTP method.
- Click Save.
-
In a new terminal window, navigate to the example directory:
cd getting_started/examples/partners -
Start the server:
uv run python openai_chat_completions.py -
You see a message confirming the server is running:
1INFO: Started server process2INFO: Waiting for application startup.3INFO: Application startup complete.4INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Now that your server is running, ngrok is exposing it to the internet, and Twilio webhooks are configured, you can test the agent using SMS or voice.
Info
To confirm memory retrieval, set TWILIO_LOG_LEVEL=debug in your .env file and restart the server. Check your terminal output for memory retrieval log entries.
Send a text message to your Twilio phone number:
"Hi, I need help with my account."
Without memory integration: The agent responds as a generic customer service assistant.
With memory integration: The agent retrieves past interactions and personalizes responses using profile data from Conversation Memory. For name-based personalization (for example, greeting the customer by name), a profile with traits like firstName must be configured in Conversation Memory.
Call your Twilio phone number. The agent will greet you and respond to spoken questions.
With memory integration: The agent uses your profile information to provide context-aware responses throughout the call.
The Python SDK includes a dashboard example that runs the same agent with a local observation UI for monitoring active conversations, message history, and agent context in real time.
To try it, stop the current server and run the dashboard example from the repository root:
uv run python getting_started/examples/features/dashboard/app.py
The dashboard example includes the same SMS and Voice agent from the previous steps, plus a monitoring interface.
Open http://localhost:8000/dashboard in your browser to view:
- Active Sessions — Live conversations with message viewer
- History — Closed conversations from Conversation Orchestrator
- Agent Context — Profile traits, observations, and summaries from Conversation Memory
Send an SMS or make a voice call to your Twilio number, then watch the dashboard update in real time.
Warning
The dashboard has no authentication. Use it for local development and demos only.
For more information about the dashboard, see the dashboard example in the Python SDK repository.
- Add TAC to your agent: Go beyond the quickstart — add custom tools, knowledge search, and memory to your agent.
- More examples (Python) and more examples (TypeScript): Explore additional TAC examples including outbound conversations, WhatsApp, RCS, and partner integrations.
- Core concepts: Understand TAC's architecture and component relationships.
- Troubleshooting: Common issues and solutions.