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:
```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
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
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
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
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
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
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}
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
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)
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
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
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
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}
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)