/telnyx-voice-go

name: telnyx-voice-go
description: >-
  Programmatic call control: make/receive calls, transfer, bridge, gather DTMF,
  stream audio. Real-time call events via webhooks.
metadata:
  author: telnyx
  product: voice
  language: go
  generated_by: telnyx-openapi-pipeline
  contract: v2

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Voice - 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")),
  option.WithPublicKey(os.Getenv("TELNYX_PUBLIC_KEY")), // Required for client.Webhooks.Unwrap (webhook verification)
)

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"

response, err := client.Calls.Dial(context.Background(), telnyx.CallDialParams{
		ConnectionID: "7267xxxxxxxxxxxxxx",
		From:         "+18005550101",
		To: telnyx.CallDialParamsToUnion{
			OfString: telnyx.String("+18005550100"),
		},
	})
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, then retry the request (bounded 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")
  }
  return err // Propagate: a failed request must never look like success to the caller
}

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() }`.

Operational Caveats

• Call Control is event-driven. After `dial()` or an inbound webhook, issue follow-up commands from webhook handlers using the `call_control_id` in the event payload.
• Outbound and inbound flows are different: outbound calls start with `dial()`, while inbound calls must be answered from the incoming webhook before other commands run.
• A publicly reachable webhook endpoint is required for real call control. Without it, calls may connect but your application cannot drive the live call state.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

• If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
• Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).
• Before reading or matching webhook fields beyond the inline examples, read [the webhook payload reference](references/api-details.md#webhook-payload-fields).

Core Tasks

Dial an outbound call

Primary voice entrypoint. Agents need the async call-control identifiers returned here.

`client.Calls.Dial()` — `POST /calls`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `To` | string (E.164) | Yes | The DID or SIP URI to dial out to. | | `From` | string (E.164) | Yes | The `from` number to be used as the caller id presented to t... | | `ConnectionId` | string (UUID) | Yes | The ID of the Call Control App (formerly ID of the connectio... | | `TimeoutSecs` | integer | No | The number of seconds that Telnyx will wait for the call to ... | | `BillingGroupId` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `ClientState` | string | No | Use this field to add state to every subsequent webhook. | | ... | | | +59 optional params in [references/api-details.md](references/api-details.md) |

	response, err := client.Calls.Dial(context.Background(), telnyx.CallDialParams{
		ConnectionID: "7267xxxxxxxxxxxxxx",
		From:         "+18005550101",
		To: telnyx.CallDialParamsToUnion{
			OfString: telnyx.String("+18005550100"),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Primary response fields:

• `response.Data.CallControlID`
• `response.Data.CallLegID`
• `response.Data.CallSessionID`
• `response.Data.IsAlive`
• `response.Data.RecordingID`
• `response.Data.CallDuration`

Answer an inbound call

Primary inbound call-control command.

`client.Calls.Actions.Answer()` — `POST /calls/{call_control_id}/actions/answer`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `CallControlId` | string (UUID) | Yes | Unique identifier and token for controlling the call | | `BillingGroupId` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `ClientState` | string | No | Use this field to add state to every subsequent webhook. | | `WebhookUrl` | string (URL) | No | Use this field to override the URL for which Telnyx will sen... | | ... | | | +29 optional params in [references/api-details.md](references/api-details.md) |

	response, err := client.Calls.Actions.Answer(
		context.Background(),
		"call_control_id",
		telnyx.CallActionAnswerParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.