Skip to main content

Knowledge > Runbooks > Customer Ops > Add Voice Number

Provision a Twilio Number for a Church Voice Agent

Buy a local Twilio phone number for a church, configure it to forward to the Cartesia voice agent, and create the church_voice_agents database row.

Prerequisites​

  • Twilio Console access (credentials: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN)
  • Supabase access
  • Church's UUID from the churches table
  • Church's desired area code (ideally matching their local area code)

Architecture Note​

The voice agent is multi-tenant — one deployed agent serves ALL churches. No redeploy is needed when adding a new church. The agent routes calls by inbound phone number using main.py:get_agent(), which looks up the number in church_voice_agents.

Steps​

1. Identify the church UUID​

SELECT id, name, city, state, phone
FROM churches
WHERE name ILIKE '%[church-name]%'
LIMIT 3;

Copy the id (UUID).

2. Determine the desired area code​

Use the church's local area code (shown in their phone field, or ask the church). A local number builds trust with callers.

3. Purchase a Twilio phone number​

Log in to the Twilio Console:

  • Navigate to Phone Numbers → Buy a Number
  • Filter by Country: US, Type: Local, Area Code: [desired code]
  • Select a number and purchase it (~$1.15/month)

Copy the purchased number in E.164 format, e.g., +15551234567.

4. Configure the Twilio number to forward to the voice agent​

In Twilio Console, go to the purchased number's configuration:

  • Under Voice & Fax → A call comes in
  • Set to Webhook
  • URL: https://churchwiseai.com/api/voice/twiml (or the Cartesia endpoint URL — verify current endpoint)
  • HTTP Method: POST
  • Save

Alternatively, via Twilio CLI:

twilio phone-numbers:update +15551234567 \
  --voice-url https://churchwiseai.com/api/voice/twiml \
  --voice-method POST

5. Create the church_voice_agents row in Supabase​

INSERT INTO church_voice_agents (
  church_id,
  phone_number,
  is_active,
  agent_name,
  greeting,
  created_at
) VALUES (
  '[church-uuid]',
  '+15551234567',   -- Twilio number in E.164 format
  true,
  'Grace Community Church',   -- Church's display name
  'Thank you for calling Grace Community Church! How can I help you today?',
  now()
);

Adjust columns to match the current church_voice_agents schema. Check the actual schema first:

SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'church_voice_agents'
ORDER BY ordinal_position;

6. Verify the configuration​

Call the new Twilio number from a phone. The voice agent should answer within 5 seconds. Confirm:

  • The greeting uses the church's name (not "ChurchWiseAI")
  • The agent responds correctly to basic questions
  • A voice_call_logs row is created after the call ends
SELECT id, church_id, status, duration_seconds, created_at
FROM voice_call_logs
WHERE church_id = '[church-uuid]'
ORDER BY created_at DESC LIMIT 3;

7. Notify the church​

Send the church their new phone number and instructions for forwarding their main number (if they want calls to forward from their existing church number to the AI line).

Optional: Cal.com Integration​

If the church wants appointment booking, add their Cal.com credentials to church_voice_agents:

UPDATE church_voice_agents
SET calcom_api_key = '[their-calcom-api-key]',
    calcom_event_type_id = '[their-event-type-id]'
WHERE church_id = '[church-uuid]';

Rollback​

To deactivate a voice number:

UPDATE church_voice_agents
SET is_active = false
WHERE church_id = '[church-uuid]';

Release the Twilio number in the Twilio Console (Phone Numbers → Active Numbers → Release).

See Also​