Voiceflow Voice Outbound Demo

This service enables outbound voice calls using Twilio and Voiceflow Voice feature, with advanced call handling features including answering machine detection, call status tracking, and seamless integration with Voiceflow's conversational AI.

Features

Initiate outbound voice calls via a simple API endpoint
Automatic answering machine detection
Real-time call status tracking
Integration with Voiceflow for conversational AI
Detailed call status reporting and event logging

Prerequisites

Node.js
Twilio account with Account SID and Auth Token
Voiceflow account with API key and webhook ID
Environment variables properly configured

Environment Variables

Create a .env file with the following variables:

TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
VOICEFLOW_API_KEY=your_voiceflow_api_key
VOICEFLOW_WEBHOOK_ID=your_voiceflow_webhook_id
SERVER_URL=your_server_url
PORT=4242  # Optional, defaults to 4242

Note: The Voiceflow API key and webhook ID can be found in your Twilio Phone Numbers section. Select your phone number and look for the webhook URL:
https://runtime-api.voiceflow.com/v1/twilio/webhooks/{VOICEFLOW_WEBHOOK_ID}/answer?authorization={VOICEFLOW_API_KEY}

Installation

npm install

Running the Server

npm start

Local Testing with ngrok

To allow Twilio to reach your local service, you'll need to expose it using a secure tunnel. ngrok is recommended for this purpose.

Install ngrok from https://ngrok.com/download
Start ngrok tunnel to your local server:

ngrok http ${PORT:-4242}

Copy the HTTPS URL provided by ngrok (e.g., https://your-tunnel.ngrok-free.app)
Update your .env file with the ngrok URL:

SERVER_URL=https://your-tunnel.ngrok-free.app

Note: The ngrok URL changes each time you restart ngrok unless you have a paid account. Make sure to update your SERVER_URL environment variable whenever the URL changes.

Docker Support

You can also run this service using Docker. Make sure you have Docker and Docker Compose installed on your system.

Using Docker Compose (Recommended)

Make sure your .env file is properly configured
Build and start the container:

docker-compose up -d

To stop the service:

docker-compose down

Using Docker Directly

Build the Docker image:

docker build -t voiceflow-outbound .

Run the container:

docker run -d \
  --env-file .env \
  -p ${PORT:-4242}:${PORT:-4242} \
  --name voiceflow-outbound \
  voiceflow-outbound

To stop the container:

docker stop voiceflow-outbound
docker rm voiceflow-outbound

API Endpoints

1. Initiate a Call

GET /call?to={phoneNumber}&from={twilioNumber}

Parameters:

to: Destination phone number (E.164 format)
from: Your Twilio phone number (E.164 format)

Example:

curl "http://localhost:4242/call?to=14155551234&from=14155557890"

Response:

{
  "message": "Call initiated successfully",
  "callSid": "CA123...",
  "to": "+14155551234",
  "from": "+14155557890",
  "status": "queued",
  "statusUrl": "http://localhost:4242/status/CA123..."
}

2. Check Call Status

GET /status/{callId}