telnyx-ai-edge as the reference implementation.
What you’ll build
A support assistant for “Telnyx Logistics” that:- Greets callers by name (dynamic variables resolved from the caller’s phone number)
- Has a
lookup-ordertool the assistant can call to retrieve order status, carrier, and estimated delivery
Prerequisites
- A Telnyx account with Edge Compute enabled.
- The
telnyx-edgeCLI installed and authenticated. - An existing AI Assistant (or you can create one via API as shown below).
- Go 1.24+ installed locally (if following along with the Go sample).
Key concepts
Single function, two callbacks
Edge Compute routes all HTTP methods and paths under your function URL to your handler — path handling is up to your code (see Routes & Domains). The platform handles/health/liveness and /health/readiness probes automatically.
In this guide, both the dynamic variables webhook and the webhook tool call point to the same function URL, so the handler dispatches on the request body shape rather than the URL path:
- Dynamic variables webhook — Telnyx wraps the payload under
data.event_type. - Webhook tool call — the body is the flat arguments object from the tool’s
body_parametersschema (e.g.{"order_id": "ORD-10042"}).
/dynamic-variables and /tool/lookup-order) if you prefer path-based routing — both approaches work. This guide uses body-shape dispatch to keep everything at a single URL.
Webhook signature verification
Telnyx signs every dynamic-variables webhook and webhook tool call with an Ed25519 key. The signature is in thetelnyx-signature-ed25519 header, and the timestamp is in telnyx-timestamp. The signed message is "{timestamp}|{raw_body}".
You must verify this signature to confirm the request is genuinely from Telnyx. Your org’s public key is available at:
data.public (not data.public_key) — the base64-encoded Ed25519 public key.
Dynamic variables response format
The response must nest variables under adynamic_variables key. A flat object (e.g. {"customer_name": "James"}) is silently ignored — variables will remain unresolved.
Timeout
The default dynamic variables webhook timeout is 1,500 ms. Edge Compute functions may occasionally need more time on a cold start, so consider settingdynamic_variables_webhook_timeout_ms on the assistant to a higher value (up to 10,000 ms). A value of 8,000 ms is a reasonable choice for edge backends.
Step 1: Scaffold the function
func.toml with the registered function ID and a Go handler scaffold.
The Go module must be named
function (package function, entrypoint Handle(w, r)). Other module names fail to build: “malformed module path: missing dot in first path element.” Use go 1.24 in go.mod.Step 2: Store the public key as a secret
Fetch your org’s public key and store it as an encrypted secret. The public key endpoint requires authentication — use your Telnyx API key:os.Getenv("TELNYX_PUBLIC_KEY") at startup. Secrets are never visible in secrets list — only the name is shown.
Step 3: Write the handler
The handler does three things:- Verifies the Telnyx Ed25519 signature on every request
- Detects whether the request is a dynamic-variables webhook or a tool call
- Returns the appropriate response
handler.go
Step 4: Ship the function
uploaded successfully, poll telnyx-edge list until the status shows deploy_ok. Don’t trust a CLI timeout as a failure — the function may still be building server-side.
Step 5: Configure the AI Assistant
Set the function URL as both the dynamic variables webhook URL and the webhook tool URL on the assistant.Dynamic variables webhook
In the Portal or via the API:| Field | Value |
|---|---|
dynamic_variables_webhook_url | https://telnyx-ai-edge-<org>.telnyxcompute.com/ |
dynamic_variables_webhook_timeout_ms | 8000 |
Template variables in the assistant
Use{{variable_name}} in the assistant’s instructions and greeting to reference the variables your function returns:
Webhook tool
Add a webhook tool that points to the same function URL:lookup-order, Telnyx sends a POST with the tool arguments as the flat body ({"order_id": "ORD-10042"}), signed with the same Ed25519 key. Your function detects the body shape, handles it as a tool call, and returns the result.
Step 6: Test end-to-end
-
Call the function directly (without a signature — it’ll return 403, confirming it’s live):
-
Make a test call to the assistant from the Portal or via the API:
-
Verify in the conversation transcript that:
- The greeting includes the resolved
customer_name - The assistant can call
lookup-orderand read back real order data
- The greeting includes the resolved
Tips and gotchas
Choosing body-shape vs path-based dispatch
Since Edge Compute routes all paths to your handler, you can use path-based routing (e.g.r.URL.Path == "/tool/lookup-order") or body-shape dispatch as shown in this guide. Both work. If you configure separate URLs for the DV webhook and the tool on the assistant, path-based routing is natural. If you point both at the same URL, body-shape dispatch is the way to go.
For a path-based routing example, see the RESTful API example in the Edge Compute CLI repo.
Consider a higher webhook timeout
The default dynamic variables webhook timeout is 1,500 ms. Edge Compute functions may occasionally need a bit more time on a cold start, so consider settingdynamic_variables_webhook_timeout_ms to 8,000 ms to give the function room. The maximum is 10,000 ms.
Always verify signatures
Without signature verification, anyone who knows your function URL can inject fake dynamic variables or tool responses. Thetelnyx-signature-ed25519 and telnyx-timestamp headers are present on every request from Telnyx.
Ship takes a few minutes
A normal ship takes 2–3 minutes. The CLI’s build monitor has a 5-minute timeout, but the build continues server-side regardless. If the CLI reports a timeout, checktelnyx-edge list for the actual status before retrying — the function may have deployed successfully.
Secrets require re-shipping
Adding or changing a secret (telnyx-edge secrets add) does not affect an already-deployed function. Run telnyx-edge ship again to pick up the new secret.
The dynamic_variables wrapper is mandatory
Returning a flat JSON object like {"customer_name": "James"} will be silently ignored. Variables must be nested under dynamic_variables:
Next steps
- Dynamic Variables — full reference for the DV webhook payload and resolution precedence.
- Webhook signing — how Telnyx signs webhooks and how to verify signatures.
- Edge Compute quickstart — getting started with your first function.
- Secrets — encrypted, org-scoped environment variables.
- Bindings — pre-authenticated Telnyx API client for your function.