Telnyx

Bindings allow your edge functions to interact with Telnyx platform services. They provide secure, auto-authenticated access without managing API keys in your code.

Available Bindings

Binding	Description	Status
Voice	Make and receive calls	✅ Available
Messaging	Send SMS/MMS	✅ Available
Phone Numbers	Manage numbers	✅ Available
Fax	Send faxes	✅ Available
Verify	2FA/verification	✅ Available
Cloud Storage	S3-compatible storage	✅ Available
KV	Key-value store	🔜 Coming soon
SQL DB	Serverless database	🔜 Coming soon

What is a Binding?

When you configure a binding for your function, you grant it the capability to access Telnyx services. The binding handles authentication automatically — your API key is never exposed in your code or logs.

Your Function → Binding Proxy → Telnyx API
      ↓              ↓              ↓
  Placeholder    Resolves      Actual API
  API Key        Credentials   Call Made

When you deploy a function with an active binding:

Your function receives placeholder credentials as environment variables
When your code calls the Telnyx SDK, the binding proxy intercepts the request
The proxy resolves the placeholder to your real API key
The API call proceeds with proper authentication

Benefits:

API key never appears in function code
API key never appears in logs
Credentials can be rotated without code changes

Creating a Binding

One-time setup per organization:

# Create a binding for your organization
telnyx-edge bindings create

# Verify the binding works
telnyx-edge bindings validate

Managing Bindings

# View your current binding
telnyx-edge bindings get

# Validate the binding is working
telnyx-edge bindings validate

# Rotate binding credentials (recommended monthly)
telnyx-edge bindings update

# Remove the binding
telnyx-edge bindings delete

Using Bindings: Telnyx API

With a binding configured, the Telnyx SDK automatically uses the injected credentials — no configuration required.

JavaScript
Go
Python
Java

const Telnyx = require('telnyx');

// SDK automatically uses TELNYX_API_KEY and TELNYX_BASE_URL
const telnyx = new Telnyx();

async function getBalance() {
    const balance = await telnyx.balance.retrieve();
    return {
        balance: balance.data.balance,
        currency: balance.data.currency
    };
}

async function sendMessage(to, from, text) {
    const message = await telnyx.messages.create({
        from: from,
        to: to,
        text: text
    });
    return { messageId: message.data.id };
}

package main

import (
    "fmt"
    "github.com/telnyx/telnyx-go"
)

func main() {
    // SDK automatically uses TELNYX_API_KEY and TELNYX_BASE_URL
    client := telnyx.NewClient()

    // Get account balance
    balance, err := client.Balance.Get()
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Balance: %s %s\n", balance.Balance, balance.Currency)
}

func sendMessage(to, from, text string) error {
    client := telnyx.NewClient()

    message, err := client.Messages.Create(&telnyx.MessageParams{
        From: from,
        To:   to,
        Text: text,
    })

    if err != nil {
        return err
    }

    fmt.Printf("Message sent: %s\n", message.ID)
    return nil
}

import telnyx

# SDK automatically uses TELNYX_API_KEY and TELNYX_BASE_URL
# No manual configuration needed!

def get_balance():
    """Retrieve account balance."""
    balance = telnyx.Balance.retrieve()
    return {
        "balance": balance.balance,
        "currency": balance.currency
    }

def send_message(to_number, from_number, text):
    """Send an SMS using Telnyx SDK."""
    message = telnyx.Message.create(
        from_=from_number,
        to=to_number,
        text=text
    )
    return {"message_id": message.id, "status": message.status}

def make_call(to_number, from_number, webhook_url):
    """Initiate an outbound call."""
    call = telnyx.Call.create(
        to=to_number,
        from_=from_number,
        connection_id="your-connection-id",
        webhook_url=webhook_url
    )
    return {"call_id": call.id}

import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.api.MessagesApi;
import com.telnyx.sdk.model.CreateMessageRequest;

@ApplicationScoped
public class MessageResource {

    // SDK automatically uses TELNYX_API_KEY and TELNYX_BASE_URL
    @Inject
    ApiClient telnyxClient;

    @POST
    @Path("/send")
    @Produces(MediaType.APPLICATION_JSON)
    public Response sendMessage(MessageRequest req) {
        MessagesApi api = new MessagesApi(telnyxClient);

        CreateMessageRequest request = new CreateMessageRequest()
            .from(req.getFrom())
            .to(req.getTo())
            .text(req.getText());

        var message = api.createMessage(request);

        return Response.ok(message).build();
    }
}

Using Bindings: Cloud Storage

Cloud Storage bindings use S3-compatible APIs rather than the Telnyx REST API.

Go
Python (boto3)

package main

import (
    "os"
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

func getStorageClient() *s3.S3 {
    sess := session.Must(session.NewSession(&aws.Config{
        Endpoint:    aws.String("https://us-east-1.telnyxcloudstorage.com"),
        Region:      aws.String("us-east-1"),
        Credentials: credentials.NewStaticCredentials(
            os.Getenv("TELNYX_API_KEY"),
            "", // Not required for Telnyx
            "",
        ),
    }))
    return s3.New(sess)
}

func listObjects(bucket string) ([]string, error) {
    client := getStorageClient()
    
    result, err := client.ListObjectsV2(&s3.ListObjectsV2Input{
        Bucket: aws.String(bucket),
    })
    if err != nil {
        return nil, err
    }
    
    var keys []string
    for _, obj := range result.Contents {
        keys = append(keys, *obj.Key)
    }
    return keys, nil
}

import os
import boto3

def get_storage_client():
    """Create a Cloud Storage client using binding credentials."""
    return boto3.client(
        's3',
        aws_access_key_id=os.environ.get('TELNYX_API_KEY'),
        aws_secret_access_key='',  # Not required for Telnyx
        endpoint_url='https://us-east-1.telnyxcloudstorage.com'
    )

def upload_file(bucket, key, data):
    """Upload a file to Cloud Storage."""
    client = get_storage_client()
    client.put_object(Bucket=bucket, Key=key, Body=data)
    return {"uploaded": key}

def download_file(bucket, key):
    """Download a file from Cloud Storage."""
    client = get_storage_client()
    response = client.get_object(Bucket=bucket, Key=key)
    return response['Body'].read()

def list_objects(bucket, prefix=''):
    """List objects in a bucket."""
    client = get_storage_client()
    response = client.list_objects_v2(Bucket=bucket, Prefix=prefix)
    return [obj['Key'] for obj in response.get('Contents', [])]

Native SDK support for Cloud Storage via bindings is in progress. Currently, use S3-compatible libraries (boto3, aws-sdk-go) with the binding credentials.

Using Bindings: KV

🔜 Coming soon — KV bindings will allow key-value storage directly from edge functions.

Using Bindings: SQL DB

🔜 Coming soon — SQL DB bindings will provide serverless database access from edge functions.

Bindings vs Secrets

Feature	Bindings	Secrets
Purpose	Telnyx service access	General sensitive data
Scope	One per organization	Unlimited per organization
Credentials	Auto-managed	User-provided
Injection	`TELNYX_API_KEY`, `TELNYX_BASE_URL`	Custom environment variables
Rotation	`bindings update`	Manual re-add
Use case	Telnyx SDK/API integration	Database passwords, external API keys

Use bindings for Telnyx service access — credentials are managed automatically. Use secrets for third-party services or when you need multiple different credentials.

Error Handling

import telnyx
from telnyx.error import TelnyxError, AuthenticationError, APIError

def safe_api_call():
    try:
        balance = telnyx.Balance.retrieve()
        return {"balance": balance.balance}

    except AuthenticationError as e:
        # Binding issue - credentials invalid or expired
        return {
            "error": "Authentication failed",
            "hint": "Try: telnyx-edge bindings update"
        }

    except APIError as e:
        # API-level error
        return {
            "error": f"API error: {e.message}",
            "code": e.code
        }

    except TelnyxError as e:
        # General Telnyx error
        return {"error": str(e)}

Troubleshooting

Binding not found

$ telnyx-edge bindings get
❌ No binding found

# Solution: Create a binding
$ telnyx-edge bindings create

Validation failed

$ telnyx-edge bindings validate
❌ Binding validation failed

# Solutions:
# 1. Update the binding
telnyx-edge bindings update

# 2. Check your Telnyx account status

# 3. Verify authentication
telnyx-edge auth status

Function can’t access Telnyx API

# Check binding exists
telnyx-edge bindings get

# Validate binding works
telnyx-edge bindings validate

# Redeploy function to get latest credentials
telnyx-edge ship

Overview

Getting Started

Examples

To Develop

To Test

To Deploy

To Monitor

Reference

Bindings

Available Bindings

What is a Binding?

Creating a Binding

Managing Bindings

Using Bindings: Telnyx API

Using Bindings: Cloud Storage

Using Bindings: KV

Using Bindings: SQL DB

Bindings vs Secrets

Error Handling

Troubleshooting

Binding not found

Validation failed

Function can’t access Telnyx API

Overview

Getting Started

Examples

To Develop

To Test

To Deploy

To Monitor

Reference

​Available Bindings

​What is a Binding?

​Creating a Binding

​Managing Bindings

​Using Bindings: Telnyx API

​Using Bindings: Cloud Storage

​Using Bindings: KV

​Using Bindings: SQL DB

​Bindings vs Secrets

​Error Handling

​Troubleshooting

​Binding not found

​Validation failed

​Function can’t access Telnyx API

Available Bindings

What is a Binding?

Creating a Binding

Managing Bindings

Using Bindings: Telnyx API

Using Bindings: Cloud Storage

Using Bindings: KV

Using Bindings: SQL DB

Bindings vs Secrets

Error Handling

Troubleshooting

Binding not found

Validation failed

Function can’t access Telnyx API