--- name: telnyx-account-go description: >- Manage account balance, payments, invoices, webhooks, and view audit logs and detail records. This skill provides Go SDK examples. metadata: author: telnyx product: account language: go generated_by: telnyx-ext-skills-generator --- # Telnyx Account - Go ## Installation ```bash go get github.com/team-telnyx/telnyx-go ``` ## Setup ```go 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: ```go 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 Audit Logs Retrieve a list of audit log entries. Audit logs are a best-effort, eventually consistent record of significant account-related changes. `GET /audit_events` ```go page, err := client.AuditEvents.List(context.Background(), telnyx.AuditEventListParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", page) ``` Returns: `alternate_resource_id` (string | null), `change_made_by` (enum: telnyx, account_manager, account_owner, organization_member), `change_type` (string), `changes` (array | null), `created_at` (date-time), `id` (uuid), `organization_id` (uuid), `record_type` (string), `resource_id` (string), `user_id` (uuid) ## Get user balance details `GET /balance` ```go balance, err := client.Balance.Get(context.Background()) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", balance.Data) ``` Returns: `available_credit` (string), `balance` (string), `credit_limit` (string), `currency` (string), `pending` (string), `record_type` (enum: balance) ## Get monthly charges breakdown Retrieve a detailed breakdown of monthly charges for phone numbers in a specified date range. The date range cannot exceed 31 days. `GET /charges_breakdown` ```go chargesBreakdown, err := client.ChargesBreakdown.Get(context.Background(), telnyx.ChargesBreakdownGetParams{ StartDate: time.Now(), }) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", chargesBreakdown.Data) ``` Returns: `currency` (string), `end_date` (date), `results` (array[object]), `start_date` (date), `user_email` (email), `user_id` (string) ## Get monthly charges summary Retrieve a summary of monthly charges for a specified date range. The date range cannot exceed 31 days. `GET /charges_summary` ```go chargesSummary, err := client.ChargesSummary.Get(context.Background(), telnyx.ChargesSummaryGetParams{ EndDate: time.Now(), StartDate: time.Now(), }) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", chargesSummary.Data) ``` Returns: `currency` (string), `end_date` (date), `start_date` (date), `summary` (object), `total` (object), `user_email` (email), `user_id` (string) ## Search detail records Search for any detail record across the Telnyx Platform `GET /detail_records` ```go page, err := client.DetailRecords.List(context.Background(), telnyx.DetailRecordListParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", page) ``` Returns: `carrier` (string), `carrier_fee` (string), `cld` (string), `cli` (string), `completed_at` (date-time), `cost` (string), `country_code` (string), `created_at` (date-time), `currency` (string), `delivery_status` (string), `delivery_status_failover_url` (string), `delivery_status_webhook_url` (string), `direction` (enum: inbound, outbound), `errors` (array[string]), `fteu` (boolean), `mcc` (string), `message_type` (enum: SMS, MMS, RCS), `mnc` (string), `on_net` (boolean), `parts` (integer), `profile_id` (string), `profile_name` (string), `rate` (string), `record_type` (string), `sent_at` (date-time), `source_country_code` (string), `status` (enum: gw_timeout, delivered, dlr_unconfirmed, dlr_timeout, received, gw_reject, failed), `tags` (string), `updated_at` (date-time), `user_id` (string), `uuid` (string) ## List invoices Retrieve a paginated list of invoices. `GET /invoices` ```go page, err := client.Invoices.List(context.Background(), telnyx.InvoiceListParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", page) ``` Returns: `file_id` (uuid), `invoice_id` (uuid), `paid` (boolean), `period_end` (date), `period_start` (date), `url` (uri) ## Get invoice by ID Retrieve a single invoice by its unique identifier. `GET /invoices/{id}` ```go invoice, err := client.Invoices.Get( context.Background(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", telnyx.InvoiceGetParams{}, ) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", invoice.Data) ``` Returns: `download_url` (uri), `file_id` (uuid), `invoice_id` (uuid), `paid` (boolean), `period_end` (date), `period_start` (date), `url` (uri) ## List auto recharge preferences Returns the payment auto recharge preferences. `GET /payment/auto_recharge_prefs` ```go autoRechargePrefs, err := client.Payment.AutoRechargePrefs.List(context.Background()) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", autoRechargePrefs.Data) ``` Returns: `enabled` (boolean), `id` (string), `invoice_enabled` (boolean), `preference` (enum: credit_paypal, ach), `recharge_amount` (string), `record_type` (string), `threshold_amount` (string) ## Update auto recharge preferences Update payment auto recharge preferences. `PATCH /payment/auto_recharge_prefs` Optional: `enabled` (boolean), `invoice_enabled` (boolean), `preference` (enum: credit_paypal, ach), `recharge_amount` (string), `threshold_amount` (string) ```go autoRechargePref, err := client.Payment.AutoRechargePrefs.Update(context.Background(), telnyx.PaymentAutoRechargePrefUpdateParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", autoRechargePref.Data) ``` Returns: `enabled` (boolean), `id` (string), `invoice_enabled` (boolean), `preference` (enum: credit_paypal, ach), `recharge_amount` (string), `record_type` (string), `threshold_amount` (string) ## List User Tags List all user tags. `GET /user_tags` ```go userTags, err := client.UserTags.List(context.Background(), telnyx.UserTagListParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", userTags.Data) ``` Returns: `number_tags` (array[string]), `outbound_profile_tags` (array[string]) ## Create a stored payment transaction `POST /v2/payment/stored_payment_transactions` — Required: `amount` ```go response, err := client.Payment.NewStoredPaymentTransaction(context.Background(), telnyx.PaymentNewStoredPaymentTransactionParams{ Amount: "120.00", }) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", response.Data) ``` Returns: `amount_cents` (integer), `amount_currency` (string), `auto_recharge` (boolean), `created_at` (date-time), `id` (string), `processor_status` (string), `record_type` (enum: transaction), `transaction_processing_type` (enum: stored_payment) ## List webhook deliveries Lists webhook_deliveries for the authenticated user `GET /webhook_deliveries` ```go page, err := client.WebhookDeliveries.List(context.Background(), telnyx.WebhookDeliveryListParams{}) if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", page) ``` Returns: `attempts` (array[object]), `finished_at` (date-time), `id` (uuid), `record_type` (string), `started_at` (date-time), `status` (enum: delivered, failed), `user_id` (uuid), `webhook` (object) ## Find webhook_delivery details by ID Provides webhook_delivery debug data, such as timestamps, delivery status and attempts. `GET /webhook_deliveries/{id}` ```go webhookDelivery, err := client.WebhookDeliveries.Get(context.Background(), "C9C0797E-901D-4349-A33C-C2C8F31A92C2") if err != nil { log.Fatal(err) } fmt.Printf("%+v\n", webhookDelivery.Data) ``` Returns: `attempts` (array[object]), `finished_at` (date-time), `id` (uuid), `record_type` (string), `started_at` (date-time), `status` (enum: delivered, failed), `user_id` (uuid), `webhook` (object)