API-dokumentation | CallMyCall Utvecklare

Endpoints

Kärnendpoints

POST /v1/start-call

Starta ett utgående AI-samtal.

Fält / parameter	Typ	Krävs	Beskrivning
`phone_number`	string	ja	Who to call. Must be E.164 format (for example +46700000000).
`task`	string	ja	What the AI should do/say on this call (your main instruction).
`userPhone`	string	villkorligt	Phone number of your human operator/user (E.164) who will be added to the call once the call has connected. Used with userOnCall where AI and user are on the call flow at the same time.
`additionalPrompt`	string	nej	Extra instructions appended to task. Default: empty string.
`language`	string	nej	Language code (e.g. sv/en/de) for the language the AI will speak. Default: sv (normalized aliases supported).
`tts_provider`	string	nej	Which TTS engine to use: auto \| openai \| elevenlabs \| azure. If omitted, auto is used (Swedish -> ElevenLabs, English -> OpenAI).
`voice_gender`	string	nej	Voice gender selector for defaults. Allowed: female \| male (alias: voiceGender). Defaults to male when omitted. Used to auto-select default OpenAI + ElevenLabs voices when explicit voice IDs are not provided.

Förfrågningsexempel (cURL)

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","voice_gender":"female","webhook":"https://example.com/cmc"}'

Lyckat svar

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

Felsvar

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

GET /v1/calls/:callId

Hämta samtalsdetaljer och senaste transkript via call id/sid.

Fält / parameter	Typ	Krävs	Beskrivning
`callId`	string	ja	Call SID from start-call response.

Förfrågningsexempel (cURL)

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

Lyckat svar

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

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

Prenumerera på realtime-transkriptuppdateringar via Server-Sent Events.

Fält / parameter	Typ	Krävs	Beskrivning
`callId`	string	ja	Call SID from start-call response.

Förfrågningsexempel (cURL)

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

Exempel på stream-eventpayload

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

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

GET /v1/calls/:callSid/recording

Hämta signerad inspelnings-URL för avslutade samtal (om inspelning aktiverad).

Fält / parameter	Typ	Krävs	Beskrivning
`format`	string	nej	Audio format for signed URL. Allowed: mp3 or wav. Default: mp3.

Förfrågningsexempel (cURL)

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

Lyckat svar

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

Felsvar

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

POST /v1/verify-caller-id

Starta verifiering av caller ID för anpassad from_number-användning.

Fält / parameter	Typ	Krävs	Beskrivning
`phone_number`	string	ja	E.164 number to verify.

Förfrågningsexempel (cURL)

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"}'

GET /v1/verification-status/:id

Kontrollera verifieringsstatus (pending, verified, failed).

Förfrågningsexempel (cURL)

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

GET /v1/verified-caller-ids

Lista verifierade caller IDs för din API-nyckel/ditt konto.

Förfrågningsexempel (cURL)

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

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

Ta bort ett verifierat caller ID som ägs av din API-nyckel.

Förfrågningsexempel (cURL)

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

POST /v1/webhook/test

Skicka en syntetisk webhook-payload till din endpoint.

Fält / parameter	Typ	Krävs	Beskrivning
`webhook_url`	string	ja	HTTPS URL to receive test event.
`event`	string	nej	Defaults to call_completed.

Förfrågningsexempel (cURL)

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"}'

GET /auth/google/calendar

Starta Google Calendar OAuth-auktoriseringsflöde.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key. You may also pass api_key as query param, but header is recommended.
`format`	query string	nej	Set format=json to receive auth_url in JSON instead of HTTP redirect.

Förfrågningsexempel (cURL)

curl -X GET "https://call-my-call-backend.fly.dev/auth/google/calendar?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Lyckat svar

{
  "success": true,
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "state": "a1b2c3..."
}

Felsvar

{
  "error": "Failed to initiate calendar authorization",
  "details": "API key required for calendar authorization"
}

GET /auth/google/callback

OAuth-callback efter Google-samtycke; öppnas vanligtvis via webbläsarredirect.

Fält / parameter	Typ	Krävs	Beskrivning
`code`	query string	ja	OAuth authorization code from Google.
`state`	query string	ja	State value from /auth/google/calendar to prevent CSRF.
`error`	query string	nej	If user denied consent, Google returns error instead of code.

Förfrågningsexempel (cURL)

curl -X GET "https://call-my-call-backend.fly.dev/auth/google/callback?code=GOOGLE_CODE&state=OAUTH_STATE"

Lyckat svar

<!DOCTYPE html>
<html>...Calendar Authorization Successful...</html>

Felsvar

{
  "error": "Invalid or expired authorization request"
}

GET /calendar/status

Kontrollera om API-nyckeln har aktiv Google Calendar-auktorisering.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key.

Förfrågningsexempel (cURL)

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

Lyckat svar

{
  "authorized": true,
  "scopes": ["https://www.googleapis.com/auth/calendar"],
  "expires_at": "2026-02-16T20:00:00.000Z"
}

Felsvar

{
  "error": "Failed to check calendar authorization status",
  "details": "..."
}

POST /auth/google/revoke

Återkalla Google Calendar-auktorisering för API-nyckeln.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key.

Förfrågningsexempel (cURL)

curl -X POST https://call-my-call-backend.fly.dev/auth/google/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

Lyckat svar

{
  "success": true,
  "message": "Calendar authorization revoked successfully"
}

Felsvar

{
  "error": "Failed to revoke calendar authorization",
  "details": "..."
}

GET /v1/recordings/:sid.:ext

Strömma inspelningsbytes via signerad kortlivad token-URL.

Fält / parameter	Typ	Krävs	Beskrivning
`sid`	string	ja	Recording SID.
`ext`	string	ja	mp3 or wav.
`token`	string	ja	Signed token query parameter.

Förfrågningsexempel (cURL)

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

POST /v1/elevenlabs/voices

Proxy-endpoint för ElevenLabs röstkloning via multipart-uppladdning.

Fält / parameter	Typ	Krävs	Beskrivning
`name`	string	ja	Voice name label.
`files`	file[]	ja	One or more audio sample files.
`remove_background_noise`	boolean	nej	Noise removal hint for cloning.

Förfrågningsexempel (cURL)

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"

Endpoints för pågående samtal

POST /v1/end-call

Avsluta ett aktivt samtal.

Fält / parameter	Typ	Krävs	Beskrivning
`callSid`	string	ja	Call SID returned by start-call (the call you want to end).

Förfrågningsexempel (cURL)

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"}'

Lyckat svar

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

Felsvar

{
  "error": "Missing callSid"
}

POST /v1/calls/:callSid/transfer

Överför ett aktivt samtal till en annan destination.

Fält / parameter	Typ	Krävs	Beskrivning
`destination`	string	ja	Where to transfer the active call (E.164 phone number).
`warm`	boolean	nej	Transfer mode. true = warm transfer (default), false = cold transfer.
`reason`	string	nej	Optional note for audit/logging (not spoken to caller).

Förfrågningsexempel (cURL)

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"}'

Lyckat svar

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

PATCH /v1/calls/:callSid

Uppdatera parametrar för aktivt samtal medan samtalet pågår.

Fält / parameter	Typ	Krävs	Beskrivning
`task`	string	nej	Replace current AI task for this active call.
`transfer_number`	string	nej	Update transfer destination for this active call (E.164).
`additional_prompt`	string	nej	Append extra instructions to current prompt context.
`max_duration`	number	nej	Update maximum connected duration (seconds).

Förfrågningsexempel (cURL)

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"}'

User-on-call-endpoints

POST /v1/calls/:callSid/activate

Aktivera AI-övertagning för user-on-call-sessioner.

Fält / parameter	Typ	Krävs	Beskrivning
`task`	string	nej	New instruction for AI at takeover time. If omitted, existing task is used.
`drop_user`	boolean	nej	Whether to disconnect the human user when AI takes over. Default: true.
`additional_prompt`	string	nej	Extra instruction appended during activation.
`transfer_number`	string	nej	Overrides/sets the handoff destination used by transfer logic during AI phase.

Förfrågningsexempel (cURL)

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}'

Lyckat svar

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

Felsvar

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

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

Hämta user-on-call-konferensens tillstånd och deltagare.

Förfrågningsexempel (cURL)

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

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

Koppla bort användarbenet från en user-on-call-session.

Förfrågningsexempel (cURL)

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

Kalenderautentiseringsendpoints

Kalenderautentiseringsflöde

För samtal med enable_calendar=true, auktorisera en gång per API-nyckel: starta OAuth, godkänn samtycke, verifiera status och återkalla vid behov.

GET /auth/google/calendar

Starta Google Calendar OAuth-auktoriseringsflöde.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key. You may also pass api_key as query param, but header is recommended.
`format`	query string	nej	Set format=json to receive auth_url in JSON instead of HTTP redirect.

Förfrågningsexempel (cURL)

curl -X GET "https://call-my-call-backend.fly.dev/auth/google/calendar?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Lyckat svar

{
  "success": true,
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "state": "a1b2c3..."
}

Felsvar

{
  "error": "Failed to initiate calendar authorization",
  "details": "API key required for calendar authorization"
}

GET /auth/google/callback

OAuth-callback efter Google-samtycke; öppnas vanligtvis via webbläsarredirect.

Fält / parameter	Typ	Krävs	Beskrivning
`code`	query string	ja	OAuth authorization code from Google.
`state`	query string	ja	State value from /auth/google/calendar to prevent CSRF.
`error`	query string	nej	If user denied consent, Google returns error instead of code.

Förfrågningsexempel (cURL)

curl -X GET "https://call-my-call-backend.fly.dev/auth/google/callback?code=GOOGLE_CODE&state=OAUTH_STATE"

Lyckat svar

<!DOCTYPE html>
<html>...Calendar Authorization Successful...</html>

Felsvar

{
  "error": "Invalid or expired authorization request"
}

GET /calendar/status

Kontrollera om API-nyckeln har aktiv Google Calendar-auktorisering.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key.

Förfrågningsexempel (cURL)

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

Lyckat svar

{
  "authorized": true,
  "scopes": ["https://www.googleapis.com/auth/calendar"],
  "expires_at": "2026-02-16T20:00:00.000Z"
}

Felsvar

{
  "error": "Failed to check calendar authorization status",
  "details": "..."
}

POST /auth/google/revoke

Återkalla Google Calendar-auktorisering för API-nyckeln.

Fält / parameter	Typ	Krävs	Beskrivning
`Authorization`	header	ja	Bearer API key.

Förfrågningsexempel (cURL)

curl -X POST https://call-my-call-backend.fly.dev/auth/google/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

Lyckat svar

{
  "success": true,
  "message": "Calendar authorization revoked successfully"
}

Felsvar

{
  "error": "Failed to revoke calendar authorization",
  "details": "..."
}

User-on-call förklarat

Använd userOnCall: true när AI ska vänta genom IVR/köflöde tills en verklig människa svarar, medan din operatör kan stanna kvar i samtalet och trigga AI-övertagning via /activate vid rätt tillfälle.

Fas	Vem hör vad
`Före activate`	Användare och mål är uppkopplade. AI kan vara tyst/lyssna.
`Activate anropad`	Backend omdirigerar målbenet till AI realtime-ström. Om `drop_user=true`, kopplas användarbenet bort.
`Efter activate`	AI hanterar live-samtalet (inklusive kö-/IVR-progression). Om `drop_user=true` and `transfer_number` är satt kan AI återansluta/överföra samtalet till det numret när överföringslogik triggas.

Typisk API-sekvens:

1) POST /v1/start-call { userOnCall: true, userPhone, ... }
2) Wait until call is connected
3) POST /v1/calls/:callSid/activate { drop_user?: true|false, task?: string }
4) Optional: GET /v1/calls/:callSid/conference-status
5) Optional: POST /v1/calls/:callSid/drop-user

Vanliga fel: samtal hittades inte/inte user-on-call-session (404), AI redan aktiv (400), Twilio redirect/connect-problem (500).

Tillståndsmodell för user-on-call

Tillstånd	Beteende	Nästa
`initiated`	Mål- och användarben ringes upp.	`connected` or `failed`
`connected`	Användare och mål pratar medan AI kan lyssna tyst.	`ai_takeover` or `completed`
`ai_takeover`	`/activate` omdirigerar samtal till AI realtime-ström.	`active`
`active`	AI hanterar kö/IVR + samtalsflöde; den kan överföra till `transfer_number` baserat på uppgift/logik.	`transferred` or `completed`
`completed`	Samtalet avslutas och completion-webhook triggas.	-

Webhooks

Sätt webhook och valfri webhook_events i start-call-payloaden.

Händelse	När	Noteringar
`call_started`	Realtime-ström startar	Best-effort-signal
`transcript_updated`	Nya transkriptsegment	Kan triggas flera gånger
`price_updated`	Prisberikning efter samtal	Kan komma efter avslut
`call_completed`	Samtalet stängs	Standard om eventlista utelämnas

Exempel på webhook-payload

{
  "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
      }
    ]
  }
}

Leveranskontrakt	Nuvarande beteende
Lyckat villkor	Alla HTTP 2xx-svar.
Ombesök	Upp till 3 försök totalt.
Retry-policy	Försök igen vid nätverksfel och 5xx. Ingen retry på 4xx.
Backoff	600 ms och sedan 1200 ms mellan retries.
Request-timeout	10 sekunder per försök.
Signatur	`X-Callmycall-Signature: t=TIMESTAMP,v1=HMAC_SHA256` när signeringshemlighet är konfigurerad.

HTTP	Omfång	Exempel	Orsak
400	Endpointspecifikt	`Missing phone_number`	Validering misslyckades för den endpointens payload.
401	Globalt	`Authorization header with API key is required`	Saknad/ogiltig API-nyckel eller Firebase-auth-token.
402	Globalt (faktureringsstyrda endpoints)	`Subscription inactive` / `Insufficient credits`	Faktureringskontroll misslyckades före samtalsexekvering.
404	Endpointspecifikt	`Call not found`	Okänd SID/resurs-id, eller resursen är redan stängd.
429	Globalt	`Too Many Requests`	Rate limit överskriden; använd klient-backoff och försök igen.
500	Globalt	`Failed to ...`	Leverantörs-/internt fel vid hantering av requesten.

Regel	Beteende
Vad som räknas	Uppkopplad samtalstid, Twilio-medieström, transkribering, realtime-tokens och TTS.
Avrundning	Total samtalskostnad avrundas upp till närmaste hela kredit.
Minimiavgift	Ingen fast minimiavgift. Avrundade totaler kan ändå bli 1 kredit.
Köväntan	Kö-/väntetid räknas när samtalet är uppkopplat.
Kreditspärr	Start-call kan nekas när saldot är under minimum.

Scenario	Typiska krediter
2-minuterssamtal med transkribering + TTS	Cirka 4 krediter
8-minuters kö + 2-minuters samtal	Cirka 10 krediter
45-sekunders kort bekräftelsesamtal	Cirka 2 krediter