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
}