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
The app centers around a ShipmentAgent
.
The agent owns:
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
Shipment status is not just data. It is a customer communication problem.
People want to know:
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.
When a carrier status changes, the app receives a webhook.
For example:
out_for_delivery
delayed
delivered
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.
The example uses:
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.
Clone the examples repo:
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/shipment-agent
Create a virtual environment:
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Copy the environment file:
cp .env.example .env
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
The app starts a Flask server locally, and you can connect the webhook URLs to your Telnyx messaging and voice configuration.
The sample is intentionally small. For a real logistics workflow, I would add:
But the architecture is the useful part. A shipment can become a durable communications object, not just a tracking number on a page.