Module

Telefonie

Das Telefonie-Modul verbindet Codemeta OS mit der hauseigenen PBX. Calls werden mit Tickets verknüpft, Audio kann aufgezeichnet, transkribiert und durch eine KI zusammengefasst werden.

Resources – Calls

Resource	Pfad	Permission-Präfix	Sequenz
Phone-Calls	`/api/v1/phone_calls`	`phone_call`	`CALL-`
Call-Notes	`/api/v1/call_notes`	`call_note`	—

Aufzeichnung, Transkript und KI-Summary liegen als typisierte Felder direkt am phone_call-Datensatz — keine separaten Sub-Resources.

Resources – PBX-Konfiguration

Resource	Pfad	Permission-Präfix
Extensions	`/api/v1/pbx_extensions`	`pbx_extension`
Queues	`/api/v1/pbx_queues`	`pbx_queue`
Konferenz-Räume	`/api/v1/pbx_conference_rooms`	`pbx_conference_room`
Voicemails	`/api/v1/pbx_voicemails`	`pbx_voicemail`
Aufzeichnungen	`/api/v1/pbx_recordings`	`pbx_recording`

Custom-Endpoints (`/api/v1/telephony/...`)

Über CRUD hinaus gibt es dedizierte Telephony-Endpoints für Live-Steuerung und PBX-Operationen. Auszug:

Operation	Hinweis
`POST /api/v1/telephony/click-to-call`	Outbound-Call vom UI initiieren
`POST /api/v1/telephony/calls/<id>/answer`	Inbound annehmen
`POST /api/v1/telephony/calls/<id>/transfer`	Weiterleiten
`POST /api/v1/telephony/calls/<id>/hold`	Halten / Fortsetzen
`GET /api/v1/telephony/queues`	Aktive Queues
`POST /api/v1/telephony/queues/<id>/join`	Agent betritt Queue
`POST /api/v1/telephony/queues/<id>/leave`	Agent verlässt Queue

Die vollständige, immer aktuelle Liste finden Sie in der OpenAPI-Spec.

Schemas

Phone-Call

phone_calls4 Permissions

Schema for phone call records including PBX integration data

direction string erforderlich

Call direction

Werte

INBOUNDOUTBOUND

callerNumber string erforderlich

Phone number of the caller

calledNumber string erforderlich

Phone number that was called

durationSeconds number erforderlich

Total call duration in seconds

≥ 0

partyId uuid optional

Linked party (customer/contact)

nullable

contactPartyId uuid optional

Linked contact person

nullable

handledById uuid optional

User who handled the call

nullable

rungUserIds uuid[] optional

Users whose phone rang during this call. Populated for inbound PBX calls (Starface CALLFLOW with CALLED_TYPE=USER) so missed calls show up under "my calls" for everyone whose extension rang, not just the (non-existent) handler.

ticketId uuid optional

Linked ticket

nullable

note string optional

Free-text note about the call

nullable

isCallbackRequested boolean erforderlich

Whether a callback was requested

startedAt datetime erforderlich

When the call started (ISO 8601)

endedAt datetime optional

When the call ended (ISO 8601)

nullable

callerName string optional

Caller name from PBX

nullable

calledName string optional

Called party name from PBX

nullable

callerAccountId number optional

PBX account ID of the caller (-1 for external)

nullable

isConnected boolean erforderlich

Whether the call was answered

isInternalCall boolean erforderlich

Whether this was an internal call

isPickup boolean erforderlich

Whether the call was picked up by another user

externalCallUuid string optional

External PBX call UUID (e.g. Starface CALL_UUID)

nullable

source string optional

Source of the call record

Werte

manualstarfaceteamsfreeswitch

nullable

teamsCallId string optional

Microsoft Graph call record ID

nullable

teamsCallType string optional

Teams call type: peer-to-peer calling or group meeting

Werte

callingmeeting

nullable

teamsMeetingUrl string optional

Teams meeting join URL (for meeting-type calls)

nullable

teamsParticipants object[] optional

Teams call participants

nullable

displayName string erforderlich

userPrincipalName string optional

nullable

microsoftUserId string optional

nullable

internalUserId string optional

nullable

teamsModalities string[] optional

Communication modalities used (audio, video, screen share)

nullable

callFlow object[] optional

Detailed call routing steps from PBX

nullable

index integer erforderlich

calledType string erforderlich

Werte

USERGROUPMODULEUNKNOWN

calledName string erforderlich

calledNumber string erforderlich

calledAccountId string optional

nullable

connected boolean erforderlich

forwardType string erforderlich

timeStart number erforderlich

timeEnd number erforderlich

pickup boolean erforderlich

pickupFirstName string optional

nullable

pickupLastName string optional

nullable

pickupAccountId number optional

nullable

pickupTime number optional

nullable

pickupLoginId string optional

nullable

moduleInfo string optional

nullable

agentInfo object[] optional

nullable

accountId string erforderlich

online boolean erforderlich

busy boolean erforderlich

dnd boolean erforderlich

ringing boolean erforderlich

waitTimeMs number optional

Time the caller waited before pickup or abandonment (INBOUND only)

≥ 0nullable

rawWebhookData object optional

Raw webhook payload for future analysis

nullable

bookedAsTimeRecordId uuid optional

Time record ID created from this call (marks call as booked)

nullable

pbxCallId string optional

FreeSWITCH call UUID

nullable

sipTrunkId uuid optional

SIP trunk used

nullable

extensionId uuid optional

Extension that handled the call

nullable

queueId uuid optional

ACD queue if routed through queue

nullable

recordingFileId uuid optional

pbx_recording entity ID

nullable

transcriptText string optional

Call transcript from STT

nullable

aiSummary string optional

AI-generated call summary

nullable

sentimentScore number optional

Sentiment score -1 (negative) to 1 (positive)

-1 – 1nullable

Note

call_notes4 Permissions

note string erforderlich

1–10000 Zeichen

phoneNumber string optional

max 50 ZeichenDefault: nullnullable

partyId uuid optional

Default: nullnullable

contactPartyId uuid optional

Default: nullnullable

phoneCallId uuid optional

Default: nullnullable

Extension

pbx_extensions4 Permissions

Schema for a user extension (one per user) in the FreeSWITCH PBX module

extensionNumber string erforderlich

Internal extension number (1–6 digits)

Pattern

displayName string erforderlich

Display name shown in calls and directory

1–200 Zeichen

userId uuid optional

UUID of the linked user account

nullable

sipUser string optional

Auto-generated SIP username for FreeSWITCH registration (protected field)

read-onlynullable

voicemailEnabled boolean optional

Whether voicemail is enabled for this extension

nullable

voicemailPin string optional

Voicemail PIN (4–6 digits)

Patternnullable

doNotDisturb boolean optional

Do Not Disturb flag — all calls go directly to voicemail when enabled

nullable

forwardEnabled boolean optional

Whether call forwarding is active for this extension

nullable

forwardTarget string optional

Target number or extension for call forwarding

nullable

forwardType string optional

When to apply call forwarding

Werte

UNCONDITIONALBUSYNO_ANSWER

nullable

callRecordingEnabled boolean optional

Whether calls on this extension are automatically recorded

nullable

ringTimeout integer optional

Seconds to ring before going to voicemail or forwarding

5 – 120nullable

isActive boolean optional

Whether this extension is active in FreeSWITCH

nullable

Queue

pbx_queues4 Permissions

Schema for an ACD (Automatic Call Distribution) call queue in the FreeSWITCH PBX module

name string erforderlich

Human-readable name for this queue

1–200 Zeichen

extensionNumber string erforderlich

Extension number callers dial to reach this queue

strategy string optional

Agent ring strategy for distributing incoming calls

Werte

RING_ALLROUND_ROBINLEAST_RECENTFEWEST_CALLSRANDOMLINEARBROADCAST

Default: "RING_ALL"nullable

maxWaitSeconds integer optional

Maximum time in seconds a caller waits before being removed from the queue

≥ 0nullable

maxQueueSize integer optional

Maximum number of callers that can be queued at once

≥ 1nullable

announcePosition boolean optional

Whether to announce the caller's position in the queue

nullable

announceFrequency integer optional

How often (in seconds) to announce position/wait time

≥ 10nullable

musicOnHold string optional

Music-on-hold class or audio file reference

nullable

welcomePrompt string optional

Audio file key played when caller enters the queue

nullable

memberExtensionIds string[] optional

List of pbx_extension IDs (UUIDs) that are members of this queue

nullable

wrapUpSeconds integer optional

Seconds an agent has after a call ends before receiving another (wrap-up time)

≥ 0nullable

isActive boolean optional

Whether this queue is active in FreeSWITCH

nullable

ringTimeoutPerMember integer optional

Seconds to ring each member before moving to the next (LINEAR strategy)

5 – 120nullable

fallbackAction string optional

Action when all members exhausted or max wait time reached

Werte

VOICEMAILIVRQUEUEHANGUPFORWARD

nullable

fallbackTarget string optional

Target for fallback action (extension, IVR ID, queue ID, or external number)

nullable

pagingMode boolean optional

When true with BROADCAST strategy, members auto-answer for one-way paging

nullable

Conference-Room

pbx_conference_rooms4 Permissions

Schema for a conference room in the FreeSWITCH PBX module

name string erforderlich

Human-readable name for this conference room

1–200 Zeichen

extensionNumber string erforderlich

Extension number to dial into this conference room

Pattern

pin string optional

Optional PIN code for room access

Patternnullable

maxParticipants integer optional

Maximum number of concurrent participants

2 – 100nullable

recordingEnabled boolean optional

Whether to auto-record the conference

nullable

profile string optional

FreeSWITCH conference audio profile

Werte

defaultwidebandultrawideband

nullable

isActive boolean optional

Whether this conference room is active

nullable

Voicemail

pbx_voicemails4 Permissions

Schema for a voicemail message left on a PBX extension

extensionId uuid erforderlich

UUID of the pbx_extension this voicemail was left on

callerNumber string erforderlich

Phone number of the caller who left the voicemail

durationSeconds number erforderlich

Duration of the voicemail message in seconds

≥ 0

fileKey string erforderlich

S3/MinIO object key where the voicemail audio file is stored (protected field)

read-only

isRead boolean erforderlich

Whether this voicemail has been listened to / marked as read

callerName string optional

Caller name resolved from PBX directory or CRM

nullable

transcriptText string optional

Full transcript text generated by speech-to-text (STT)

nullable

transcriptStatus string optional

Current status of the transcription job

Werte

PENDINGPROCESSINGDONEFAILED

nullable

partyId uuid optional

UUID of the linked party (customer/contact) resolved from the caller number

nullable

phoneCallId uuid optional

UUID of the phone_call entity associated with this voicemail

nullable

Recording

pbx_recordings4 Permissions

Schema for a call recording entity created by the FreeSWITCH PBX module

phoneCallId uuid erforderlich

UUID of the phone_call entity this recording belongs to

direction string erforderlich

Direction of the recorded call

Werte

INBOUNDOUTBOUND

durationSeconds number erforderlich

Duration of the recording in seconds

≥ 0

fileKey string erforderlich

S3/MinIO object key where the recording file is stored (protected field)

read-only

consentGiven boolean erforderlich

Whether explicit consent was obtained before recording (required for GDPR compliance)

fileSize number optional

File size in bytes

≥ 0nullable

transcriptText string optional

Full transcript text generated by speech-to-text (STT)

nullable

transcriptStatus string optional

Current status of the transcription job

Werte

PENDINGPROCESSINGDONEFAILED

nullable

deletedAfter datetime optional

Retention date — the recording will be deleted after this timestamp (ISO 8601)

nullable

partyId uuid optional

UUID of the linked party (customer/contact)

nullable

extensionId uuid optional

UUID of the pbx_extension that participated in this recording

nullable

format string optional

Audio file format of the recording

Werte

WAVMP3OGG

nullable

Recording / Transcript / Summary

Aufzeichnungen sind Opt-in pro Call. Sobald eine Aufnahme abgeschlossen ist, verarbeitet die Plattform sie automatisch zu Transkript und KI-Summary — beide Felder werden direkt am phone_call gepflegt.

Verwandt

Konventionen
Tickets — Calls werden Tickets zugeordnet

Telefonie

Resources – Calls

Resources – PBX-Konfiguration

Custom-Endpoints (/api/v1/telephony/...)

Schemas

Recording / Transcript / Summary

Verwandt

Custom-Endpoints (`/api/v1/telephony/...`)