CallMyCall API Docs

Endpoints

POST /v1/start-call

Start an outbound AI call.

Field	Type	Required	Description
`phone_number`	string	yes	E.164 destination number.
`task`	string	yes	Instruction for AI behavior.
`language`	string	no	Language code such as `sv`, `en`, `de`.
`tts_provider`	string	no	`auto`, `openai`, `elevenlabs`, `azure`.
`openaiVoice`	string	no	OpenAI realtime voice id.
`11labsVoice`	string	no	ElevenLabs voice id (legacy alias).
`elevenLabsVoice`	string	no	ElevenLabs voice id.
`elevenLabsModel`	string	no	ElevenLabs model id.
`azureVoice`	string	no	Azure Neural voice name.
`style`	string	no	Azure style hint.
`role`	string	no	Azure role hint.
`azureBackgroundAudio`	object	no	Background audio config for Azure speech.
`additionalPrompt`	string	no	Extra instructions appended to task context.
`record`	boolean	no	Enable call recording.
`max_duration`	number	no	Maximum connected call duration (seconds).
`max_queue_time`	number	no	Maximum queue wait duration (seconds).
`persona`	object	no	Caller persona fields (name, phone, etc).
`transfer_number`	string	no	E.164 transfer target for handoff flows.
`from_number`	string	no	Override caller id (must be verified).
`share_policy`	object	no	Controls how sensitive fields may be shared.
`enable_calendar`	boolean	no	Enable calendar tools in-call.
`calendar_permissions`	object	no	Calendar read/write permissions.
`webhook`	string	no	HTTPS endpoint for events.
`webhook_events`	string[]	no	Event filters. Default is `call_completed`.
`metadata`	object	no	Arbitrary client metadata (for correlation/idempotency).
`userOnCall`	boolean	no	User joins call before AI takeover.
`userPhone`	string	conditional	Required when `userOnCall` is true.
`monitored`	boolean	no	Deprecated alias of `userOnCall`.
`user_phone`	string	no	Deprecated alias of `userPhone`.

{
  "success": true,
  "sid": "CA1234567890abcdef"
}

{
  "error": "Insufficient credits",
  "credits_balance": 3,
  "minimum_required": 5
}

curl -X POST https://call-my-call-backend.fly.dev/v1/start-call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+46700000000","task":"Confirm booking","language":"en","webhook":"https://example.com/cmc"}'

const res = await fetch("https://call-my-call-backend.fly.dev/v1/start-call", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+46700000000",
    task: "Confirm booking",
    language: "en",
    webhook: "https://example.com/cmc",
  }),
});
const data = await res.json();

POST /v1/end-call

End an active call.

Field	Type	Required	Description
`callSid`	string	yes	Twilio call SID from start response.

{
  "ok": true,
  "alreadyClosed": false,
  "transcript": []
}

{
  "error": "Missing callSid"
}

curl -X POST https://call-my-call-backend.fly.dev/v1/end-call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callSid":"CA1234567890abcdef"}'

const res = await fetch("https://call-my-call-backend.fly.dev/v1/end-call", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ callSid }),
});
const data = await res.json();

POST /v1/calls/:callSid/activate

Activate AI takeover for user-on-call sessions.

Field	Type	Required	Description
`task`	string	no	Override current AI task for takeover.
`drop_user`	boolean	no	Disconnect user leg when AI takes over.
`additional_prompt`	string	no	Additional instructions appended at activation.
`transfer_number`	string	no	Transfer target if handoff is needed.

{
  "success": true,
  "ai_activated": true,
  "user_dropped": true,
  "message": "Call redirected to AI bidirectional stream"
}

{
  "error": "Call not found or not a userOnCall session"
}

curl -X POST https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/activate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Take over now","drop_user":true}'

const res = await fetch(`${baseUrl}/v1/calls/${callSid}/activate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ task: "Take over now", drop_user: true }),
});
const data = await res.json();

GET /v1/calls/:callId

Fetch call details and recent transcripts by call id/sid.

Param	Type	Required	Description
`callId`	string	yes	Call SID from start response.

{
  "call": {
    "call_id": "CA1234567890abcdef",
    "status": "completed",
    "to": "+46700000000",
    "created_at": "2026-02-14T10:00:00.000Z"
  },
  "transcripts": [
    { "role": "assistant", "text": "Hello.", "seq": 1 }
  ]
}

curl -X GET https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/calls/${callSid}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

GET /v1/calls/:callId/transcripts/stream

Subscribe to realtime transcript updates using Server-Sent Events.

Param	Type	Required	Description
`callId`	string	yes	Call SID from start response.

event: added
data: {"role":"assistant","text":"Hello.","seq":1}

event: ping
data: {"ts":1739511142}

curl -N https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/transcripts/stream

const es = new EventSource(`${baseUrl}/v1/calls/${callSid}/transcripts/stream`);
es.addEventListener("added", (event) => {
  const turn = JSON.parse(event.data);
  console.log(turn);
});

Use this when you need live transcript rendering before call completion.

GET /v1/calls/:callSid/recording

Get a signed recording URL for a completed call (if recording enabled).

Query	Type	Required	Description
`format`	string	no	`mp3` or `wav` (default `mp3`).

{
  "recording_url": "https://call-my-call-backend.fly.dev/v1/recordings/RE123.mp3?token=...",
  "expires_at": "2026-02-14T12:00:00.000Z"
}

{
  "error": "Recording not found for this call"
}

curl -X GET "https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/recording?format=mp3" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/calls/${callSid}/recording?format=mp3`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json(); // { recording_url, expires_at }

POST /v1/calls/:callSid/transfer

Transfer an active call to another destination.

Field	Type	Required	Description
`destination`	string	yes	E.164 transfer destination.
`warm`	boolean	no	Defaults to `true` for warm transfer.
`reason`	string	no	Optional transfer reason for logs/traceability.

{
  "success": true,
  "transferType": "warm",
  "callSid": "CA1234567890abcdef"
}

curl -X POST https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"+46123456789","warm":true,"reason":"human_requested"}'

const res = await fetch(`${baseUrl}/v1/calls/${callSid}/transfer`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    destination: "+46123456789",
    warm: true,
    reason: "human_requested",
  }),
});
const data = await res.json();

GET /v1/recordings/:sid.:ext

Stream recording audio bytes using a signed token URL from the recording endpoint.

Param	Type	Required	Description
`sid`	string	yes	Recording SID.
`ext`	string	yes	`mp3` or `wav`.
`token`	string	yes	Signed short-lived token query param.

curl -L "https://call-my-call-backend.fly.dev/v1/recordings/RE123.mp3?token=SIGNED_TOKEN"

const audioRes = await fetch(recordingUrlFromPreviousStep);
const audioBuffer = await audioRes.arrayBuffer();

PATCH /v1/calls/:callSid

Update active call parameters while call is running.

Field	Type	Required	Description
`task`	string	no	Replace active task.
`transfer_number`	string	no	Set E.164 transfer target.
`additional_prompt`	string	no	Append to prompt context.
`max_duration`	number	no	Connected call max duration seconds.
`max_queue_time`	number	no	Queue max duration seconds.

curl -X PATCH https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Updated task","transfer_number":"+46123456789"}'

const res = await fetch(`${baseUrl}/v1/calls/${callSid}`, {
  method: "PATCH",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ task: "Updated task", transfer_number: "+46123456789" }),
});
const data = await res.json();

GET /v1/calls/:callSid/conference-status

Get user-on-call conference state and participants.

curl -X GET https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/conference-status \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/calls/${callSid}/conference-status`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

POST /v1/calls/:callSid/drop-user

Disconnect the user leg from a user-on-call session.

curl -X POST https://call-my-call-backend.fly.dev/v1/calls/CA1234567890abcdef/drop-user \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/calls/${callSid}/drop-user`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

POST /v1/verify-caller-id

Start caller id verification for custom from_number usage.

Field	Type	Required	Description
`phone_number`	string	yes	E.164 number to verify.

curl -X POST https://call-my-call-backend.fly.dev/v1/verify-caller-id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+46123456789"}'

const res = await fetch(`${baseUrl}/v1/verify-caller-id`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ phone_number: "+46123456789" }),
});
const data = await res.json();

GET /v1/verification-status/:id

Check verification state (pending, verified, failed).

curl -X GET https://call-my-call-backend.fly.dev/v1/verification-status/CA_VERIFICATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/verification-status/${verificationId}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

GET /v1/verified-caller-ids

List verified caller ids available to your key/account.

curl -X GET https://call-my-call-backend.fly.dev/v1/verified-caller-ids \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/verified-caller-ids`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

DELETE /v1/verified-caller-ids/:phone_number

Remove a verified caller id owned by your API key.

curl -X DELETE https://call-my-call-backend.fly.dev/v1/verified-caller-ids/+46123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/verified-caller-ids/${encodeURIComponent(phoneNumber)}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

POST /v1/webhook/test

Send a synthetic webhook payload to your endpoint.

Field	Type	Required	Description
`webhook_url`	string	yes	HTTPS URL to receive test event.
`event`	string	no	Defaults to `call_completed`.

curl -X POST https://call-my-call-backend.fly.dev/v1/webhook/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://example.com/cmc","event":"call_completed"}'

const res = await fetch(`${baseUrl}/v1/webhook/test`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ webhook_url: "https://example.com/cmc", event: "call_completed" }),
});
const data = await res.json();

POST /v1/elevenlabs/voices

Proxy endpoint for ElevenLabs voice cloning via multipart upload.

Field	Type	Required	Description
`name`	string	yes	Voice name label.
`files`	file[]	yes	One or more audio samples.
`remove_background_noise`	boolean	no	Noise removal hint for cloning.

curl -X POST https://call-my-call-backend.fly.dev/v1/elevenlabs/voices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=My Voice" \
  -F "files=@sample1.wav" \
  -F "files=@sample2.wav"

const form = new FormData();
form.append("name", "My Voice");
form.append("files", file1);
form.append("files", file2);

const res = await fetch(`${baseUrl}/v1/elevenlabs/voices`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});
const data = await res.json();

GET /v1/recordings/:callId

Legacy recording stream route (mp3 stream by call id).

curl -L https://call-my-call-backend.fly.dev/v1/recordings/CA1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(`${baseUrl}/v1/recordings/${callSid}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const audio = await res.arrayBuffer();

User-On-Call flow and states

State	Behavior	Next
`initiated`	Target + user legs are dialed.	`connected` or `failed`
`connected`	User and target talk. AI can stay silent/listening.	`ai_takeover` or `completed`
`ai_takeover`	`/activate` redirects call to AI realtime stream.	`active`
`active`	AI speaks and executes task.	`transferred` or `completed`
`completed`	Call ends and completion webhook fires.	-

Webhooks

Set webhook and optional webhook_events in start-call payload.

Event	When	Notes
`call_started`	Realtime stream starts	Best-effort signal
`transcript_updated`	New transcript segments	Can fire multiple times
`price_updated`	Post-call price enrichment	May arrive after completion
`call_completed`	Call closes	Default if events list omitted

{
  "event": "call_completed",
  "call_id": "CA1234567890abcdef",
  "sid": "CA1234567890abcdef",
  "timestamp": 1739511142,
  "data": {
    "status": "completed",
    "to": "+46700000000",
    "summary": { "goal_completed": true },
    "transcripts": [
      { "role": "assistant", "content": "Hello.", "timestamp": "2026-02-14T10:00:00.000Z", "seq": 1 }
    ]
  }
}

Delivery contract	Current behavior
Success condition	Any HTTP 2xx response.
Retries	Up to 3 attempts total.
Retry policy	Retry on network errors and 5xx. No retry on 4xx.
Backoff	600ms then 1200ms between retries.
Request timeout	10 seconds per attempt.
Signature	`X-Callmycall-Signature: t=TIMESTAMP,v1=HMAC_SHA256` (when signing secret is configured).

Deduplicate by event + sid + timestamp.

HTTP	Example	Cause
400	`Missing phone_number`	Validation failed.
401	`Authorization header with API key is required`	Missing/invalid auth.
402	`Subscription inactive` / `Insufficient credits`	Billing pre-check failed.
404	`Call not found`	Unknown SID or already closed.
429	`Too Many Requests`	Apply client backoff and retry.
500	`Failed to ...`	Provider/internal error.

Rule	Behavior
What counts	Connected call time, Twilio media stream, transcription, realtime tokens, and TTS.
Rounding	Total call charge is rounded up to the nearest whole credit.
Minimum charge	No separate fixed minimum fee. Rounded call total can still become 1 credit.
Queue wait	Queue/hold time counts once the call is connected.
Credit guard	Start-call may reject when balance is below required minimum.

Scenario	Typical credits
2-minute call with transcription + TTS	About 4 credits
8-minute queue + 2-minute conversation	About 10 credits
45-second short confirmation call	About 2 credits