telnyx-messaging-go

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

# Telnyx Messaging - 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"

response, err := client.Messages.Send(context.Background(), telnyx.MessageSendParams{
		To: "+18445550001",
		From: "+18005550101",
		Text: "Hello from Telnyx!",
	})
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:
      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() }`.

## Operational Caveats

- The sending number must already be assigned to the correct messaging profile before you send traffic from it.
- US A2P long-code traffic must complete 10DLC registration before production sending or carriers will block or heavily filter messages.
- Delivery webhooks are asynchronous. Treat the send response as acceptance of the request, not final carrier delivery.

## 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

### Send an SMS

Primary outbound messaging flow. Agents need exact request fields and delivery-related response fields.

`client.Messages.Send()` — `POST /messages`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `To` | string (E.164) | Yes | Receiving address (+E.164 formatted phone number or short co... |
| `From` | string (E.164) | Yes | Sending address (+E.164 formatted phone number, alphanumeric... |
| `Text` | string | Yes | Message body (i.e., content) as a non-empty string. |
| `MessagingProfileId` | string (UUID) | No | Unique identifier for a messaging profile. |
| `MediaUrls` | array[string] | No | A list of media URLs. |
| `WebhookUrl` | string (URL) | No | The URL where webhooks related to this message will be sent. |
| ... | | | +7 optional params in [references/api-details.md](references/api-details.md) |

```go
	response, err := client.Messages.Send(context.Background(), telnyx.MessageSendParams{
		To: "+18445550001",
		From: "+18005550101",
		Text: "Hello from Telnyx!",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)
```

Primary response fields:
- `response.Data.ID`
- `response.Data.To`
- `response.Data.From`
- `response.Data.Text`
- `response.Data.SentAt`
- `response.Data.Errors`

### Send an SMS with an alphanumeric sender ID

Common sender variant that requires different request shape.

`client.Messages.SendWithAlphanumericSender()` — `POST /messages/alphanumeric_sender_id`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `From` | string (E.164) | Yes | A valid alphanumeric sender ID on the user's account. |
| `To` | string (E.164) | Yes | Receiving address (+E.164 formatted phone number or short co... |
| `Text` | string | Yes | The message body. |
| `MessagingProfileId` | string (UUID) | Yes | The messaging profile ID to use. |
| `WebhookUrl` | string (URL) | No | Callback URL for delivery status updates. |
| `WebhookFailoverUrl` | string (URL) | No | Failover callback URL for delivery status updates. |
| `UseProfileWebhooks` | boolean | No | If true, use the messaging profile's webhook settings. |

```go
	response, err := client.Messages.SendWithAlphanumericSender(context.Background(), telnyx.MessageSendWithAlphanumericSenderParams{
		From:               "MyCompany",
		MessagingProfileID: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
		Text: "Hello from Telnyx!",
		To: "+13125550001",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)
```

Primary response fields:
- `response.Data.ID`
- `response.Data.To`
- `response.Data.From`
- `response.Data.Text`
- `response.Data.SentAt`
- `response.Data.Errors`

---

### Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes `telnyx-signature-ed25519`
and `telnyx-timestamp` headers. Always verify signatures in production:

```go
// In your webhook handler:
func handleWebhook(w http.ResponseWriter, r *http.Request) {
  body, _ := io.ReadAll(r.Body)
  event, err := client.Webhooks.Unwrap(body, r.Header)
  if err != nil {
    http.Error(w, "Invalid signature", h