Skip to main content
POST
/
initiate-bridged-call
curl -X POST "https://api.magpipe.ai/functions/v1/initiate-bridged-call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "from": "+16045551234",
    "agent_id": "c72ea2b8-1234-5678-9abc-def012345678"
  }'

{
  "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"
}

​
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://api.magpipe.ai/functions/v1/initiate-bridged-call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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