Class FreeSwitchClient

FreeSwitchClient is the class you use to create a new client. It will automatically reconnect.

const client = new FreeSwitchClient({ logger: pino.default() })
const res = await client.bgapi('sofia status', 1000)
console.log('sofia status is', res)

Hierarchy (View Summary)

FreeSwitchResponse
- FreeSwitchClient

Index

Constructors

constructor

new FreeSwitchClient(
    options: {
        host?: string;
        logger: Logger;
        password?: string;
        port?: number;
    },
): FreeSwitchClient
Parameters
- options: { host?: string; logger: Logger; password?: string; port?: number }
Returns FreeSwitchClient
Overrides FreeSwitchResponse.constructor
- Defined in src/client.ts:22

Properties

`Readonly`custom

custom: FreeSwitchEventEmitter<
string,
Record<string, (data: FreeSwitchEventData) => void>,
>

Event emitter for custom events

this.custom.on('conference::maintenance', (data) => {
})

`Readonly`logs

logs: FreeSwitchEventEmitter<
"log",
{ log: (data: FreeSwitchParserData) => void },
> = ...

EventEmitter for log events You must use client.log() beforehand to specify the log level.

`Readonly`ref

ref: string = ...

Uniquely identify each instance, for tracing purposes.

stats

stats: {
    apiResponses: bigint;
    authRequest: bigint;
    bodyParseErrors: bigint;
    commandReply: bigint;
    disconnect: bigint;
    events: bigint;
    logData: bigint;
    missingContentType: bigint;
    missingEventName: bigint;
    nonEmptyBufferAtEnd: bigint;
    rudeRejections: bigint;
    unflushedWrites: bigint;
    unhandled: bigint;
} = ...

Statistics about this connection

Type declaration

apiResponses: bigint
Number of api responses
authRequest: bigint
Number of authentication requests
bodyParseErrors: bigint
Number of body parse errors
commandReply: bigint
Number of command replies
disconnect: bigint
Number of disconnect event received
events: bigint
Number of FreeSwitch events received
logData: bigint
Number of log data events received
missingContentType: bigint
Number of missing Content-Type headers
missingEventName: bigint
Number of missing Event-Name headers
nonEmptyBufferAtEnd: bigint
Number of unexpected non-empty buffer at end of processing.
rudeRejections: bigint
Number of rude rejections (generally due to ACL access to the Event Socket)
unflushedWrites: bigint
Number of unflushed writes, indicating the network or FreeSwitch are not keeping up with our traffic
unhandled: bigint
Number of unhandled events

Methods

bgapi

bgapi(
    command: string,
    timeout: number,
): Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
Send an API command in the background. Await the command's result.

bgapi will return an error if the job submission fails.

It will not return an error if the bakcground job itself failed. The response from the background job will be stored in the .body.response field of the return value.

The timeout parameter should encompass job submission and the command completion.

This method is not expected to throw / return a rejected Promise.
Parameters
- command: string
- timeout: number
Returns Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
Inherited from FreeSwitchResponse.bgapi
- Defined in src/response.ts:56

command_uuid

command_uuid(
    uuid: string,
    appName: string,
    appArg?: string,
    timeout: number,
): Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
Execute an application synchronously on a channel. Await the result.

Check the result's response field to know the outcome of a command. The first character indicates success (+) or failure (-).

If you would like an async version, use execute_uuid.

This method is not expected to throw / return a rejected Promise.
Parameters
- uuid: string
- appName: string
- appArg: string = ''
- timeout: number
Returns Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
Inherited from FreeSwitchResponse.command_uuid
- Defined in src/response.ts:224

`Protected`connect

connect(): Promise<void>
Returns Promise<void>
Inherited from FreeSwitchResponse.connect
- Defined in src/response.ts:431

emit

emit<K extends keyof FreeSwitchPublicResponseEvents>(
event: K,
arg: Parameters<FreeSwitchPublicResponseEvents[K]>[0],
): boolean
Send out an event: all registered callbacks are notified.
Type Parameters
- K extends keyof FreeSwitchPublicResponseEvents
Parameters
- event: K
- arg: Parameters<FreeSwitchPublicResponseEvents[K]>[0]
Returns boolean
Inherited from FreeSwitchResponse.emit
- Defined in src/event-emitter.ts:30

end

end(): void
End this instance.

Returns void
Inherited from FreeSwitchResponse.end
- Defined in src/response.ts:90

execute_uuid

execute_uuid(
    uuid: string,
    appName: string,
    appArg: string,
    headers: {
        "content-type"?: string;
        "event-uuid"?: string;
        "event-uuid-name"?: string;
        "hold-bleg"?: boolean;
        loops?: number;
    },
    timeout: number,
): SendResult
Execute an application for the given UUID (channel). Does not await the result. event-uuid and event-uuid-name are set as app_uuid and app_uuid_name in the channel, respectively.

If you would like to await the result, use command_uuid.

This method is not expected to throw / return a rejected Promise.
Parameters
- uuid: string
- appName: string
- appArg: string
- headers: {
      "content-type"?: string;
      "event-uuid"?: string;
      "event-uuid-name"?: string;
      "hold-bleg"?: boolean;
      loops?: number;
  }
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.execute_uuid
- Defined in src/response.ts:188

hangup_uuid

hangup_uuid(uuid: string, hangupCause?: string, timeout: number): SendResult
Hangup the call referenced by the given UUID with an optional (FreeSwitch) cause code.

This method is not expected to throw / return a rejected Promise.
Parameters
- uuid: string
- hangupCause: string = 'NORMAL_UNSPECIFIED'
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.hangup_uuid
- Defined in src/response.ts:261

log

log(level: number, timeout: number): SendResult
Enable logging on the socket, setting the log level.
```
client.log(7)
client.logs.on('log', (data) => { … })
```
This method is not expected to throw / return a rejected Promise.
Parameters
- level: number
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.log
- Defined in src/response.ts:125

nolog

nolog(timeout: number): SendResult
Disable logging on the socket.

This method is not expected to throw / return a rejected Promise.
Parameters
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.nolog
- Defined in src/response.ts:138

on

on<K extends keyof FreeSwitchPublicResponseEvents>(
event: K,
handler: FreeSwitchPublicResponseEvents[K],
): this
Register a new callback for the named event. The callback is called every time the event is emitted.
Type Parameters
- K extends keyof FreeSwitchPublicResponseEvents
Parameters
- event: K
- handler: FreeSwitchPublicResponseEvents[K]
Returns this
Inherited from FreeSwitchResponse.on
- Defined in src/event-emitter.ts:48

once

once<K extends keyof FreeSwitchPublicResponseEvents>(
event: K,
handler: FreeSwitchPublicResponseEvents[K],
): this
Register a new callback for the named event. The callback is only called the first time the event is emitted.
Type Parameters
- K extends keyof FreeSwitchPublicResponseEvents
Parameters
- event: K
- handler: FreeSwitchPublicResponseEvents[K]
Returns this
Inherited from FreeSwitchResponse.once
- Defined in src/event-emitter.ts:64

onceAsync

onceAsync<K extends keyof FreeSwitchPublicResponseEvents>(
event: K,
): Promise<Parameters<FreeSwitchPublicResponseEvents[K]>>
Returns a Promise that is resolved the next time the named event is emitted.
Type Parameters
- K extends keyof FreeSwitchPublicResponseEvents
Parameters
- event: K
Returns Promise<Parameters<FreeSwitchPublicResponseEvents[K]>>
Inherited from FreeSwitchResponse.onceAsync
- Defined in src/event-emitter.ts:79

removeAllListeners

removeAllListeners(): void
Unregisters all callbacks from the named event.

Returns void
Inherited from FreeSwitchResponse.removeAllListeners
- Defined in src/event-emitter.ts:103

removeListener

removeListener<K extends keyof FreeSwitchPublicResponseEvents>(
event: K,
handler: FreeSwitchPublicResponseEvents[K],
): void
Unregister the callback from the named event.
Type Parameters
- K extends keyof FreeSwitchPublicResponseEvents
Parameters
- event: K
- handler: FreeSwitchPublicResponseEvents[K]
Returns void
Inherited from FreeSwitchResponse.removeListener
- Defined in src/event-emitter.ts:91

`Protected`send

send(
    command: string,
    commandHeaders: ValueMap,
    commandBody:
        | undefined
        | { content: Buffer<ArrayBufferLike>; contentType: string },
    timeout: number,
): Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
A generic way of sending commands to FreeSwitch; waits for FreeSwitch's notification that the command completed.

This is a low-level method; in most cases one should use bgapi, command_uuid, etc which provide higher-level APIs.

This method is not exposed by default; create a subclass of FreeSwitchClient in order to access it.

This method is not expected to throw / return a rejected Promise.
Parameters
- command: string
- commandHeaders: ValueMap
- commandBody: undefined | { content: Buffer<ArrayBufferLike>; contentType: string }
- timeout: number
Returns Promise<
    | FreeSwitchEventData
    | FreeSwitchAbortError
    | FreeSwitchApplicationEndedError
    | FreeSwitchFailedCommandError
    | FreeSwitchNoReplyError
    | FreeSwitchTimeoutError,
>
Inherited from FreeSwitchResponse.send
- Defined in src/response.ts:748

sendevent

sendevent(eventName: EventName, args: ValueMap, timeout: number): SendResult
Send an event into the FreeSwitch event queue.

This method is not expected to throw / return a rejected Promise.
Parameters
- eventName: EventName
- args: ValueMap
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.sendevent
- Defined in src/response.ts:147

sendeventWithBody

sendeventWithBody(
    eventName: EventName,
    args: ValueMap,
    contentType: string,
    content: Buffer<ArrayBufferLike>,
    timeout: number,
): SendResult
Send an event into the FreeSwitch event queue with a body.

This method is not expected to throw / return a rejected Promise.
Parameters
- eventName: EventName
- args: ValueMap
- contentType: string
- content: Buffer<ArrayBufferLike>
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.sendeventWithBody
- Defined in src/response.ts:165

`Protected`sendmsg_uuid

sendmsg_uuid(
    uuid: string,
    command: string,
    args: ValueMap,
    body: undefined | Buffer<ArrayBufferLike>,
    timeout: number,
): SendResult
Send a message to a given UUID (channel).

This is a low-level operation; in most cases execute_uuid, command_uuid etc will provide a better API.

This method is not exposed by default; create a subclass of FreeSwitchClient in order to access it.

This method is not expected to throw / return a rejected Promise.
Parameters
- uuid: string
- command: string
- args: ValueMap
- body: undefined | Buffer<ArrayBufferLike>
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.sendmsg_uuid
- Defined in src/response.ts:848

unicast_uuid

unicast_uuid(
    uuid: string,
    args: {
        flags?: "native";
        "local-ip": string;
        "local-port": number;
        "remote-ip": string;
        "remote-port": number;
        transport: "tcp" | "udp";
    },
    timeout: number,
): SendResult
Forwards the media to and from a given socket.

This method is not expected to throw / return a rejected Promise.
Parameters
- uuid: string
- args: {
      flags?: "native";
      "local-ip": string;
      "local-port": number;
      "remote-ip": string;
      "remote-port": number;
      transport: "tcp" | "udp";
  }
  - Optionalflags?: "native"
    native means do not transcode to/from L16 audio
    
    In other words, if the flags is present, audio will be in the native codec. If the flag is absent, audio will be in L16 format.
  - local-ip: string
  - local-port: number
  - remote-ip: string
  - remote-port: number
  - transport: "tcp" | "udp"
- timeout: number
Returns SendResult
Inherited from FreeSwitchResponse.unicast_uuid
- Defined in src/response.ts:277

Class FreeSwitchClient

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns FreeSwitchClient

Properties

Readonlycustom

Readonlylogs

Readonlyref

stats

Type declaration

apiResponses: bigint

authRequest: bigint

bodyParseErrors: bigint

commandReply: bigint

disconnect: bigint

events: bigint

logData: bigint

missingContentType: bigint

missingEventName: bigint

nonEmptyBufferAtEnd: bigint

rudeRejections: bigint

unflushedWrites: bigint

unhandled: bigint

Methods

bgapi

Parameters

Returns Promise< | FreeSwitchEventData | FreeSwitchAbortError | FreeSwitchApplicationEndedError | FreeSwitchFailedCommandError | FreeSwitchNoReplyError | FreeSwitchTimeoutError,>

command_uuid

Parameters

Returns Promise< | FreeSwitchEventData | FreeSwitchAbortError | FreeSwitchApplicationEndedError | FreeSwitchFailedCommandError | FreeSwitchNoReplyError | FreeSwitchTimeoutError,>

Protectedconnect

Returns Promise<void>

emit

Type Parameters

Parameters

Returns boolean

end

Returns void

execute_uuid

Parameters

Returns SendResult

hangup_uuid

Parameters

Returns SendResult

log

Parameters

Returns SendResult

nolog

Parameters

Returns SendResult

on

Type Parameters

Parameters

Returns this

once

Type Parameters

Parameters

Returns this

onceAsync

Type Parameters

Parameters

Returns Promise<Parameters<FreeSwitchPublicResponseEvents[K]>>

removeAllListeners

Returns void

removeListener

Type Parameters

Parameters

Returns void

Protectedsend

Parameters

Returns Promise< | FreeSwitchEventData | FreeSwitchAbortError | FreeSwitchApplicationEndedError | FreeSwitchFailedCommandError | FreeSwitchNoReplyError | FreeSwitchTimeoutError,>

sendevent

Parameters

Returns SendResult

`Readonly`custom

`Readonly`logs

`Readonly`ref

Returns Promise<
| FreeSwitchEventData
| FreeSwitchAbortError
| FreeSwitchApplicationEndedError
| FreeSwitchFailedCommandError
| FreeSwitchNoReplyError
| FreeSwitchTimeoutError,
>

Returns Promise<
| FreeSwitchEventData
| FreeSwitchAbortError
| FreeSwitchApplicationEndedError
| FreeSwitchFailedCommandError
| FreeSwitchNoReplyError
| FreeSwitchTimeoutError,
>

`Protected`connect

`Protected`send

Returns Promise<
| FreeSwitchEventData
| FreeSwitchAbortError
| FreeSwitchApplicationEndedError
| FreeSwitchFailedCommandError
| FreeSwitchNoReplyError
| FreeSwitchTimeoutError,
>

`Protected`sendmsg_uuid

`Optional`flags?: "native"