Webhook Integration Guide

How It Works

When you define tools/functions for your voice agent, the AI will call your webhook URL whenever it needs to perform an action (like booking an appointment). Your webhook receives the function name and arguments, performs the action, and returns a result that the AI speaks back to the caller.

Caller: "I'd like to book an appointment for tomorrow at 3pm"
    ↓
AI collects: name, phone, date, time, reason
    ↓
AI calls your webhook: book_appointment({...})
    ↓
Your system: Creates calendar event, returns confirmation
    ↓
AI speaks: "I've booked your appointment for tomorrow at 3pm"

Webhook Payload

Your webhook receives a POST request with this JSON structure:

{
  "type": "function_call",
  "call_id": "CA1234567890abcdef",
  "function": {
    "name": "book_appointment",
    "arguments": {
      "patient_name": "Jonathan",
      "date": "2025-12-30",
      "time": "15:00",
      "reason": "back pain",
      "phone": "555-456"
    }
  }
}

Field Reference

Expected Response

Your webhook should return a JSON response with a result field. This text will be used by the AI to respond to the caller.

{
  "result": "Appointment confirmed for December 30th at 3:00 PM. We'll send a reminder to 555-456."
}

Important: The AI will use your response text naturally in conversation. Write it as you'd want it spoken, not as a system message.

Zapier Integration

Zapier is a great way to connect your voice agent to 5000+ apps without coding.

Setup Steps

1. Create a new Zap with Webhooks by Zapier as the trigger
2. Choose Catch Hook as the trigger event
3. Copy the webhook URL Zapier gives you
4. Paste it into your agent's Webhook URL field
5. Make a test call to send sample data to Zapier
6. Set up your action (Google Calendar, CRM, etc.)

Mapping Nested Fields in Zapier

Because the payload uses nested objects, use these paths in Zapier:

Example: Google Calendar

To create calendar events from voice appointments:

Custom Backend Example

Here's a simple Express.js webhook handler:

app.post('/webhook/voice', async (req, res) => {
  const { type, call_id, function: func } = req.body;
  
  if (type !== 'function_call') {
    return res.json({ result: 'Unknown request type' });
  }
  
  const { name, arguments: args } = func;
  
  switch (name) {
    case 'book_appointment':
      // Save to your database
      await db.appointments.create({
        patientName: args.patient_name,
        phone: args.phone,
        date: args.date,
        time: args.time,
        reason: args.reason,
        callId: call_id
      });
      return res.json({ 
        result: `Appointment booked for ${args.date} at ${args.time}` 
      });
      
    case 'check_availability':
      // Query your calendar
      const slots = await getAvailableSlots(args.date);
      return res.json({ 
        result: `Available times: ${slots.join(', ')}` 
      });
      
    default:
      return res.json({ result: 'Function not implemented' });
  }
});

Pre-built Function Templates

When creating an agent, you can use these pre-built function templates: