Telnyx Numbers Config - Go

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

Phone numbers must be in E.164 format (e.g., +13125550001). Include the + prefix and country code. No spaces, dashes, or parentheses.
Pagination: Use ListAutoPaging() for automatic iteration: iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }.

Bulk update phone number profiles

POST /messagingnumbersbulkupdates — Required: messagingprofile_id, numbers

Optional: assign_only (boolean)

	messagingNumbersBulkUpdate, err := client.MessagingNumbersBulkUpdates.New(context.Background(), telnyx.MessagingNumbersBulkUpdateNewParams{
		MessagingProfileID: "00000000-0000-0000-0000-000000000000",
		Numbers:            []string{"+18880000000", "+18880000001", "+18880000002"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", messagingNumbersBulkUpdate.Data)

Returns: failed (array[string]), orderid (uuid), pending (array[string]), recordtype (enum: messagingnumbersbulk_update), success (array[string])

Retrieve bulk update status

GET /messagingnumbersbulkupdates/{orderid}

	messagingNumbersBulkUpdate, err := client.MessagingNumbersBulkUpdates.Get(context.Background(), "order_id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", messagingNumbersBulkUpdate.Data)

Returns: failed (array[string]), orderid (uuid), pending (array[string]), recordtype (enum: messagingnumbersbulk_update), success (array[string])

List mobile phone numbers with messaging settings

GET /mobilephonenumbers/messaging

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

Returns: countrycode (string), createdat (date-time), features (object), id (string), messagingproduct (string), messagingprofileid (string | null), organizationid (string), phonenumber (string), recordtype (enum: messagingphonenumber, messagingsettings), tags (array[string]), traffictype (string), type (enum: longcode), updated_at (date-time)

Retrieve a mobile phone number with messaging settings

GET /mobilephonenumbers/{id}/messaging

	messaging, err := client.MobilePhoneNumbers.Messaging.Get(context.Background(), "id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", messaging.Data)

List phone numbers

GET /phone_numbers

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

Returns: activatedat (object), billinggroupid (string | null), callforwardingenabled (boolean), callrecordingenabled (boolean), calleridnameenabled (boolean), cnamlistingenabled (boolean), connectionid (string | null), connectionname (string | null), countryisoalpha2 (string), createdat (date-time), customerreference (string | null), deletionlockenabled (boolean), emergencyaddressid (string | null), emergencyenabled (boolean), emergencystatus (enum: active, deprovisioning, disabled, provisioning, provisioning-failed), externalpin (string | null), hdvoiceenabled (boolean), id (string), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), messagingprofileid (string | null), messagingprofilename (string | null), phonenumber (string), phonenumbertype (enum: local, tollfree, mobile, national, sharedcost, landline, tollfree, shortcode, longcode), purchasedat (string), recordtype (string), sourcetype (object), status (enum: purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending, requirement-info-pending, requirement-info-under-review, requirement-info-exception, provision-pending), t38faxgatewayenabled (boolean), tags (array[string]), updated_at (string)

Verify ownership of phone numbers

Verifies ownership of the provided phone numbers and returns a mapping of numbers to their IDs, plus a list of numbers not found in the account.

POST /phonenumbers/actions/verifyownership — Required: phone_numbers

	response, err := client.PhoneNumbers.Actions.VerifyOwnership(context.Background(), telnyx.PhoneNumberActionVerifyOwnershipParams{
		PhoneNumbers: []string{"+15551234567"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns: found (array[object]), notfound (array[string]), recordtype (string)

Lists the phone numbers jobs

GET /phone_numbers/jobs

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

Returns: createdat (string), etc (date-time), failedoperations (array[object]), id (uuid), pendingoperations (array[object]), phonenumbers (array[object]), recordtype (string), status (enum: pending, inprogress, completed, failed, expired), successfuloperations (array[object]), type (enum: updateemergencysettings, deletephonenumbers, updatephonenumbers), updatedat (string)

Delete a batch of numbers

Creates a new background job to delete a batch of numbers. At most one thousand numbers can be updated per API call.

POST /phonenumbers/jobs/deletephonenumbers — Required: phonenumbers

	response, err := client.PhoneNumbers.Jobs.DeleteBatch(context.Background(), telnyx.PhoneNumberJobDeleteBatchParams{
		PhoneNumbers: []string{"+19705555098", "+19715555098", "32873127836"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Update the emergency settings from a batch of numbers

Creates a background job to update the emergency settings of a collection of phone numbers. At most one thousand numbers can be updated per API call.

POST /phonenumbers/jobs/updateemergencysettings — Required: emergencyenabled, phone_numbers

Optional: emergencyaddressid (string | null)

	response, err := client.PhoneNumbers.Jobs.UpdateEmergencySettingsBatch(context.Background(), telnyx.PhoneNumberJobUpdateEmergencySettingsBatchParams{
		EmergencyEnabled: true,
		PhoneNumbers:     []string{"+19705555098", "+19715555098", "32873127836"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Update a batch of numbers

Creates a new background job to update a batch of numbers. At most one thousand numbers can be updated per API call. At least one of the updateable fields must be submitted.

POST /phonenumbers/jobs/updatephonenumbers — Required: phonenumbers

Optional: billinggroupid (string), connectionid (string), customerreference (string), deletionlockenabled (boolean), externalpin (string), hdvoice_enabled (boolean), tags (array[string]), voice (object)

	response, err := client.PhoneNumbers.Jobs.UpdateBatch(context.Background(), telnyx.PhoneNumberJobUpdateBatchParams{
		PhoneNumbers: []string{"1583466971586889004", "+13127367254"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Retrieve a phone numbers job

GET /phone_numbers/jobs/{id}

	job, err := client.PhoneNumbers.Jobs.Get(context.Background(), "id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", job.Data)

List phone numbers with messaging settings

GET /phone_numbers/messaging

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

Returns: countrycode (string), createdat (date-time), eligiblemessagingproducts (array[string]), features (object), health (object), id (string), messagingproduct (string), messagingprofileid (string | null), organizationid (string), phonenumber (string), recordtype (enum: messagingphonenumber, messagingsettings), tags (array[string]), traffictype (string), type (enum: long-code, toll-free, short-code, longcode, tollfree, shortcode), updated_at (date-time)

Slim List phone numbers

List phone numbers, This endpoint is a lighter version of the /phone_numbers endpoint having higher performance and rate limit.

GET /phone_numbers/slim

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

Returns: activatedat (object), billinggroupid (string), callforwardingenabled (boolean), callrecordingenabled (boolean), calleridnameenabled (boolean), cnamlistingenabled (boolean), connectionid (string), countryisoalpha2 (string), createdat (string), customerreference (string), emergencyaddressid (string), emergencyenabled (boolean), emergencystatus (enum: active, deprovisioning, disabled, provisioning, provisioning-failed), externalpin (string), hdvoiceenabled (boolean), id (string), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), phonenumber (string), phonenumbertype (enum: local, tollfree, mobile, national, sharedcost, landline, tollfree, shortcode, longcode), purchasedat (string), recordtype (string), status (enum: purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending, requirement-info-pending, requirement-info-under-review, requirement-info-exception, provision-pending), t38faxgatewayenabled (boolean), updated_at (string)

List phone numbers with voice settings

GET /phone_numbers/voice

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

Returns: callforwarding (object), callrecording (object), cnamlisting (object), connectionid (string), customerreference (string), emergency (object), id (string), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), mediafeatures (object), phonenumber (string), recordtype (string), techprefixenabled (boolean), translatednumber (string), usagepayment_method (enum: pay-per-minute, channel)

Retrieve a phone number

GET /phone_numbers/{id}

	phoneNumber, err := client.PhoneNumbers.Get(context.Background(), "1293384261075731499")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", phoneNumber.Data)

Update a phone number

PATCH /phone_numbers/{id}

Optional: addressid (string), billinggroupid (string), connectionid (string), customerreference (string), externalpin (string), hdvoiceenabled (boolean), id (string), tags (array[string])

	phoneNumber, err := client.PhoneNumbers.Update(
		context.Background(),
		"1293384261075731499",
		telnyx.PhoneNumberUpdateParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", phoneNumber.Data)

Delete a phone number

DELETE /phone_numbers/{id}

	phoneNumber, err := client.PhoneNumbers.Delete(context.Background(), "1293384261075731499")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", phoneNumber.Data)

Returns: activatedat (object), billinggroupid (string), callforwardingenabled (boolean), callrecordingenabled (boolean), calleridnameenabled (boolean), cnamlistingenabled (boolean), connectionid (string), connectionname (string), createdat (string), customerreference (string), deletionlockenabled (boolean), emergencyaddressid (string), emergencyenabled (boolean), externalpin (string), hdvoiceenabled (boolean), id (string), messagingprofileid (string), messagingprofilename (string), phonenumber (string), phonenumbertype (enum: local, tollfree, mobile, national, sharedcost, landline), purchasedat (string), recordtype (string), status (enum: purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending), t38faxgatewayenabled (boolean), tags (array[string]), updated_at (string)

Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)

PATCH /phonenumbers/{id}/actions/bundlestatuschange — Required: bundleid

	response, err := client.PhoneNumbers.Actions.ChangeBundleStatus(
		context.Background(),
		"1293384261075731499",
		telnyx.PhoneNumberActionChangeBundleStatusParams{
			BundleID: "5194d8fc-87e6-4188-baa9-1c434bbe861b",
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Enable emergency for a phone number

POST /phonenumbers/{id}/actions/enableemergency — Required: emergencyenabled, emergencyaddress_id

	response, err := client.PhoneNumbers.Actions.EnableEmergency(
		context.Background(),
		"1293384261075731499",
		telnyx.PhoneNumberActionEnableEmergencyParams{
			EmergencyAddressID: "53829456729313",
			EmergencyEnabled:   true,
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Retrieve a phone number with messaging settings

GET /phone_numbers/{id}/messaging

	messaging, err := client.PhoneNumbers.Messaging.Get(context.Background(), "id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", messaging.Data)

Update the messaging profile and/or messaging product of a phone number

PATCH /phone_numbers/{id}/messaging

Optional: messagingproduct (string), messagingprofile_id (string), tags (array[string])

	messaging, err := client.PhoneNumbers.Messaging.Update(
		context.Background(),
		"id",
		telnyx.PhoneNumberMessagingUpdateParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", messaging.Data)

Retrieve a phone number with voice settings

GET /phone_numbers/{id}/voice

	voice, err := client.PhoneNumbers.Voice.Get(context.Background(), "1293384261075731499")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", voice.Data)

Update a phone number with voice settings

PATCH /phone_numbers/{id}/voice

Optional: callforwarding (object), callrecording (object), calleridnameenabled (boolean), cnamlisting (object), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), mediafeatures (object), techprefixenabled (boolean), translatednumber (string), usagepaymentmethod (enum: pay-per-minute, channel)

	voice, err := client.PhoneNumbers.Voice.Update(
		context.Background(),
		"1293384261075731499",
		telnyx.PhoneNumberVoiceUpdateParams{
			UpdateVoiceSettings: telnyx.UpdateVoiceSettingsParam{},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", voice.Data)

List Mobile Phone Numbers

GET /v2/mobilephonenumbers

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

Returns: callforwarding (object), callrecording (object), calleridnameenabled (boolean), cnamlisting (object), connectionid (string | null), connectionname (string | null), connectiontype (string | null), countryisoalpha2 (string), createdat (date-time), customerreference (string | null), id (string), inbound (object), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), mobilevoiceenabled (boolean), noisesuppression (enum: inbound, outbound, both, disabled), outbound (object), phonenumber (string), recordtype (string), simcardid (uuid), status (string), tags (array[string]), updated_at (date-time)

Retrieve a Mobile Phone Number

GET /v2/mobilephonenumbers/{id}

	mobilePhoneNumber, err := client.MobilePhoneNumbers.Get(context.Background(), "id")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", mobilePhoneNumber.Data)

Update a Mobile Phone Number

PATCH /v2/mobilephonenumbers/{id}

Optional: callforwarding (object), callrecording (object), calleridnameenabled (boolean), cnamlisting (object), connectionid (string | null), customerreference (string | null), inbound (object), inboundcallscreening (enum: disabled, rejectcalls, flagcalls), noise_suppression (boolean), outbound (object), tags (array[string])

	mobilePhoneNumber, err := client.MobilePhoneNumbers.Update(
		context.Background(),
		"id",
		telnyx.MobilePhoneNumberUpdateParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", mobilePhoneNumber.Data)

telnyx-numbers-config-go

Installation

Similar popular skills

Also in this package

Agent compatibility

Repository health

Skill metadata

Package contents

History

SKILL.md

Telnyx Numbers Config - Go

Installation

Setup

Error Handling

Important Notes

Bulk update phone number profiles

Retrieve bulk update status

List mobile phone numbers with messaging settings

Retrieve a mobile phone number with messaging settings

List phone numbers

Verify ownership of phone numbers

Lists the phone numbers jobs

Delete a batch of numbers

Update the emergency settings from a batch of numbers

Update a batch of numbers

Retrieve a phone numbers job

List phone numbers with messaging settings

Slim List phone numbers

List phone numbers with voice settings

Retrieve a phone number

Update a phone number

Delete a phone number

Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)

Enable emergency for a phone number

Retrieve a phone number with messaging settings

Update the messaging profile and/or messaging product of a phone number

Retrieve a phone number with voice settings

Update a phone number with voice settings

List Mobile Phone Numbers

Retrieve a Mobile Phone Number

Update a Mobile Phone Number