Create Phone 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"
}

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/json

Body 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: +16045551234

string

required

UUID of the AI agent to handle the call.Example: c72ea2b8-1234-5678-9abc-def012345678

object

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/calls

Response

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 placed
queued - 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

API Reference

Agents

Custom Functions

Dynamic Variables

Memory

Calls

Call Whitelist

Skills

Batch Calls

Testing

Messages

Phone Numbers

Chat Widget

Knowledge Base

Voice

Models

Calendar

Contacts

Billing

Scheduled Actions

API Keys & Webhooks

Create Phone Call

Overview

Request

Headers

Body Parameters

Response

Example Request

Example Response

Error Responses

Call Status Webhook

Call Status Values

​Overview

​Request

​Headers

​Body Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Call Status Webhook

​Call Status Values

Overview

Request

Headers

Body Parameters

Response

Example Request

Example Response

Error Responses

Call Status Webhook

Call Status Values