Go SDK requests and types

Request fields

The telnyx library uses the omitzero semantics from the Go 1.24+ encoding/json release for request fields. Required primitive fields (int64, string, etc.) feature the tag `json:”…,required”`. These fields are always serialized, even their zero values. Optional primitive types are wrapped in a param.Opt[T]. These fields can be set with the provided constructors, telnyx.String(string), telnyx.Int(int64), etc. Any param.Opt[T], map, slice, struct or string enum uses the tag `json:”…,omitzero”`. Its zero value is considered omitted. The param.IsOmitted(any) function can confirm the presence of any omitzero field.

p := telnyx.ExampleParams{
	ID:   "id_xxx",             // required property
	Name: telnyx.String("..."), // optional property

	Point: telnyx.Point{
		X: 0,             // required field will serialize as 0
		Y: telnyx.Int(1), // optional field will serialize as 1
		// ... omitted non-required fields will not be serialized
	},

	Origin: telnyx.Origin{}, // the zero value of [Origin] is considered omitted
}

To send null instead of a param.Opt[T], use param.Null[T](). To send null instead of a struct T, use param.NullStruct[T]().

p.Name = param.Null[string]()       // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

Request structs contain a .SetExtraFields(map[string]any) method which can send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching key. For security reasons, only use SetExtraFields with trusted data. To send a custom value instead of a struct, use param.Override[T](https://github.com/team-telnyx/telnyx-go/tree/master/value).

// In cases where the API specifies a given type,
// but you want to send something else, use [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Send a number instead of an object
custom := param.Override[telnyx.FooParams](https://github.com/team-telnyx/telnyx-go/tree/master/12)

Request unions

Unions are represented as a struct with fields prefixed by “Of” for each of it’s variants, only one field can be non-zero. The non-zero field will be serialized. Sub-properties of the union can be accessed via methods on the union struct. These methods return a mutable pointer to the underlying data, if present.

// Only one field can be non-zero, use param.IsOmitted() to check if a field is set
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline`
	OfDog *Dog `json:",omitzero,inline`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", Zip: 0},
		},
	},
}

// Mutating a field
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Response objects

All fields in response structs are ordinary value types (not pointers or wrappers). Response structs also include a special JSON field containing metadata about each property.

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owner       respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

To handle optional data, use the .Valid() method on the JSON field. .Valid() returns true if a field is not null, not present, or couldn’t be marshaled. If .Valid() is false, the corresponding field will simply be its zero value.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Accessing regular fields

res.Owners // 1
res.Name   // ""
res.Age    // 0

// Optional field checks

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// Raw JSON values

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

These .JSON structs also include an ExtraFields map containing any properties in the json response that were not specified in the struct. This can be useful for API features not yet present in the SDK.

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

Response Unions

In responses, unions are represented by a flattened struct containing all possible fields from each of the object variants. To convert it to a variant use the .AsFooVariant() method or the .AsAny() method if present. If a response value union contains primitive values, primitive fields will be alongside the properties but prefixed with Of and feature the tag json:"...,inline".

type AnimalUnion struct {
	// From variants [Dog], [Cat]
	Owner Person `json:"owner"`
	// From variant [Dog]
	DogBreed string `json:"dog_breed"`
	// From variant [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// If animal variant
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Switch on the variant
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

RequestOptions

This library uses the functional options pattern. Functions defined in the option package return a RequestOption, which is a closure that mutates a RequestConfig. These options can be supplied to the client or at individual requests. For example:

client := telnyx.NewClient(
	// Adds a header to every request made by the client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.NumberOrders.New(context.TODO(), ...,
	// Override the header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Add an undocumented field to the request body, using sjson syntax
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

The request option option.WithDebugLog(nil) may be helpful while debugging. See the full list of request options.

Pagination

This library provides some conveniences for working with paginated list endpoints. You can use .ListAutoPaging() methods to iterate through items across all pages: Or you can use simple .List() methods to fetch a single page and receive a standard response object with additional helper methods like .GetNextPage(), e.g.:

File uploads

Request parameters that correspond to file uploads in multipart requests are typed as io.Reader. The contents of the io.Reader will by default be sent as a multipart form part with the file name of “anonymous_file” and content-type of “application/octet-stream”. The file name and content-type can be customized by implementing Name() string or ContentType() string on the run-time type of io.Reader. Note that os.File implements Name() string, so a file returned by os.Open will be sent with the file name on disk. We also provide a helper telnyx.File(reader io.Reader, filename string, contentType string) which can be used to wrap any io.Reader with the appropriate file name and content type.

// A file from the file system
file, err := os.Open("/path/to/file")
telnyx.AIAudioTranscribeParams{
	Model: telnyx.AIAudioTranscribeParamsModelDistilWhisperDistilLargeV2,
	File:  file,
}

// A file from a string
telnyx.AIAudioTranscribeParams{
	Model: telnyx.AIAudioTranscribeParamsModelDistilWhisperDistilLargeV2,
	File:  strings.NewReader("my file contents"),
}

// With a custom filename and contentType
telnyx.AIAudioTranscribeParams{
	Model: telnyx.AIAudioTranscribeParamsModelDistilWhisperDistilLargeV2,
	File:  telnyx.File(strings.NewReader(`{"hello": "foo"}`), "file.go", "application/json"),
}

Account setup

APIs fundamentals

Server-side SDKs

Telnyx CLI

Development Tools

Migration Guides

Glossary

For AI Agents

Go SDK requests and types

Request fields

Request unions

Response objects

Response Unions

RequestOptions

File uploads

​Request fields

​Request unions

​Response objects

​Response Unions

​RequestOptions

​Pagination

​File uploads

Request fields

Request unions

Response objects

Response Unions

RequestOptions

Pagination

File uploads