README.md

goagi: Golang library to build agi/fastagi applications

Simple library that helps to build AGI scripts or FastAGI servers with Go.

import "github.com/staskobzar/goagi"

API local documentation link is here or go.dev generated documentation.

Usage FastAGI

AGI object is created with New method with three arguments:

• Reader interface
• Writer interface
• Debugger interface

Debugger interface is required only for debugging and usually nil. See below for more details.

Reader and Writer are interfaces are any objects that implement Read/Write methods and can be net.Conn, tls.Conn, os.Stdin, os.Stdout or any other, for example from packages strings, bufio, bytes.

New method will read AGI session setup environment variables and provides interface to AGI commands. AGI environment variables and arguments can be accessed with methods Env and EnvArgs. If AGI channel receives HANGUP message, the session will be marked as hungup. Hangup status can be checked by method IsHungup.

Usage example for AGI:

	import (
		"github.com/staskobzar/goagi"
		"os"
	)

	agi, err := goagi.New(os.Stdin, os.Stdout, nil)
	if err != nil {
		panic(err)
	}
	agi.Verbose("Hello World!")

Fast AGI example:

	ln, err := net.Listen("tcp", "127.0.0.1:4573")
	if err != nil {
		panic(err)
	}
	for {
		conn, err := ln.Accept()
		if err != nil {
			panic(err)
		}
		go func(conn net.Conn) {
			agi, err := goagi.New(conn, conn, nil)
			if err != nil {
				panic(err)
			}
			agi.Verbose("Hello World!")
		}(conn)
	}

See working examples in [examples/] folder.

Index of methods that implements AGI commands see here.

Commands Response interface

Every AGI command method return interface Response. This is interface that provides access to AGI response values. Success response example:

200 result=1 (speech) endpos=9834523 results=5

Fail response example:

511 Command Not Permitted on a dead channel or intercept routine

There are success and error responses. Response interface implements following methods:

• Code() int: response code: 200, 510 etc.
• RawResponse() string: returns full text of AGI response.
• Result() int: returns value of result= field.
• Value() string: returns response value field that comes in parentheses. For exmpale "(timeout)" in response "200 result=1 (timeout)".
• Data() string: returns text for error responses and dtmf values for command like GetData.
• EndPos() int64: returns value for endpos= field.
• Digit() string: return digit from digit= field.
• SResults() int: return value for results= field.

Debugger

Interface that provides debugging capabilities with configurable output.

Example of usage:

	dbg := logger.New(os.Stdout, "myagi:", log.Lmicroseconds)
	r, w := net.Pipe()
	agi, err := goagi.New(r, w, dbg)