eslgo

README

eslgo

eslgo is a FreeSWITCH™ ESL library for GoLang. eslgo was written from the ground up in idiomatic Go for use in our production products tested handling thousands of calls per second.

Install

go get github.com/AkronimBlack/eslgo

github.com/AkronimBlack/eslgo v1.3.3

Overview

• Inbound ESL Connection
• Outbound ESL Server
• Event listeners by UUID or All events
  • Unique-Id
  • Application-UUID
  • Job-UUID
• Context support for canceling requests
• All command types abstracted out
  • You can also send custom data by implementing the Command interface
    • BuildMessage() string
• Basic Helpers for common tasks
  • DTMF
  • Call origination
  • Call answer/hangup
  • Audio playback

Examples

There are some buildable examples under the example directory as well

Outbound ESL Server

package main

import (
	"context"
	"fmt"
	"github.com/AkronimBlack/eslgo"
	"log"
)

func main() {
	// Start listening, this is a blocking function
	log.Fatalln(eslgo.ListenAndServe(":8084", handleConnection))
}

func handleConnection(ctx context.Context, conn *eslgo.Conn, response *eslgo.RawResponse) {
	fmt.Printf("Got connection! %#v\n", response)

	// Place the call in the foreground(api) to user 100 and playback an audio file as the bLeg and no exported variables
	response, err := conn.OriginateCall(ctx, false, eslgo.Leg{CallURL: "user/100"}, eslgo.Leg{CallURL: "&playback(misc/ivr-to_hear_screaming_monkeys.wav)"}, map[string]string{})
	fmt.Println("Call Originated: ", response, err)
}

Inbound ESL Client

package main

import (
	"context"
	"fmt"
	"github.com/AkronimBlack/eslgo"
	"time"
)

func main() {
	// Connect to FreeSWITCH
	conn, err := eslgo.Dial("127.0.0.1:8021", "ClueCon", func() {
		fmt.Println("Inbound Connection Disconnected")
	})
	if err != nil {
		fmt.Println("Error connecting", err)
		return
	}

	// Create a basic context
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()

	// Place the call in the background(bgapi) to user 100 and playback an audio file as the bLeg and no exported variables
	response, err := conn.OriginateCall(ctx, true, eslgo.Leg{CallURL: "user/100"}, eslgo.Leg{CallURL: "&playback(misc/ivr-to_hear_screaming_monkeys.wav)"}, map[string]string{})
	fmt.Println("Call Originated: ", response, err)

	// Close the connection after sleeping for a bit
	time.Sleep(60 * time.Second)
	conn.ExitAndClose()
}

Documentation

Overview

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

* Copyright (c) 2020 Percipia * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Contributor(s): * Andrew Querol <aquerol@percipia.com>

Index

• Constants
• func BuildVars(format string, vars map[string]string) string
• func ListenAndServe(address string, handler OutboundHandler, opts *Options) error
• type Conn
  • func Dial(address, password string, timeout time.Duration, onDisconnect func()) (*Conn, error)
  • func NewConnection(c net.Conn, outbound bool, onDisconnect func(), address, password string) *Conn
  • func (c *Conn) AnswerCall(ctx context.Context, uuid string) error
  • func (c *Conn) Close()
  • func (c *Conn) DebugEvents(w io.Writer) string
  • func (c *Conn) DebugOff(id string)
  • func (c *Conn) EnableEvents(ctx context.Context) error
  • func (c *Conn) EnterpriseOriginateCall(ctx context.Context, background bool, vars map[string]string, bLeg Leg, ...) (*RawResponse, error)
  • func (c *Conn) ExitAndClose()
  • func (c *Conn) FinishedChannel() chan bool
  • func (c *Conn) HangupCall(ctx context.Context, uuid, cause string) error
  • func (c *Conn) OnDisconnect() func()
  • func (c *Conn) OriginateCall(ctx context.Context, background bool, aLeg, bLeg Leg, vars map[string]string) (*RawResponse, error)
  • func (c *Conn) Phrase(ctx context.Context, uuid, macro string, times int, wait bool) (*RawResponse, error)
  • func (c *Conn) PhraseWithArg(ctx context.Context, uuid, macro string, argument interface{}, times int, ...) (*RawResponse, error)
  • func (c *Conn) Playback(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)
  • func (c *Conn) RegisterEventListener(channelUUID string, listener EventListener) string
  • func (c *Conn) RemoveEventListener(channelUUID string, id string)
  • func (c *Conn) RunningContext() context.Context
  • func (c *Conn) Say(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)
  • func (c *Conn) SendCommand(ctx context.Context, command command.Command) (*RawResponse, error)
  • func (c *Conn) SetFinishedChannel(finishedChannel chan bool)
  • func (c *Conn) Speak(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)
  • func (c *Conn) WaitForDTMF(ctx context.Context, uuid string) (byte, error)
• type Event
  • func (e Event) GetHeader(header string) string
  • func (e Event) GetName() string
  • func (e Event) GoString() string
  • func (e Event) HasHeader(header string) bool
  • func (e Event) String() string
• type EventListener
• type Leg
  • func (l Leg) String() string
• type Options
  • func NewOptions(network string, timout time.Duration) *Options
• type OutboundHandler
• type RawResponse
  • func (r RawResponse) ChannelUUID() string
  • func (r RawResponse) GetHeader(header string) string
  • func (r RawResponse) GetReply() string
  • func (r RawResponse) GetVariable(variable string) string
  • func (r RawResponse) GoString() string
  • func (r RawResponse) HasHeader(header string) bool
  • func (r RawResponse) IsOk() bool
  • func (r RawResponse) String() string

Constants

const (
	TypeEventPlain  = `text/event-plain`
	TypeEventJSON   = `text/event-json`
	TypeEventXML    = `text/event-xml`
	TypeReply       = `command/reply`
	TypeAPIResponse = `api/response`
	TypeAuthRequest = `auth/request`
	TypeDisconnect  = `text/disconnect-notice`
)

const EndOfMessage = "\r\n\r\n"

const (
	EventListenAll = "ALL"
)

Functions

func BuildVars

func BuildVars(format string, vars map[string]string) string

func ListenAndServe

func ListenAndServe(address string, handler OutboundHandler, opts *Options) error

ListenAndServe start listener with given options

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn ...

func Dial

func Dial(address, password string, timeout time.Duration, onDisconnect func()) (*Conn, error)

func NewConnection

func NewConnection(c net.Conn, outbound bool, onDisconnect func(), address, password string) *Conn

NewConnection exported constructor for alterative builds

func (*Conn) AnswerCall

func (c *Conn) AnswerCall(ctx context.Context, uuid string) error

HangupCall - A helper to answer a call synchronously

func (*Conn) Close

func (c *Conn) Close()

func (*Conn) DebugEvents

func (c *Conn) DebugEvents(w io.Writer) string

DebugEvents - A helper that will output all events to a logger

func (*Conn) DebugOff

func (c *Conn) DebugOff(id string)

func (*Conn) EnableEvents

func (c *Conn) EnableEvents(ctx context.Context) error

func (*Conn) EnterpriseOriginateCall

func (c *Conn) EnterpriseOriginateCall(ctx context.Context, background bool, vars map[string]string, bLeg Leg, aLegs ...Leg) (*RawResponse, error)

EnterpriseOriginateCall - Calls the originate function in FreeSWITCH using the enterprise method for calling multiple legs ":_:" If you want variables for each leg independently set them in the aLeg and bLeg strings Arguments: ctx context.Context for supporting context cancellation, background bool should we wait for the origination to complete vars map[string]string, channel variables to be passed to originate for both legs, contained in <> bLeg string The bLeg of the call aLegs ...string variadic argument for each aLeg to call

func (*Conn) ExitAndClose

func (c *Conn) ExitAndClose()

func (*Conn) FinishedChannel

func (c *Conn) FinishedChannel() chan bool

func (*Conn) HangupCall

func (c *Conn) HangupCall(ctx context.Context, uuid, cause string) error

HangupCall - A helper to hangup a call asynchronously

func (*Conn) OnDisconnect

func (c *Conn) OnDisconnect() func()

func (*Conn) OriginateCall

func (c *Conn) OriginateCall(ctx context.Context, background bool, aLeg, bLeg Leg, vars map[string]string) (*RawResponse, error)

OriginateCall - Calls the originate function in FreeSWITCH. If you want variables for each leg independently set them in the aLeg and bLeg Arguments: ctx context.Context for supporting context cancellation, background bool should we wait for the origination to complete aLeg, bLeg Leg The aLeg and bLeg of the call respectively vars map[string]string, channel variables to be passed to originate for both legs, contained in {}

func (*Conn) Phrase

func (c *Conn) Phrase(ctx context.Context, uuid, macro string, times int, wait bool) (*RawResponse, error)

Phrase - Executes the mod_dptools phrase app

func (*Conn) PhraseWithArg

func (c *Conn) PhraseWithArg(ctx context.Context, uuid, macro string, argument interface{}, times int, wait bool) (*RawResponse, error)

PhraseWithArg - Executes the mod_dptools phrase app with arguments

func (*Conn) Playback

func (c *Conn) Playback(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)

Playback - Executes the mod_dptools playback app

func (*Conn) RegisterEventListener

func (c *Conn) RegisterEventListener(channelUUID string, listener EventListener) string

RegisterEventListener ...

func (*Conn) RemoveEventListener

func (c *Conn) RemoveEventListener(channelUUID string, id string)

RemoveEventListener ..

func (*Conn) RunningContext

func (c *Conn) RunningContext() context.Context

func (*Conn) Say

func (c *Conn) Say(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)

Say - Executes the mod_dptools say app

func (*Conn) SendCommand

func (c *Conn) SendCommand(ctx context.Context, command command.Command) (*RawResponse, error)

func (*Conn) SetFinishedChannel

func (c *Conn) SetFinishedChannel(finishedChannel chan bool)

func (*Conn) Speak

func (c *Conn) Speak(ctx context.Context, uuid, audioArgs string, times int, wait bool) (*RawResponse, error)

Speak - Executes the mod_dptools speak app

func (*Conn) WaitForDTMF

func (c *Conn) WaitForDTMF(ctx context.Context, uuid string) (byte, error)

WaitForDTMF, waits for a DTMF event. Requires events to be enabled!

type Event

type Event struct {
	Headers textproto.MIMEHeader
	Body    []byte
}

func (Event) GetHeader

func (e Event) GetHeader(header string) string

GetHeader Helper function that calls e.Header.Get

func (Event) GetName

func (e Event) GetName() string

GetName Helper function that returns the event name header

func (Event) GoString

func (e Event) GoString() string

GoString Implement the GoStringer interface for pretty printing (%#v)

func (Event) HasHeader

func (e Event) HasHeader(header string) bool

HasHeader Helper to check if the Event has a header

func (Event) String

func (e Event) String() string

String Implement the Stringer interface for pretty printing (%v)

type EventListener

type EventListener func(event *Event)

type Leg

type Leg struct {
	CallURL      string
	LegVariables map[string]string
}

Leg This struct is used to specify the individual legs of a call for the originate helpers

func (Leg) String

func (l Leg) String() string

String - Build the Leg string for passing to Bridge/Originate functions

type Options

type Options struct {
	//Allow for context timout. 0 will mean indefinite
	Timeout time.Duration `json:"duration"`
	// Defaults to "tcp"
	// Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only),
	// "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4"
	// (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
	// "unixpacket".
	Network string `json:"network"`
}

Options allow of customizing listener

func NewOptions

func NewOptions(network string, timout time.Duration) *Options

type OutboundHandler

type OutboundHandler func(ctx context.Context, conn *Conn, connectResponse *RawResponse)

type RawResponse

type RawResponse struct {
	Headers textproto.MIMEHeader
	Body    []byte
}

RawResponse This struct contains all response data from FreeSWITCH

func (RawResponse) ChannelUUID

func (r RawResponse) ChannelUUID() string

ChannelUUID Helper to get the channel UUID. Calls GetHeader internally

func (RawResponse) GetHeader

func (r RawResponse) GetHeader(header string) string

GetHeader Helper function that calls RawResponse.Headers.Get. Result gets passed through url.PathUnescape

func (RawResponse) GetReply

func (r RawResponse) GetReply() string

GetReply Helper to get the Reply text from FreeSWITCH, uses the Reply-Text header primarily. Also will use the body if the Reply-Text header does not exist, this can be the case for TypeAPIResponse

func (RawResponse) GetVariable

func (r RawResponse) GetVariable(variable string) string

GetVariable Helper function to get "Variable_" headers. Calls GetHeader internally

func (RawResponse) GoString

func (r RawResponse) GoString() string

GoString Implement the GoStringer interface for pretty printing (%#v)

func (RawResponse) HasHeader

func (r RawResponse) HasHeader(header string) bool

HasHeader Helper to check if the RawResponse has a header

func (RawResponse) IsOk

func (r RawResponse) IsOk() bool

IsOk Helper to check response status, uses the Reply-Text header primarily. Calls GetReply internally

func (RawResponse) String

func (r RawResponse) String() string

String Implement the Stringer interface for pretty printing