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"
}'
const response = await fetch(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+14155551234',
from: '+16045551234',
agent_id: 'c72ea2b8-1234-5678-9abc-def012345678',
}),
}
);
const data = await response.json();
console.log(data.call_id);
import requests
response = requests.post(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json',
},
json={
'to': '+14155551234',
'from': '+16045551234',
'agent_id': 'c72ea2b8-1234-5678-9abc-def012345678',
}
)
data = response.json()
print(data['call_id'])
{
"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"
}
Calls
Create Phone Call
Initiate an outbound phone call with an AI agent
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"
}'
const response = await fetch(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+14155551234',
from: '+16045551234',
agent_id: 'c72ea2b8-1234-5678-9abc-def012345678',
}),
}
);
const data = await response.json();
console.log(data.call_id);
import requests
response = requests.post(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json',
},
json={
'to': '+14155551234',
'from': '+16045551234',
'agent_id': 'c72ea2b8-1234-5678-9abc-def012345678',
}
)
data = response.json()
print(data['call_id'])
{
"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
string
required
Bearer token for authentication.Example:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...string
required
Must be
application/jsonBody Parameters
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
string
required
Your Magpipe phone number to use as caller ID. Must be a number provisioned in your account.Example:
+16045551234string
required
UUID of the AI agent to handle the call.Example:
c72ea2b8-1234-5678-9abc-def012345678object
Optional key-value pairs to attach to the call. Available in webhooks and call logs.Example:
{
"customer_id": "cust_123",
"campaign": "follow_up"
}
string
URL to receive call status webhooks. Overrides account-level webhook settings.Example:
https://yourapp.com/webhooks/callsResponse
boolean
Whether the call was successfully initiated.
string
Unique identifier for the call. Use this to track call status.
string
Initial call status. One of:
initiated- Call is being placedqueued- Call is queued for dialing
string
The caller ID number used.
string
The destination phone number.
string
The agent handling the call.
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"
}'
const response = await fetch(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+14155551234',
from: '+16045551234',
agent_id: 'c72ea2b8-1234-5678-9abc-def012345678',
}),
}
);
const data = await response.json();
console.log(data.call_id);
import requests
response = requests.post(
'https://api.magpipe.ai/functions/v1/initiate-bridged-call',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json',
},
json={
'to': '+14155551234',
'from': '+16045551234',
'agent_id': 'c72ea2b8-1234-5678-9abc-def012345678',
}
)
data = response.json()
print(data['call_id'])
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
| Status | Description |
|---|---|
initiated | Call request received, dialing |
ringing | Recipient phone is ringing |
in-progress | Call is active |
completed | Call ended normally |
busy | Recipient was busy |
no-answer | No answer after timeout |
failed | Call failed to connect |
canceled | Call was canceled before connecting |