Kivvi offers a Telegram bot that allows you to manage your shipments, track packages, and perform various actions directly from your messaging app. This guide covers all available features and commands.
Register in Telegram Bot
Sign in to your account. If you don't have a Telegram bot account, locate the "Telegram" card and press the "Register in Telegram" button. The card remains visible until you complete the registration.
You will be redirected to the Telegram bot. To begin, enter or select the /start command. Please check all the bot features in that post.
Telegram Notifications
The bot sends automatic notifications to users via Telegram when certain actions occur.
Package Actions
| Event | Notification |
|---|---|
| Awaited Package Created | "We are expecting a new package for you. Tracking number: %(reference name)s." |
| New Package Received | "We have received a new package for you. Tracking number: %(package)s. It will be processed soon." |
| Package Processed | "Your package %(package)s has been processed. Package contents: %(item)s: %(quantity)s" |
| Smartpost Order Shipped | "Shipment %(shipment name)s containing your packages was shipped." |
| Package Ready for Pickup | "{QR code image} Your package(s) %(package)s are now with our delivery partner and ready for pickup at our %(warehouse.partner.city)s, office: %(warehouse.partner.address)s. For more details, please contact us at %(warehouse.partner.phone)s. Please present this QR code at the pickup point. The QR code contains your package details and will be scanned to confirm the pickup." |
Picking Validation
Notifications are sent when the configured operation type is validated.
| Operation Type | Notification |
|---|---|
| Receipt | "Your package(s) %(package)s have arrived at our warehouse in %(warehouse.partner.city)s, %(country)s. Please wait for further updates when your package is ready for delivery or pickup." |
| Delivery | "Your package(s) %(package)s is heading to the next destination. It is being prepared for international transit." |
| Delivery Carrier | "Your package(s) %(package)s arrived at the delivery point and was handed over to the %(delivery_method)s courier. Courier tracking number: %(tracking number)s. Please use this number to track your delivery." |
| PIN Validation at Pickup Point | "Confirmation PIN code %(4_digits_pin)s" |
Package Status Requests (/status command)
When you request package status using the /status command, the bot responds with the following information:
| Scenario | Response |
|---|---|
| Received Package | "Tracking number: %(package)s Status: Received" |
| Processed Package | "Tracking number: %(package)s Status: Processed or Shipped Weight: %(weight)s Parent Package: %(parent package)s" |
Interactive Buttons:
| Button | Action |
|---|---|
| Contents | Displays: "%(item)s: %(quantity)s" |
| Parent Package | Displays: "Tracking number: %(package)s Status: Received Child Packages: %(package)s" |
| Child Package | Displays: "%(item)s: %(quantity)s" |
Note: Parent package information is displayed only if the package has a parent package and the partner is authorized to view it. For shipped packages, the status shows as "Shipped."
Profile Information (/profile command)
When you request profile information using the /profile command, the bot responds with:
| Response Element | Description |
|---|---|
| User Profile | Your account information. |
| Delivery Address | Your current delivery address: %(delivery_address)s |
| Boxberry Point URL | Your Boxberry pickup point: %(boxberry_point_url)s |
| /delivery_methods | Option to set or change delivery method (if not set). |
| US Address button | Displays your Base Forwarding Address when clicked. |
Note: Please check the Configuration readme for more information.
Actions Performed on Telegram Requests
Awaited Package Creation (/declare command)
To declare a new package awaited for shipment, use the /declare command.
| Step | Response |
|---|---|
| 1. Enter reference | "Enter the shipment reference number:" |
| 2. Invalid format | "Invalid shipment reference format. Please enter a valid shipment reference number. Reference numbers must contain A-Z a-z 0-9" |
| 3. Confirmation | "Press 'Yes' for confirmation" |
| 4. Success | "We are expecting a new package for you. Tracking number: %(reference name)s." |
Helpdesk Tickets Creation (/support command)
Use the /support command to create support tickets for various issues.
Change Recipient Ticket
When users click the "Yes" button to confirm recipient changes, a new Helpdesk Ticket is automatically created in the system.
| Step | Response |
|---|---|
| 1. Enter package number | "Enter your package number:" |
| 2. Package not found | "Sorry, no package %(package)s found, please check the reference number" |
| 3. Package belongs to another recipient | "Sorry, the package %(package)s belongs to another recipient" |
| 4. Package contains child packages | "Sorry, the package contains other packages, the recipient can't be changed" |
| 5. Package already packed | "Sorry, we can't change the recipient. Your package %(package)s is already packed and ready for shipment" |
| 6. Package already shipped | "Sorry, the package is shipped" |
| 7. Valid package | "Enter the Target Recipient Ref number:" |
| 8. Valid target recipient | "Please confirm you want %(partner.name)s as the recipient for the %(reference name)s" |
| 9. Confirmation buttons | "Yes button / No button" |
Note: Only the first name and the first letter of the last name are displayed in the notification for privacy.
Helpdesk Ticket Status Notifications
Notifications for Helpdesk Ticket status changes are sent to users automatically when the status changes.
| Event | Notification |
|---|---|
| Ticket Status Change | "Ticket %(helpdesk_ticket)s - %(package)s change recipient is %(helpdesk_ticket.status)s" |
Telegram Commands Reference
| Command | Description |
|---|---|
| /start <access_token> | Registers the user in the bot. |
| /status | Checks the status of a package using package name or reference name. Displays package information with interactive buttons: Contents, Shipment, Parent Package. |
| /declare | Declares a new package awaited for shipment. |
| /support | Creates a support request. Displays support request options with button: Change Recipient. |
| /profile | Retrieves user profile information. Includes a Delivery Address button (Base Forwarding Address for users with partner ref). |
| /delivery_methods | Sets the delivery method. Displays: Delivery to Address (fill out relevant fields) or Boxberry Delivery (select using the widget). |
| /cancel | Cancels any ongoing action. |
Support
If you have any questions about the Telegram bot features, our support team is available to assist.