Step 1: Initial Request (to get Macaroon and Invoice)

Send a POST request with the destination phone number and either a text message or audio URL. This returns a 402 Payment Required with L402 headers (macaroon + Lightning invoice).

Example A — Text-to-speech:

curl -X POST https://sats4ai.com/api/l402/place-call \
-H "Content-Type: application/json" \
-d '{"phone_number":"+1234567890","message":"Hello, this is your appointment reminder for tomorrow at 3 PM."}' \
-i

Example B — Audio file (include duration_minutes):

curl -X POST https://sats4ai.com/api/l402/place-call \
-H "Content-Type: application/json" \
-d '{"phone_number":"+1234567890","audio_url":"https://example.com/my-audio-message.mp3","duration_minutes":2}' \
-i

Step 2: Pay the Lightning Invoice

Pay the Lightning invoice from the www-authenticate header using any Lightning wallet. Save the preimage (proof of payment) for Step 3.

Step 3: Final Request (to Place the Call)

Repeat the same request with an Authorization header containing the macaroon and preimage.

Important: The JSON body must be identical to Step 1.

Example A — TTS:

curl -X POST https://sats4ai.com/api/l402/place-call \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{"phone_number":"+1234567890","message":"Hello, this is your appointment reminder for tomorrow at 3 PM."}'

Example B — Audio file:

curl -X POST https://sats4ai.com/api/l402/place-call \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{"phone_number":"+1234567890","audio_url":"https://example.com/my-audio-message.mp3","duration_minutes":2}'

Success Response:

{
  "success": true,
  "sid": "CA1234567890abcdef",
  "status": "queued",
  "to": "+1234567890"
}

Request Body Parameters

Option A: Text-to-Speech

{
  "phone_number": "+1234567890",
  "message": "Hello, this is your appointment reminder for tomorrow at 3 PM."
}

Option B: Play Audio File

{
  "phone_number": "+1234567890",
  "audio_url": "https://example.com/my-audio-message.mp3",
  "duration_minutes": 2
}

Step 0: Discovery (Optional)

Send a GET request to see accepted parameters, pricing details, and supported options.

curl -X GET https://sats4ai.com/api/l402/ai-call

Step 1: Initial Request (to get Macaroon and Invoice)

Send a POST request with the destination phone number and the task you want the AI agent to perform. This returns a 402 Payment Required response with L402 headers (macaroon + Lightning invoice).

curl -X POST https://sats4ai.com/api/l402/ai-call \
-H "Content-Type: application/json" \
-d '{"phone_number":"+1234567890","task":"Call the restaurant and make a reservation for 2 people at 7 PM tonight under the name Smith.","duration_minutes":3,"language":"en","begin_message":"Hi, I'd like to make a reservation please."}' \
-i

Step 2: Pay the Lightning Invoice

Pay the Lightning invoice from the www-authenticate header using any Lightning wallet. Save the preimage (proof of payment) for Step 3.

Step 3: Final Request (to Start the AI Call)

Repeat the same request with an Authorization header containing the macaroon and preimage.

Important: The JSON body must be identical to Step 1.

curl -X POST https://sats4ai.com/api/l402/ai-call \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{"phone_number":"+1234567890","task":"Call the restaurant and make a reservation for 2 people at 7 PM tonight under the name Smith.","duration_minutes":3,"language":"en","begin_message":"Hi, I'd like to make a reservation please."}'

Success Response (call initiated):

{
  "success": true,
  "state": "calling",
  "call_id": "call_abc123def456",
  "session_id": "uuid-...",
  "status": "initiated",
  "poll_url": "https://sats4ai.com/api/l402/ai-call?call_id=call_abc123def456",
  "message": "Call initiated. Poll the poll_url for transcript and results."
}

Push-back Response (missing details):

If your task is missing critical info (e.g., a booking without date or time), the API returns clarification questions instead of starting the call. Answer them with a confirm request.

{
  "success": true,
  "state": "pending_confirm",
  "session_id": "uuid-...",
  "questions": [
    "What date should the booking be for?",
    "What time would you prefer?",
    "How many people will be dining?"
  ],
  "message": "Task is missing some details. POST with action='confirm' to proceed."
}

Confirm Request (after push-back):

curl -X POST https://sats4ai.com/api/l402/ai-call \
  -H "Content-Type: application/json" \
  -d '{
    "action": "confirm",
    "session_id": "uuid-...",
    "answers": {
      "What date should the booking be for?": "This Saturday",
      "What time would you prefer?": "7pm",
      "How many people will be dining?": "4"
    }
  }'

Step 4: Poll for Transcript & Results

The AI call runs asynchronously. Use the call_id from the response to poll for the transcript and call status. No authentication is required for polling.

curl -X GET "https://sats4ai.com/api/l402/ai-call?call_id=<CALL_ID_FROM_RESPONSE>"

Polling Response (in progress):

{
  "status": "in_progress",
  "call_id": "call_abc123def456",
  "message": "Call in progress. Poll again for results."
}

Polling Response (auto-retrying):

{
  "status": "in_progress",
  "call_id": "call_abc123def456",
  "attempt": 2,
  "max_attempts": 3,
  "retry_reason": "voicemail_reached",
  "message": "Auto-retrying (attempt 2/3, reason: voicemail_reached). Poll again."
}

Polling Response (completed - task succeeded):

{
  "status": "ended",
  "call_id": "call_abc123def456",
  "task_completed": true,
  "transcript": "Agent: Hi, I'd like to make a reservation...\nHost: Of course...",
  "call_analysis": { "call_summary": "Reserved a table for 4 at 7 PM Saturday." },
  "recording_url": "https://..."
}

Polling Response (completed - task failed):

{
  "status": "ended",
  "call_id": "call_abc123def456",
  "task_completed": false,
  "transcript": "Agent: Hi, I'd like to book...\nHost: Sorry, we're fully booked...",
  "call_analysis": { "call_summary": "Restaurant fully booked for Saturday." },
  "disconnection_reason": "agent_hangup",
  "message": "Task was not completed. Review the transcript to understand what happened. You can retry with a new payment."
}

AI Call Request Body Parameters

{
  "phone_number": "+1234567890",
  "task": "Call the restaurant and make a reservation for 2 people at 7 PM tonight under the name Smith.",
  "duration_minutes": 3,
  "language": "en",
  "begin_message": "Hi, I'd like to make a reservation please."
}