openapi: 3.0.0 info: title: Jambonz API description: Jambonz REST API specification contact: email: daveh@drachtio.org license: name: MIT url: https://opensource.org/licenses/MIT version: 1.0.0 servers: - url: https://api.jambonz.cloud/v1 security: - bearerAuth: [] tags: - name: Calls description: Control Calls - name: Conferences description: Confernce Participants paths: /Accounts/{AccountSid}/Calls: post: tags: - Calls summary: create a call operationId: createCall parameters: - name: AccountSid in: path required: true schema: type: string requestBody: content: application/json: schema: required: - from - to type: object properties: application_sid: type: string format: uuid description: The application to use to control this call. Either application_sid or call_hook is required. answerOnBridge: type: boolean description: If set to true, the inbound call will ring until the number that was dialed answers the call, and at that point a 200 OK will be sent on the inbound leg. If false, the inbound call will be answered immediately as the outbound call is placed. example: false call_hook: $ref: '#/components/schemas/Webhook' example: url: https://example.com/callhook method: POST call_status_hook: $ref: '#/components/schemas/Webhook' example: url: https://example.com/status method: POST from: type: string description: The calling party number example: '16175551212' fromHost: type: string description: The hostname to put in the SIP From header of the INVITE example: sip.example.com timeout: type: integer description: The number of seconds to wait for call to be answered. Defaults to 60. example: 30 timeLimit: type: integer description: The max length of call in seconds example: 60 codecs: type: array items: type: string description: Codec names, in preference order, to offer on the outbound INVITE. Names are case-insensitive. When omitted the media server offers its default codecs. If any name is not supported the whole list is ignored, an error is logged and an alert is written, and default negotiation is used. example: ["G722", "PCMU"] tag: type: object description: Initial set of customer-supplied metadata to associate with the call (see jambonz 'tag' verb) example: callCount: 10 to: $ref: '#/components/schemas/Target' description: Destination for call headers: type: object description: The customer SIP headers to associate with the call example: X-Custom-Header: Hello sipRequestWithinDialogHook: type: string description: The sip indialog hook to receive session messages example: /customHook speech_synthesis_vendor: type: string description: The vendor for Text to Speech (required if application_sid is not used) example: google speech_synthesis_language: type: string description: The language for Text to Speech (required if application_sid is not used) example: en-US speech_synthesis_voice: type: string description: The voice for Text to Speech (required if application_sid is not used) example: Wavenet-A speech_recognizer_vendor: type: string description: The vendor for Speech to Text (required if application_sid is not used) example: google speech_recognizer_language: type: string description: The language for Speech to Text (required if application_sid is not used) example: en-US amd: $ref: '#/components/schemas/amd' noiseIsolation: $ref: '#/components/schemas/noiseIsolation' dual_streams: type: boolean description: >- If set to true, jambonz generates an outbound INVITE whose SDP offer contains two audio media streams (two `m=audio` lines) instead of one. This is useful when the far end (for example a carrier or recording system) requires the inbound and outbound audio to be delivered on separate RTP streams. Defaults to false. Supported only when creating a call via the REST API (i.e. not available from the `dial` verb). example: false responses: '201': description: call successfully created content: application/json: schema: required: - sid properties: sid: type: string format: uuid example: 2531329f-fb09-4ef7-887e-84e648214436 '400': description: bad request get: tags: - Calls summary: list calls operationId: listCalls parameters: - name: AccountSid in: path required: true schema: type: string - in: query name: direction required: false schema: type: string enum: - inbound - outbound description: call direction to retrieve - in: query name: from required: false schema: type: string description: calling number to retrieve - in: query name: to required: false schema: type: string description: called number to retrieve - in: query name: callStatus required: false schema: type: string enum: - trying - ringing - early-media - in-progress - completed - failed - busy - no-answer - queued description: call status to retrieve responses: '200': description: list of calls for a specified account content: application/json: schema: type: array items: $ref: '#/components/schemas/Call' '500': description: system error content: application/json: schema: $ref: '#/components/schemas/GeneralError' /Accounts/{AccountSid}/Calls/{CallSid}: parameters: - name: AccountSid in: path required: true style: simple explode: false schema: type: string - name: CallSid in: path required: true style: simple explode: false schema: type: string delete: tags: - Calls summary: delete a call operationId: deleteCall responses: '204': description: call successfully deleted '404': description: call not found '422': description: unprocessable entity content: application/json: schema: $ref: '#/components/schemas/GeneralError' '500': description: system error content: application/json: schema: $ref: '#/components/schemas/GeneralError' get: tags: - Calls summary: retrieve a call operationId: getCall responses: '200': description: call found content: application/json: schema: $ref: '#/components/schemas/Call' '404': description: call not found '500': description: system error content: application/json: schema: $ref: '#/components/schemas/GeneralError' put: tags: - Calls summary: update a call operationId: updateCall requestBody: content: application/json: schema: type: object properties: call_hook: $ref: '#/components/schemas/Webhook' child_call_hook: $ref: '#/components/schemas/Webhook' call_status: type: string enum: - completed - no-answer conf_mute_status: type: string enum: - mute - unmute conf_hold_status: type: string enum: - hold - unhold listen_status: type: string enum: - pause - silence - resume mute_status: type: string enum: - mute - unmute transcribe_status: type: string enum: - pause - resume whisper: oneOf: - type: object properties: verb: enum: - say - play description: See [Say](/verbs/verbs/say) or [Play](/verbs/verbs/play) for details of the properties - type: array items: type: object properties: verb: enum: - say - play description: See [Say](/verbs/verbs/say) or [Play](/verbs/verbs/play) for details of the properties sip_request: type: object properties: method: type: string content_type: type: string content: type: string headers: type: object record: type: object properties: action: type: string enum: - startCallRecording - stopCallRecording - pauseCallRecording - resumeCallRecording type: type: string default: siprec enum: - cloud - siprec recordingID: type: string description: used with startCallRecording and SIPREC siprecServerURL: type: string description: used with startCallRecording and SIPREC silence: type: boolean default: false description: when pausing recording the file will be padded with silence conferenceParticipantAction: type: object properties: action: type: string enum: - tag - untag - coach - uncoach - mute - unmute - hold - unhold tag: type: string dtmf: type: object properties: digit: type: string enum: - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" - "9" - "0" - "*" - "#" description: "Single digit to send" duration: type: integer default: 250 description: "Duration of the tone in ms" required: - digit stream_status: type: string description: Pause or resume an active stream verb. enum: - pause - silence - resume tag: type: object description: Set customer data tags on the call. Freeform key-value object. additionalProperties: true dub: type: object description: Add or remove additional audio tracks on the call. required: - action - track properties: action: type: string enum: - startDub - stopDub track: type: string description: Track name identifier. play: type: string description: Audio URL to play. say: type: object description: TTS configuration. loop: type: boolean description: Whether to loop playback. gain: type: number description: Gain in decibels. boostAudioSignal: description: Boost audio signal by specified decibels (e.g. 6 or "6dB"). oneOf: - type: number - type: string media_path: type: string description: Update the media path during an active Dial verb. enum: - no-media - partial-media - full-media noise_isolation_status: type: string description: Enable or disable noise isolation on the call. enum: - enable - disable noise_isolation_vendor: type: string description: Noise isolation vendor. Default is krisp. noise_isolation_level: type: number description: Noise isolation level 0-100. Default is 100. noise_isolation_model: type: string description: Noise isolation model identifier. agent_update: type: object description: Update an active agent verb mid-conversation. required: - type properties: type: type: string enum: - update_instructions - inject_context - update_tools - generate_reply description: The type of agent update to perform. instructions: type: string description: New system prompt (for update_instructions). messages: type: array description: Messages to append to conversation history (for inject_context). items: type: object required: - role - content properties: role: type: string enum: - user - assistant content: type: string tools: type: array description: Replacement tool definitions (for update_tools). items: type: object properties: name: type: string description: type: string parameters: type: object user_input: type: string description: Text to prompt the LLM with (for generate_reply). interrupt: type: boolean description: Whether to interrupt current assistant speech (for generate_reply). default: false responses: '200': description: Accepted '202': description: Accepted '400': description: bad request '404': description: call not found '422': description: unprocessable entity content: application/json: schema: $ref: '#/components/schemas/GeneralError' '500': description: system error content: application/json: schema: $ref: '#/components/schemas/GeneralError' /Accounts/{AccountSid}/Queues: parameters: - name: AccountSid in: path required: true schema: type: string format: uuid - in: query name: search required: false schema: type: string description: queue name of data to retrieve get: tags: - Queues summary: retrieve active queues for an account operationId: listQueues responses: '200': description: retrieve active queues records for a specified account content: application/json: schema: type: array items: type: object properties: name: type: string length: type: string /Accounts/{AccountSid}/Conferences: get: tags: - Conferences summary: list conferences operationId: listConferences parameters: - name: AccountSid in: path required: true schema: type: string - name: expand in: query required: false schema: type: string enum: - participants description: >- When set to "participants", returns live rooms with duration and per-member details (call_sid, label, memberTag) instead of a plain list of conference names. Only in-progress call legs are included. responses: '200': description: >- list of conferences for a specified account. A plain array of conference names by default; an array of ConferenceRoom objects when expand=participants. content: application/json: schema: oneOf: - type: array items: type: string - type: array items: $ref: '#/components/schemas/ConferenceRoom' '500': description: system error content: application/json: schema: $ref: '#/components/schemas/GeneralError' /Accounts/{AccountSid}/Conferences/{ConferenceName}/listen: parameters: - name: AccountSid in: path required: true schema: type: string - name: ConferenceName in: path required: true schema: type: string post: tags: - Conferences summary: start a conference listen fork description: >- Streams the conference's mixed audio (L16 PCM) to the supplied WebSocket URL. Addressed by conference name — no participant call leg is required. The fork is media-server-owned: it is excluded from participant counts, never keeps a room alive, and is torn down automatically when the conference ends. Starting a fork for a conference that already has one is idempotent and returns the existing bot member (200 rather than 201). operationId: startConferenceListen requestBody: content: application/json: schema: required: - url type: object properties: url: type: string description: ws(s):// URL the media server streams the room mix to example: wss://example.com/audio-sink sampleRate: type: integer description: PCM sample rate of the fork (e.g. 8000, 16000) example: 16000 wsAuth: type: object description: HTTP basic-auth credentials presented on the WebSocket connection properties: username: type: string password: type: string metadata: type: object description: >- Arbitrary JSON delivered verbatim as the fork's first text frame, so the receiving WebSocket can identify and configure itself responses: '201': description: listen fork started content: application/json: schema: type: object properties: botMemberId: type: integer description: conference member id of the fork bot botId: type: string '200': description: a listen fork is already active for this conference (idempotent) content: application/json: schema: type: object properties: botMemberId: type: integer botId: type: string '400': description: url is required '404': description: no such conference '502': description: the conference's home feature-server is unknown or unreachable delete: tags: - Conferences summary: stop a conference listen fork operationId: stopConferenceListen responses: '204': description: listen fork stopped '404': description: no active listen fork for this conference /Accounts/{AccountSid}/CallCount: get: tags: - Calls summary: get call count operationId: getCallCount parameters: - name: AccountSid in: path required: true schema: type: string responses: '200': description: count of active calls for an account content: application/json: schema: type: object properties: inbound: type: number description: Number of inbound calls to the platform example: 2 outbound: type: number description: Number of outbound calls to the platform example: 0 '400': description: error content: application/json: schema: $ref: '#/components/schemas/GeneralError' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: token schemas: ConferenceParticipant: type: object description: a live member of a conference (derived from in-progress call legs) properties: call_sid: type: string format: uuid description: call_sid of this member's leg (usable with updateCall, e.g. conferenceParticipantAction) label: type: string description: caller id when available, otherwise the bare number memberTag: type: string description: the member's conference tag (empty string when untagged) isAgent: type: boolean description: convenience flag, true when memberTag is "agent" required: - call_sid - label - memberTag - isAgent ConferenceRoom: type: object description: a live conference with its participants (expand=participants) properties: id: type: string description: conference name (account-scoped) name: type: string description: conference name durationSec: type: integer description: seconds since the conference started participants: type: array items: $ref: '#/components/schemas/ConferenceParticipant' required: - id - name - durationSec - participants GeneralError: type: object required: - msg properties: msg: type: string example: msg: specific error detail will be provided here Webhook: type: object properties: webhook_sid: type: string format: uuid url: type: string format: url method: type: string enum: - get - post username: type: string password: type: string required: - url example: url: https://acme.com method: POST Call: type: object properties: account_sid: type: string format: uuid application_sid: type: string format: uuid call_id: type: string call_sid: type: string format: uuid call_status: type: string enum: - trying - ringing - alerting - in-progress - completed - busy - no-answer - failed - queued caller_name: type: string direction: type: string enum: - inbound - outbound duration: type: integer from: type: string originating_sip_trunk_name: type: string parent_call_sid: type: string format: uuid service_url: type: string sip_status: type: integer to: type: string required: - account_sid - call_id - call_sid - call_status - direction - from - service_url - sip_status - to Target: properties: type: type: string enum: - phone - sip - user - teams number: type: string description: A phone number to call (when type is phone) sipUri: type: string description: A SIP URI to call (when type is sip) tenant: type: string description: Microsoft Teams customer tenant domain name (when type is teams) trunk: type: string description: The name of the Carrier that should be used to deliver this call (when type is phone) vmail: type: boolean description: Dial directly into user's voicemail to leave a message (MS Teams only) overrideTo: type: string description: A SIP URI that, if provided, will be used as the To header in the outbound INVITE (not needed in most cases) name: type: string description: The name of a registered jambonz user to call (when type is user) auth: type: object properties: username: type: string description: The username to use for SIP authentication, if challenged password: type: string description: The password to use for SIP authentication, if challenged proxy: type: string description: SIP Proxy to use for the outgoing INVITE example: sip:192.0.0.1:5080 required: - type example: type: phone number: '+16172375080' amd: type: object properties: actionHook: type: string description: Webhook to send AMD events. thresholdWordCount: type: number description: Number of spoken words in a greeting that result in an amd_machine_detected result. digitCount: type: number description: Number of digits in a greeting to trigger a amd_machine_detected result. 0 is off timers: type: object properties: decisionTimeoutMs: type: number default: 15000 description: Time in milliseconds to wait before returning amd_decision_timeout. greetingCompletionTimeoutMs: type: number default: 2000 description: Silence in milliseconds to wait for during greeting before returning amd_machine_stopped_speaking. noSpeechTimeoutMs: type: number default: 5000 description: Time in milliseconds to wait for speech before returning amd_no_speech_detected. toneTimeoutMs: type: number default: 20000 description: Time in milliseconds to wait to hear a tone. noiseIsolation: type: object description: >- Enable server-side noise isolation on the call at answer time, before any callHook verbs run. Useful for cleaning the far-end audio ahead of answering machine detection on noisy outbound calls. Applied to the read (far-end/inbound) stream by default. properties: enable: type: boolean default: true description: Set to false to disable; the object's presence otherwise enables it. example: true vendor: type: string default: krisp description: Noise isolation vendor. example: krisp direction: type: string enum: - read - write default: read description: >- 'read' filters far-end/inbound audio (default, correct for AMD on outbound calls); 'write' filters audio sent to the far end. example: read level: type: number default: 100 description: Suppression level 0-100. example: 100 model: type: string description: Optional model name/path override.