Zum Hauptinhalt springen

API Overview

JustCall's backend is powered by Supabase Edge Functions and a Node.js Voice Server.

Architecture​

Supabase Edge Functions​

Located in supabase/functions/:

Voice System Tools​

FunctionPurpose
tool-get-menuFetch restaurant menu
tool-check-deliveryValidate delivery address
tool-calculate-orderCalculate order totals
twilio-incomingHandle incoming calls

Integrations​

FunctionPurpose
whatsapp-webhookMeta WhatsApp Business API
menu-ocr-processMenu PDF/image OCR
menu-parseParse OCR text to structured menu
kb-searchKnowledge base semantic search

Billing​

FunctionPurpose
billing-create-setup-intentStripe setup intent
billing-charge-commissionCharge order commission

Voice Server API​

The Voice Server (Fly.io) exposes:

WebSocket Endpoints​

  • /twilio - Twilio Media Streams
  • /ws - Admin WebSocket (optional)

REST Endpoints​

  • GET /health - Health check
  • GET /admin/calls - List active calls
  • POST /admin/calls/[id]/hangup - Force hangup

Authentication​

Supabase Auth​

Frontend uses Supabase Auth with JWT:

const { data: { session } } = await supabase.auth.getSession();
// session.access_token is passed automatically

API Keys​

External integrations use API keys:

curl -H "x-api-key: just_xxxx" \
  https://xxx.supabase.co/functions/v1/external-orders

Service Role​

Edge Functions use service role for internal operations:

const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')! // Full access
);

Error Handling​

All Edge Functions return consistent error format:

{
  "error": "Descriptive error message",
  "code": "ERROR_CODE",
  "details": {}
}

HTTP Status Codes:

  • 200 - Success
  • 400 - Bad request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not found
  • 500 - Internal error

CORS​

All functions include CORS headers:

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 
    'authorization, x-client-info, apikey, content-type',
};

// Preflight
if (req.method === 'OPTIONS') {
  return new Response(null, { headers: corsHeaders });
}

Rate Limiting​

Supabase applies default rate limits. For higher limits:

  • Upgrade plan
  • Implement custom rate limiting in Edge Functions