DEV Community

Sonam
Sonam

Posted on

Build an AI Shipment Agent with SMS, Voice, and Telnyx Inference

#ai #python #voice #telnyx

Most package tracking flows make the customer do the work.

You get a tracking number. You open a page. You refresh it. Maybe you get a generic text that says the package is out for delivery. If you need to ask a real question, you usually end up somewhere else entirely.

I wanted to build the opposite shape: what if the package itself had an agent?

The shipment-agent example is a Python and Flask app that treats a shipment as a durable AI entity. It can send proactive SMS updates, understand customer replies with Telnyx AI Inference, and answer inbound calls with shipment context.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/shipment-agent

What it builds

The app centers around a ShipmentAgent.

The agent owns:

  • shipment status
  • carrier and tracking context
  • customer phone number
  • interaction history
  • messaging and voice behavior

Instead of a stateless chatbot waiting in a web page, the agent lives alongside the shipment lifecycle.

Carrier update
  -> Flask webhook
  -> ShipmentAgent updates state
  -> SMS customer

Customer SMS reply
  -> Telnyx Messaging webhook
  -> AI Inference response
  -> SMS reply

Customer phone call
  -> Telnyx Call Control
  -> ShipmentAgent answers with context
Enter fullscreen mode Exit fullscreen mode

Why this is useful

Shipment status is not just data. It is a customer communication problem.

People want to know:

  • Is my package delayed?
  • Can I leave delivery instructions?
  • Did it already arrive?
  • Who do I call if something looks wrong?

Traditional tracking pages are good at showing status, but not at handling conversation. This example shows how to turn the shipment into a small communications agent that can respond across SMS and voice.

The main flow

When a carrier status changes, the app receives a webhook.

For example:

out_for_delivery
delayed
delivered
Enter fullscreen mode Exit fullscreen mode

The ShipmentAgent updates its internal state and sends a message to the customer through Telnyx Messaging.

If the customer replies, the app passes the message and shipment context to Telnyx AI Inference. That lets the response include the current shipment state instead of acting like a generic support bot.

If the customer calls the Telnyx number, the Call Control flow can answer with the same context.

That is the key idea: SMS and voice are not separate experiences. They are two ways to talk to the same shipment agent.

Telnyx pieces used

The example uses:

  • Telnyx Messaging for proactive SMS updates and customer replies
  • Telnyx Call Control for inbound voice interactions
  • Telnyx AI Inference for natural language processing
  • Telnyx webhook signing to verify inbound events

Webhook verification matters here because the agent updates customer-facing shipment state based on incoming events. You want to know those events are authentic before they change what the agent does.

Running the example

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/shipment-agent
Enter fullscreen mode Exit fullscreen mode

Create a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Copy the environment file:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Fill in the required Telnyx values:

  • TELNYX_API_KEY
  • TELNYX_FROM_NUMBER
  • TELNYX_MESSAGING_PROFILE_ID
  • TELNYX_PUBLIC_KEY
  • TELNYX_TO_NUMBER

Then run:

python app.py
Enter fullscreen mode Exit fullscreen mode

The app starts a Flask server locally, and you can connect the webhook URLs to your Telnyx messaging and voice configuration.

What I would add for production

The sample is intentionally small. For a real logistics workflow, I would add:

  • persistent database storage
  • idempotency for carrier events
  • richer delivery instruction handling
  • customer authentication
  • escalation to a human support team
  • retries for SMS and webhook processing
  • observability around missed or delayed events

But the architecture is the useful part. A shipment can become a durable communications object, not just a tracking number on a page.

Resources

Top comments (0)