# 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

## Prerequisites

Before you begin, gather the following information from the [Console](https://1console.twilio.com/):

| Credential              | Where to find it                                                                                                                                                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Twilio Account SID**  | In the [Console Dashboard](https://1console.twilio.com). Starts with `AC`.                                                                                                                                                                                             |
| **Twilio Auth Token**   | In the [Console](https://1console.twilio.com), 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](https://1console.twilio.com), 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](https://1console.twilio.com), 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](https://platform.openai.com/account/api-keys).
* **Python 3.10+** or **Node.js 22.13.0+**: Depending on your chosen language.

## Clone the example repository

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](/docs/conversations/agent-connect/build-with-tac#install-the-sdk) for pip/npm installation instructions.

## Python

1. Clone the TAC repository and navigate to it:

   ```bash
   git clone https://github.com/twilio/twilio-agent-connect-python.git
   cd twilio-agent-connect-python
   ```
2. Install `uv`, a Python package manager. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for instructions.

   ```bash
   # macOS/Linux
   curl -sSL https://install.astral.sh | sh
   # or with Homebrew (macOS)
   brew install uv
   # or with pip
   pip install uv
   ```
3. Install dependencies:

   ```bash
   make sync
   ```

## TypeScript

1. Clone the TAC repository and navigate to it:

   ```bash
   git clone https://github.com/twilio/twilio-agent-connect-typescript.git
   cd twilio-agent-connect-typescript
   ```
2. Install dependencies:

   ```bash
   npm install
   ```
3. Build the packages:

   ```bash
   npm run build
   ```

## Expose your local server with ngrok

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:

### Free ngrok plan (random domain)

1. Start ngrok:

   ```bash
   ngrok http 8000
   ```
2. Ngrok generates a **random URL** (for example, `https://abc123xyz.ngrok.app`). Copy the domain from the ngrok terminal output (for example, `abc123xyz.ngrok.app`).

> \[!NOTE]
>
> 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.

### Paid ngrok plan (static domain)

If you have a paid ngrok plan with a static domain, you can use the same URL every time:

1. Start ngrok with your static domain:

   ```bash
   ngrok http --url=your-static-domain.ngrok.app 8000
   ```
2. 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.

> \[!NOTE]
>
> 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.

## Configure your environment

## Python

The Python SDK includes a setup wizard that creates the required Twilio services and generates your environment variables.

1. In a new terminal window (keep ngrok running), start the setup wizard from the repository root:

   ```bash
   make setup
   ```
2. Open `http://localhost:8080` in your browser.
3. 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.
4. Create the `.env` file in the `getting_started/examples` folder:

   ```bash
   cd getting_started/examples
   cp .env.example .env
   ```
5. Back in the wizard, click **Copy** and paste the values into the `.env` file you just created.

## TypeScript

The TypeScript SDK requires manual environment configuration and service creation.

### Configure environment variables

1. Navigate to the examples directory and create your `.env` file:

   ```bash
   cd getting_started/examples
   cp .env.example .env
   ```
2. Open the `.env` file and add your Twilio credentials:

   ```bash
   TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_AUTH_TOKEN=your_auth_token_here
   TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_API_SECRET=your_api_secret_here
   TWILIO_PHONE_NUMBER=+YOUR_TWILIO_NUMBER
   OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   ```
3. You also need a `TWILIO_CONVERSATION_CONFIGURATION_ID`. Create this service by following the steps in the next section.

### Create required Twilio services

Create a Conversation Configuration and a Memory Store by following the steps in the [Conversation Orchestrator quickstart](/docs/conversations/orchestrator/quickstart#create-a-memory-store-and-conversation-configuration). You can use the Console or the REST API. Save the conversation configuration ID (starts with `conv_configuration_`) — you need it in the next step.

### Add service IDs to your environment

Add the service IDs to your `.env` file:

```bash
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_VOICE_PUBLIC_DOMAIN=your-domain.ngrok.app              # Optional, for voice
```

## Configure Twilio webhooks

Use the ngrok domain from the earlier step to configure webhooks in the Console.

### Configure SMS webhook

1. In the [Console](https://1console.twilio.com/), go to **Products & services** > **Conversation Orchestrator** > **Conversation Configurations**.
2. Select your conversation configuration.
3. In the **Overview** tab, click the **Edit** button.
4. Set **Webhook > Callback method** to `https://your-domain.ngrok.app/webhook`.
   * Replace `your-domain` with your actual ngrok domain from the previous section (either the random domain like `abc123xyz` or your static domain).
5. Select **`POST`** as the HTTP method.
6. Click **Save changes**.

### Configure Voice webhook

1. In the [Console](https://1console.twilio.com/), go to **Products & services** > **Numbers & senders**.
2. Select your Twilio phone number.
3. 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-domain` with your actual ngrok domain from the previous section (either the random domain like `abc123xyz` or your static domain)
   * Select **`POST`** as the HTTP method.
4. Click **Save**.

## Start the server

## Python

1. In a new terminal window, navigate to the example directory:

   ```bash
   cd getting_started/examples/partners
   ```
2. Start the server:

   ```bash
   uv run python openai_chat_completions.py
   ```
3. You see a message confirming the server is running:

   ```bash
   INFO:     Started server process
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
   ```

## TypeScript

1. In a new terminal window, navigate to the OpenAI example directory:

   ```bash
   cd getting_started/examples/openai
   ```
2. Install example dependencies and start the server:

   ```bash
   npm install
   npm run dev
   ```
3. You see a message confirming the server is running:

   ```bash
   Server started successfully
   ```

## Test the agent

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.

> \[!NOTE]
>
> 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.

### Test with SMS

Send a text message to your Twilio phone number:

```text
"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.

### Test with Voice

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.

### Optional: Monitor with the demo dashboard

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:

```bash
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](https://github.com/twilio/twilio-agent-connect-python/tree/main/getting_started/examples/features/dashboard) in the Python SDK repository.

## Next steps

* [Add TAC to your agent](/docs/conversations/agent-connect/build-with-tac): Go beyond the quickstart — add custom tools, knowledge search, and memory to your agent.
* [More examples](https://github.com/twilio/twilio-agent-connect-python/tree/main/getting_started/examples) (Python) and [more examples](https://github.com/twilio/twilio-agent-connect-typescript/tree/main/getting_started/examples) (TypeScript): Explore additional TAC examples including outbound conversations, WhatsApp, RCS, and partner integrations.
* [Core concepts](/docs/conversations/agent-connect/core-concepts): Understand TAC's architecture and component relationships.
* [Troubleshooting](/docs/conversations/agent-connect/troubleshooting): Common issues and solutions.