-- import "github.com/zaf/agi"
Package agi implements the Asterisk Gateway Interface (http://www.asterisk.org). All AGI commands are implemented as methods of the Session struct that holds a copy of the AGI environment variables. All methods return a Reply struct and the AGI error, if any. The Reply struct contains the numeric result of the AGI command in Res and if there is any additional data it is stored as string in the Dat element of the struct. For example, to create a new AGI session and initialize it:
myAgi:=agi.New()
err:=myAgi.Init(nil)
iferr!=nil {
log.Fatalf("Error Parsing AGI environment: %v\n", err)
}To play back a voice prompt using AGI 'Stream file' command:
rep, err:=myAgi.StreamFile("hello-world", "0123456789")
iferr!=nil {
log.Fatalf("AGI reply error: %v\n", err)
}
ifrep.Res==-1 {
log.Printf("Error during playback\n")
}For more please see the code snippets in the examples folder.
Package agi implements the Asterisk Gateway Interface (http://www.asterisk.org).
typeReplystruct {
Resint//Numeric result of the AGI command.Datstring//Additional returned data.
}Reply is a struct that holds the return values of each AGI command.
typeSessionstruct {
Envmap[string]string//AGI environment variables.
}Session is a struct holding AGI environment vars and the I/O handlers.
funcNew() *SessionNew creates a new Session and returns a pointer to it.
func (a*Session) Answer() (Reply, error)Answer answers channel. Res is -1 on channel failure, or 0 if successful.
func (a*Session) AsyncagiBreak() (Reply, error)AsyncagiBreak interrupts Async AGI. Res is always 0.
func (a*Session) ChannelStatus(channel...string) (Reply, error)ChannelStatus Res contains the status of the given channel, if no channel specified checks the current channel. Result values:
0 - Channel is down and available.
1 - Channel is down, but reserved.
2 - Channel is off hook.
3 - Digits (or equivalent) have been dialed.
4 - Line is ringing.
5 - Remote end is ringing.
6 - Line is up.
7 - Line is busy.
func (a*Session) ControlStreamFile(file, escapestring, params...interface{}) (Reply, error)ControlStreamFile sends audio file on channel and allows the listener to control the stream. Optional parameters: skipms, ffchar - Defaults to *, rewchr - Defaults to #, pausechr. Res is 0 if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed, or -1 on error or if the channel was disconnected.
func (a*Session) DatabaseDel(family, keystring) (Reply, error)DatabaseDel removes database key/value. Res is 1 if successful, 0 otherwise.
func (a*Session) DatabaseDelTree(familystring, keytree...string) (Reply, error)DatabaseDelTree removes database keytree/value. Res is 1 if successful, 0 otherwise.
func (a*Session) DatabaseGet(family, keystring) (Reply, error)DatabaseGet gets database value. Res is 0 if key is not set, 1 if key is set and the value is returned in Dat.
func (a*Session) DatabasePut(family, key, valuestring) (Reply, error)DatabasePut adds/updates database value. Res is 1 if successful, 0 otherwise.
func (a*Session) Exec(app, optionsstring) (Reply, error)Exec executes a given application. Res contains whatever the dialplan application returns, or -2 on failure to find the application.
func (a*Session) Failure() (Reply, error)Failure causes asterisk to terminate the AGI session and set the AGISTATUS channel variable to 'FAILURE'.
func (a*Session) GetData(filestring, params...int) (Reply, error)GetData prompts for DTMF on a channel. Optional parameters: timeout, maxdigits. Res contains the digits received from the channel at the other end.
func (a*Session) GetFullVariable(variablestring, channel...string) (Reply, error)GetFullVariable evaluates a channel expression, if no channel is specified the current channel is used. Res is 1 if variable is set and the value is returned in Dat. Understands complex variable names and build in variables.
func (a*Session) GetOption(filename, escapestring, timeout...int) (Reply, error)GetOption streams file, prompts for DTMF with timeout. Optional parameter: timeout. Res contains the digits received from the channel at the other end and Dat contains the sample ofset. In case of failure to playback Res is -1.
func (a*Session) GetVariable(variablestring) (Reply, error)GetVariable gets a channel variable. Res is 0 if variable is not set, 1 if variable is set and Dat contains the value.
func (a*Session) GoSub(context, extension, priority, argsstring) (Reply, error)GoSub causes the channel to execute the specified dialplan subroutine, returning to the dialplan with execution of a Return().
func (a*Session) Hangup(channel...string) (Reply, error)Hangup hangs up a channel, Res is 1 on success, -1 if the given channel was not found.
func (a*Session) Init(rw*bufio.ReadWriter) errorInit initializes a new AGI session. If rw is nil the AGI session will use standard input (stdin) and output (stdout) for a standalone AGI application. It reads and stores the AGI environment variables in Env. Returns an error if the parsing of the AGI environment was unsuccessful.
func (a*Session) Noop(params...interface{}) (Reply, error)Noop does nothing. Res is always 0.
func (a*Session) RawCommand(params...interface{}) (Reply, error)RawCommand sends a user defined command. Use of this is generally discouraged. Useful only for debugging, testing and maybe compatibility with newer/altered versions of the AGI protocol.
func (a*Session) ReceiveChar(timeoutint) (Reply, error)ReceiveChar receives one character from channels supporting it. Res contains the decimal value of the character if one is received, or 0 if the channel does not support text reception. Result is -1 only on error/hang-up.
func (a*Session) ReceiveText(timeoutint) (Reply, error)ReceiveText receives text from channels supporting it. Res is -1 for failure or 1 for success, and Dat contains the string.
func (a*Session) RecordFile(file, format, escapestring, timeoutint, params...interface{}) (Reply, error)RecordFile records to a given file. The format will specify what kind of file will be recorded. The timeout is the maximum record time in milliseconds, or -1 for no timeout. Optional parameters: offset samples if provided will seek to the offset without exceeding the end of the file. Silence (always prefixed with s=)is the number of seconds of silence allowed before the function returns despite the lack of DTMF digits or reaching timeout. Negative values of Res mean error. Res equals 0 if recording was successful without any DTMF digit received, or the ASCII numerical value of the digit if one was received. Dat contains a set of different inconsistent return values depending on each case, please refer to res_agi.c in asterisk source code for further info.
func (a*Session) SayAlpha(str, escapestring) (Reply, error)SayAlpha says a given character string. Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SayDate(dateint64, escapestring) (Reply, error)SayDate says a given date (Unix time format). Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SayDateTime(timeint64, escapestring, params...string) (Reply, error)SayDateTime says a given time (Unix time format). Optional parameters: format, the format the time should be said in. See voicemail.conf (defaults to ABdY 'digits/at' IMp). timezone, acceptable values can be found in /usr/share/zoneinfo. Defaults to machine default. Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SayDigits(digitint, escapestring) (Reply, error)SayDigits says a given digit. Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SayNumber(numint, escapestring, gender...string) (Reply, error)SayNumber says a given number. Optional parameter gender. Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SayPhonetic(str, escapestring) (Reply, error)SayPhonetic says a given character string with phonetics. Res is 0 if playback completes without a digit pressed, the ASCII numerical value of the digit if one was pressed, or -1 on error/hang-up
func (a*Session) SayTime(timeint64, escapestring) (Reply, error)SayTime says a given time (Unix time format). Res is 0 if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or -1 on error/hang-up.
func (a*Session) SendImage(imagestring) (Reply, error)SendImage sends images to channels supporting it. Res is 0 if image is sent, or if the channel does not support image transmission. Result is -1 only on error/hang-up. Image names should not include extensions.
func (a*Session) SendText(textstring) (Reply, error)SendText sends text to channels supporting it. Res is 0 if text is sent, or if the channel does not support text transmission. Result is -1 only on error/hang-up.
func (a*Session) SetAutohangup(timeint) (Reply, error)SetAutohangup autohang-ups channel after a number of seconds. Setting time to 0 will cause the autohang-up feature to be disabled on this channel. Res is always 0.
func (a*Session) SetCallerid(cidstring) (Reply, error)SetCallerid sets callerid for the current channel. Res is always 1.
func (a*Session) SetContext(contextstring) (Reply, error)SetContext sets channel context. Res is always 0.
func (a*Session) SetExtension(extstring) (Reply, error)SetExtension changes channel extension. Res is always 0.
func (a*Session) SetMusic(optstring, class...string) (Reply, error)SetMusic enables/disables Music on hold generator by setting opt to "on" or "off". Optional parameter: class, if not specified, then the default music on hold class will be used. Res is always 0.
func (a*Session) SetPriority(prioritystring) (Reply, error)SetPriority sets channel dialplan priority. The priority must be a valid priority or label. Res is always 0.
func (a*Session) SetVariable(variablestring, valueinterface{}) (Reply, error)SetVariable sets a channel variable. Res is always 1.
func (a*Session) SpeechActivateGrammar(grammarstring) (Reply, error)SpeechActivateGrammar activates a grammar. Res is 1 on success 0 on error.
func (a*Session) SpeechCreate(enginestring) (Reply, error)SpeechCreate creates a speech object. Res is 1 on success 0 on error.
func (a*Session) SpeechDeactivateGrammar(grammarstring) (Reply, error)SpeechDeactivateGrammar deactivates a grammar. Res is 1 on success 0 on error.
func (a*Session) SpeechDestroy() (Reply, error)SpeechDestroy destroys a speech object. Res is 1 on success 0 on error.
func (a*Session) SpeechLoadGrammar(grammar, pathstring) (Reply, error)SpeechLoadGrammar loads a grammar. Res is 1 on success 0 on error.
func (a*Session) SpeechRecognize(prompt, timeout, offsetstring) (Reply, error)SpeechRecognize recognizes speech. Res is 1 onsuccess, 0 in case of error In case of success Dat contains a set of different inconsistent values. Please refer to res_agi.c in asterisk source code for further info.
func (a*Session) SpeechSet(name, valuestring) (Reply, error)SpeechSet sets a speech engine setting. Res is 1 on success 0 on error.
func (a*Session) SpeechUnloadGrammar(grammarstring) (Reply, error)SpeechUnloadGrammar unloads a grammar. Result is 1 on success 0 on error.
func (a*Session) StreamFile(file, escapestring, offset...int) (Reply, error)StreamFile sends audio file on channel. Optional parameter: sample offset for the playback start position. Res is 0 if playback completes without a digit being pressed, the ASCII numerical value of the digit if one was pressed, or -1 on error or if the channel was disconnected. If musiconhold is playing before calling stream file it will be automatically stopped and will not be restarted after completion.
func (a*Session) TddMode(modestring) (Reply, error)TddMode toggles TDD mode (for the deaf). Res is 1 if successful, or 0 if channel is not TDD-capable.
func (a*Session) Verbose(msginterface{}, level...int) (Reply, error)Verbose logs a message to the asterisk verbose log. Optional variable: level, the verbose level (1-4). Res is always 1.
func (a*Session) WaitForDigit(timeoutint) (Reply, error)WaitForDigit waits for a digit to be pressed. Use -1 for the timeout value if you desire the call to block indefinitely. Res is -1 on channel failure, 0 if no digit is received in the timeout, or the ASCII numerical value of the digit if one is received.