Telnyx Networking - Go

SkillDev tools

Configure private networks, WireGuard VPN gateways, internet gateways, and virtual cross connects. This skill provides Go SDK examples.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the Telnyx Networking - Go skill

What this skill tells your AI

The instructions your AI receives, as published by team-telnyx/ai in skills/telnyx-networking-go/SKILL.md and read by ahel’s review.

Installation

go get github.com/team-telnyx/telnyx-go

Setup

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

client := telnyx.NewClient(
  option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
)

All examples below assume client is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

import "errors"

result, err := client.Messages.Send(ctx, params)
if err != nil {
  var apiErr *telnyx.Error
  if errors.As(err, &apiErr) {
    switch apiErr.StatusCode {
    case 422:
      fmt.Println("Validation error — check required fields and formats")
    case 429:
      // Rate limited — wait and retry with exponential backoff
      fmt.Println("Rate limited, retrying...")
    default:
      fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Error())
    }
  } else {
    fmt.Println("Network error — check connectivity and retry")
  }
}

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Important Notes

Pagination: Use ListAutoPaging() for automatic iteration: iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }.

List all clusters

GET /ai/clusters

	page, err := client.AI.Clusters.List(context.Background(), telnyx.AIClusterListParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", page)

Returns: bucket (string), created_at (date-time), finished_at (date-time), min_cluster_size (integer), min_subcluster_size (integer), status (enum: pending, starting, running, completed, failed), task_id (string)

Compute new clusters

Starts a background task to compute how the data in an embedded storage bucket is clustered. This helps identify common themes and patterns in the data.

POST /ai/clusters — Required: bucket

Optional: files (array[string]), min_cluster_size (integer), min_subcluster_size (integer), prefix (string)

	response, err := client.AI.Clusters.Compute(context.Background(), telnyx.AIClusterComputeParams{
		Bucket: "my-bucket",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns: task_id (string)

Fetch a cluster

GET /ai/clusters/{task_id}

	cluster, err := client.AI.Clusters.Get(
		context.Background(),
		"task_id",
		telnyx.AIClusterGetParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", cluster.Data)

Returns: bucket (string), clusters (array[object]), status (enum: pending, starting, running, completed, failed)

Delete a cluster

DELETE /ai/clusters/{task_id}

	err := client.AI.Clusters.Delete(context.Background(), "task_id")
	if err != nil {
		log.Fatal(err)
	}

Fetch a cluster visualization

GET /ai/clusters/{task_id}/graph

	response, err := client.AI.Clusters.FetchGraph(
		context.Background(),
		"task_id",
		telnyx.AIClusterFetchGraphParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response)

List Integrations

List all available integrations.

GET /ai/integrations

	integrations, err := client.AI.Integrations.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", integrations.Data)

Returns: available_tools (array[string]), description (string), display_name (string), id (string), logo_url (string), name (string), status (enum: disconnected, connected)

List User Integrations

List user setup integrations

GET /ai/integrations/connections

	connections, err := client.AI.Integrations.Connections.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", connections.Data)

Returns: allowed_tools (array[string]), id (string), integration_id (string)

Get User Integration connection By Id

Get user setup integrations

GET /ai/integrations/connections/{user_connection_id}

	connection, err := client.AI.Integrations.Connections.Get(context.Background(), "user_connection_id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", connection.Data)

Returns: allowed_tools (array[string]), id (string), integration_id (string)

Delete Integration Connection

Delete a specific integration connection.

DELETE /ai/integrations/connections/{user_connection_id}

	err := client.AI.Integrations.Connections.Delete(context.Background(), "user_connection_id")
	if err != nil {
		log.Fatal(err)
	}

List Integration By Id

Retrieve integration details

GET /ai/integrations/{integration_id}

	integration, err := client.AI.Integrations.Get(context.Background(), "integration_id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", integration.ID)

Returns: available_tools (array[string]), description (string), display_name (string), id (string), logo_url (string), name (string), status (enum: disconnected, connected)

List all Global IP Allowed Ports

GET /global_ip_allowed_ports

	globalIPAllowedPorts, err := client.GlobalIPAllowedPorts.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAllowedPorts.Data)

Returns: first_port (integer), id (uuid), last_port (integer), name (string), protocol_code (string), record_type (string)

Global IP Assignment Health Check Metrics

GET /global_ip_assignment_health

	globalIPAssignmentHealth, err := client.GlobalIPAssignmentHealth.Get(context.Background(), telnyx.GlobalIPAssignmentHealthGetParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignmentHealth.Data)

Returns: global_ip (object), global_ip_assignment (object), health (object), timestamp (date-time)

List all Global IP assignments

List all Global IP assignments.

GET /global_ip_assignments

	page, err := client.GlobalIPAssignments.List(context.Background(), telnyx.GlobalIPAssignmentListParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", page)

Returns: created_at (string), global_ip_id (uuid), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (uuid)

Create a Global IP assignment

Create a Global IP assignment.

POST /global_ip_assignments

Optional: created_at (string), global_ip_id (uuid), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (uuid)

	globalIPAssignment, err := client.GlobalIPAssignments.New(context.Background(), telnyx.GlobalIPAssignmentNewParams{
		GlobalIPAssignment: telnyx.GlobalIPAssignmentParam{},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignment.Data)

Retrieve a Global IP

Retrieve a Global IP assignment.

GET /global_ip_assignments/{id}

	globalIPAssignment, err := client.GlobalIPAssignments.Get(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignment.Data)

Update a Global IP assignment

Update a Global IP assignment.

PATCH /global_ip_assignments/{id}

Optional: created_at (string), global_ip_id (string), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (string)

	globalIPAssignment, err := client.GlobalIPAssignments.Update(
		context.Background(),
		"6a09cdc3-8948-47f0-aa62-74ac943d6c58",
		telnyx.GlobalIPAssignmentUpdateParams{
			GlobalIPAssignmentUpdateRequest: telnyx.GlobalIPAssignmentUpdateParamsGlobalIPAssignmentUpdateRequest{
				GlobalIPAssignmentParam: telnyx.GlobalIPAssignmentParam{},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignment.Data)

Delete a Global IP assignment

Delete a Global IP assignment.

DELETE /global_ip_assignments/{id}

	globalIPAssignment, err := client.GlobalIPAssignments.Delete(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignment.Data)

Global IP Assignment Usage Metrics

GET /global_ip_assignments_usage

	globalIPAssignmentsUsage, err := client.GlobalIPAssignmentsUsage.Get(context.Background(), telnyx.GlobalIPAssignmentsUsageGetParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPAssignmentsUsage.Data)

Returns: global_ip (object), global_ip_assignment (object), received (object), timestamp (date-time), transmitted (object)

List all Global IP Health check types

List all Global IP Health check types.

GET /global_ip_health_check_types

	globalIPHealthCheckTypes, err := client.GlobalIPHealthCheckTypes.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPHealthCheckTypes.Data)

Returns: health_check_params (object), health_check_type (string), record_type (string)

List all Global IP health checks

List all Global IP health checks.

GET /global_ip_health_checks

	page, err := client.GlobalIPHealthChecks.List(context.Background(), telnyx.GlobalIPHealthCheckListParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", page)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Create a Global IP health check

Create a Global IP health check.

POST /global_ip_health_checks

Optional: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

	globalIPHealthCheck, err := client.GlobalIPHealthChecks.New(context.Background(), telnyx.GlobalIPHealthCheckNewParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPHealthCheck.Data)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Retrieve a Global IP health check

Retrieve a Global IP health check.

GET /global_ip_health_checks/{id}

	globalIPHealthCheck, err := client.GlobalIPHealthChecks.Get(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPHealthCheck.Data)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Delete a Global IP health check

Delete a Global IP health check.

DELETE /global_ip_health_checks/{id}

	globalIPHealthCheck, err := client.GlobalIPHealthChecks.Delete(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPHealthCheck.Data)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Global IP Latency Metrics

GET /global_ip_latency

	globalIPLatency, err := client.GlobalIPLatency.Get(context.Background(), telnyx.GlobalIPLatencyGetParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPLatency.Data)

Returns: global_ip (object), mean_latency (object), percentile_latency (object), prober_location (object), timestamp (date-time)

List all Global IP Protocols

GET /global_ip_protocols

	globalIPProtocols, err := client.GlobalIPProtocols.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPProtocols.Data)

Returns: code (string), name (string), record_type (string)

Global IP Usage Metrics

GET /global_ip_usage

	globalIPUsage, err := client.GlobalIPUsage.Get(context.Background(), telnyx.GlobalIPUsageGetParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIPUsage.Data)

Returns: global_ip (object), received (object), timestamp (date-time), transmitted (object)

List all Global IPs

List all Global IPs.

GET /global_ips

	page, err := client.GlobalIPs.List(context.Background(), telnyx.GlobalIPListParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", page)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Create a Global IP

Create a Global IP.

POST /global_ips

Optional: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

	globalIP, err := client.GlobalIPs.New(context.Background(), telnyx.GlobalIPNewParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIP.Data)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Retrieve a Global IP

Retrieve a Global IP.

GET /global_ips/{id}

	globalIP, err := client.GlobalIPs.Get(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIP.Data)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Delete a Global IP

Delete a Global IP.

DELETE /global_ips/{id}

	globalIP, err := client.GlobalIPs.Delete(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", globalIP.Data)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)