Skip to main content
POST
/
initiate-bridged-call
Create Phone Call
curl --request POST \
  --url https://mtxbiyilvgwhbdptysex.supabase.co/functions/v1/initiate-bridged-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+14155551234",
  "caller_id": "+16045551234",
  "purpose": "<string>",
  "goal": "<string>",
  "template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number"
  }
}

​
Overview

Creates a new outbound phone call. The AI agent will call the specified phone number and handle the conversation based on its configuration.
Calls are billed based on duration. See Pricing for details.

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication.Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
to
string
required
The phone number to call in E.164 format.Example: +14155551234Constraints:
  • Must start with + followed by country code
  • 10-15 digits total
  • Must be a valid, dialable phone number
​
from
string
required
Your Magpipe phone number to use as caller ID. Must be a number provisioned in your account.Example: +16045551234
​
agent_id
string
required
UUID of the AI agent to handle the call.Example: c72ea2b8-1234-5678-9abc-def012345678
​
metadata
object
Optional key-value pairs to attach to the call. Available in webhooks and call logs.Example:
{
  "customer_id": "cust_123",
  "campaign": "follow_up"
}
​
webhook_url
string
URL to receive call status webhooks. Overrides account-level webhook settings.Example: https://yourapp.com/webhooks/calls

​
Response

​
success
boolean
Whether the call was successfully initiated.
​
call_id
string
Unique identifier for the call. Use this to track call status.
​
status
string
Initial call status. One of:
  • initiated - Call is being placed
  • queued - Call is queued for dialing
​
from_number
string
The caller ID number used.
​
to_number
string
The destination phone number.
​
agent_id
string
The agent handling the call.
​
created_at
string
ISO 8601 timestamp of when the call was created.

​
Example Request

curl -X POST "https://mtxbiyilvgwhbdptysex.supabase.co/functions/v1/initiate-bridged-call" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "from": "+16045551234",
    "agent_id": "c72ea2b8-1234-5678-9abc-def012345678"
  }'

​
Example Response

{
  "success": true,
  "call_id": "a1b2c3d4-5678-9012-3456-789012345678",
  "status": "initiated",
  "from_number": "+16045551234",
  "to_number": "+14155551234",
  "agent_id": "c72ea2b8-1234-5678-9abc-def012345678",
  "created_at": "2024-01-15T10:30:00.000Z"
}

​
Error Responses

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient account balance to place call"
  }
}

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with specified ID not found"
  }
}

{
  "error": {
    "code": "NUMBER_NOT_OWNED",
    "message": "The 'from' number is not provisioned in your account"
  }
}

​
Call Status Webhook

When the call status changes, a webhook is sent to your configured URL: 
{
  "event": "call.status_changed",
  "call_id": "a1b2c3d4-5678-9012-3456-789012345678",
  "status": "completed",
  "duration": 125,
  "recording_url": "https://storage.magpipe.ai/recordings/...",
  "transcript": "Agent: Hello! Caller: Hi there...",
  "metadata": {
    "customer_id": "cust_123"
  },
  "timestamp": "2024-01-15T10:32:05.000Z"
}

​
Call Status Values

StatusDescription
initiatedCall request received, dialing
ringingRecipient phone is ringing
in-progressCall is active
completedCall ended normally
busyRecipient was busy
no-answerNo answer after timeout
failedCall failed to connect
canceledCall was canceled before connecting

Authorizations

​
Authorization
string
header
required

Your Magpipe access token from the dashboard

Body

application/json
​
phone_number
string
required

Destination phone number in E.164 format

Example:

"+14155551234"

​
caller_id
string
required

Your Magpipe phone number to use as caller ID (agent assigned to this number handles the call)

Example:

"+16045551234"

​
purpose
string

Purpose of the call (provided to the agent as context)

​
goal
string

Goal of the call (provided to the agent as context)

​
template_id
string<uuid>

Optional call template ID

Response

Call initiated successfully

​
success
boolean
Example:

true

​
call_sid
string

SignalWire call SID

​
call_record_id
string<uuid>

Internal call record ID

​
status
string
Example:

"queued"