Files · Cohere Voice Agent for Shopify Order Status Checks

# Cohere Voice Agent for Shopify Order Status Checks
 
> Enable customers to call and check order status via a natural voice conversation, integrated with Shopify for real-time updates.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Overview
 
This voice agent accepts inbound Twilio calls, transcribes speech with Deepgram, classifies intent and extracts order numbers using Cohere's command model, looks up order status in Shopify, and responds with lifelike speech via ElevenLabs. Built-in circuit breaker resilience, per-call budget controls, and Zendesk escalation ensure production readiness.
 
## Features
 
- **Twilio inbound** — receive and respond to phone calls via Twilio webhooks
- **Deepgram STT** — real-time speech-to-text transcription
- **Cohere intent recognition** — classify caller intent and extract entities
- **Shopify order lookup** — fetch real-time order status from Shopify Admin API
- **ElevenLabs TTS** — natural voice responses
- **Circuit breaker resilience** — protect Shopify API with automatic failure detection and recovery
- **Budget controls** — per-call spending limits via `@reaatech/agent-budget-engine`
- **Zendesk escalation** — seamless handoff to human agents when needed
 
## Prerequisites
 
- Node.js >= 22
- pnpm 10
- A Twilio account with a purchased phone number
- A Deepgram API key
- A Cohere API key
- An ElevenLabs API key
- A Shopify store with Admin API access
- A Zendesk account (for escalation)
- A Langfuse account (for observability)
- ngrok (for local development with Twilio)
 
## Environment Variables
 
| Variable | Description |
|----------|-------------|
| `NODE_ENV` | Environment (`development`, `production`, `test`) |
| `COHERE_API_KEY` | Cohere API key |
| `COHERE_MODEL` | Cohere model name (default: `command-a-03-2025`) |
| `DEEPGRAM_API_KEY` | Deepgram API key |
| `DEEPGRAM_MODEL` | Deepgram model name (default: `nova-3`) |
| `ELEVENLABS_API_KEY` | ElevenLabs API key |
| `ELEVENLABS_VOICE_ID` | ElevenLabs voice ID |
| `ELEVENLABS_TTS_MODEL` | ElevenLabs TTS model (default: `eleven_flash_v2_5`) |
| `TWILIO_ACCOUNT_SID` | Twilio Account SID |
| `TWILIO_AUTH_TOKEN` | Twilio Auth Token |
| `TWILIO_PHONE_NUMBER` | Twilio phone number |
| `SHOPIFY_SHOP_DOMAIN` | Shopify shop domain |
| `SHOPIFY_ACCESS_TOKEN` | Shopify Admin API access token |
| `SHOPIFY_API_KEY` | Shopify API key |
| `SHOPIFY_API_SECRET` | Shopify API secret |
| `ZENDESK_SUBDOMAIN` | Zendesk subdomain |
| `ZENDESK_EMAIL` | Zendesk email |
| `ZENDESK_API_TOKEN` | Zendesk API token |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_HOST` | Langfuse host URL |
| `PER_CALL_BUDGET_LIMIT_USD` | Per-call budget in USD (default: `0.50`) |
| `MAX_CALL_DURATION_SECONDS` | Maximum call duration in seconds (default: `600`) |
 
## Getting Started
 
```bash
pnpm install
cp .env.example .env
# Fill in your API keys and configuration in .env
pnpm dev
```
 
### Configure Twilio Webhook
 
1. Start ngrok: `ngrok http 3000`
2. In your Twilio Console, set the phone number's voice webhook URL to: `https://<your-ngrok-subdomain>.ngrok.io/api/twilio/incoming`
3. Set the HTTP method to POST
 
## API Routes
 
| Route | Method | Description |
|-------|--------|-------------|
| `POST /api/twilio/incoming` | POST | Handle incoming call from Twilio |
| `POST /api/twilio/gather` | POST | Process speech input from caller |
| `POST /api/twilio/status` | POST | Receive call status updates from Twilio |
| `GET /api/health` | GET | Health check endpoint |
 
## Project Structure
 
```
app/
  api/
    health/
      route.ts          GET /api/health
    twilio/
      incoming/
        route.ts        POST /api/twilio/incoming
      gather/
        route.ts        POST /api/twilio/gather
      status/
        route.ts        POST /api/twilio/status
src/
  config/
    env.ts              Zod-validated environment
  services/
    budget/
      controller.ts     Budget enforcement
      pricing-provider.ts Token pricing
      spend-store.ts    In-memory spend tracking
    circuit-breaker/
      shopify-breaker.ts Circuit breaker for Shopify API
    cohere/
      client.ts         Cohere LLM client
    deepgram/
      client.ts         Deepgram STT client
    elevenlabs/
      client.ts         ElevenLabs TTS client
    handoff/
      zendesk-handler.ts Zendesk escalation
    observability/
      langfuse.ts       LLM tracing
    shopify/
      client.ts         Shopify order lookup
    twilio/
      client.ts         Twilio client and webhook parsers
    voice/
      orchestrator.ts   Main conversation loop
      session-store.ts  In-memory call session store
  types/
    shopify.ts          Shopify types
    voice.ts            Call session and intent types
tests/
  api/
    health.test.ts
    twilio.test.ts
  e2e/
    call-flow.test.ts
  services/
    budget.test.ts
    circuit-breaker.test.ts
    cohere.test.ts
    deepgram.test.ts
    elevenlabs.test.ts
    handoff.test.ts
    observability.test.ts
    session-store.test.ts
    shopify.test.ts
    twilio.test.ts
    voice.test.ts
packages/               API references for every dependency
DEV_PLAN.md             Build plan for this recipe
```
 
## Testing
 
```bash
pnpm test
```
 
Runs the vitest suite with coverage reporting (configurable threshold: 90%+ lines, branches, functions, statements).
 
## License
 
MIT — see [LICENSE](./LICENSE).