The KIVVI Telegram bot lets you manage shipments, track packages, and perform other actions directly in Telegram. This guide covers all available features and commands.
Connect the Telegram Bot
Sign in to your KIVVI account. If you haven’t connected the Telegram bot yet, find the Telegram card and select Register in Telegram. The card will remain visible until registration is complete.
You will then be redirected to the Telegram bot. To get started, enter or select the /start command.
The welcome message will list the bot’s available features.
Telegram Notifications
The bot automatically sends notifications about package updates and status changes.
Package Updates
| 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" |
| 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." |
Warehouse Operation Confirmations
Notifications are sent after the relevant warehouse operation has been confirmed.
| Warehouse Operation | 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." |
| PIN Validation at Pickup Point | "Confirmation PIN code %(4_digits_pin)s" |
Check Package Status with /status
After you request an update using the /status command, the bot will show the current package information.
| Package status | Bot 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 shown only if the package has a parent package and the user is authorized to view those details. Packages that have already left the warehouse are shown with the status Shipped.
Profile Information with /profile
After you enter the /profile command, the bot will show the following information:
| Section | Description |
|---|---|
| User Profile | Your account details |
| 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 Available Through Telegram Commands
Add an Awaited Package with /declare
Use the /declare command to add the tracking number of a package expected at the KIVVI warehouse.
| Step | Bot Response |
|---|---|
| 1. Enter the tracking number | "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. Package added successful | "We are expecting a new package for you. Tracking number: %(reference name)s." |
Contact Support with /support
Use the /support command to create a support request.
Change the Recipient
After you confirm the recipient change by selecting Yes, a support request will be created automatically.
| Step or situation | Bot 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 registered 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. Recipient found | "Please confirm you want %(partner.name)s as the recipient for the %(reference name)s" |
| 9. Confirmation buttons | "Yes" / "No" |
Note: For privacy, the notification will display only the recipient’s first name and the first initial of their last name.
Support Request Status Notifications
The bot will automatically notify you when the status of your support request changes.
| Event | Notification |
|---|---|
| Support Request Updates | "Ticket %(helpdesk_ticket)s - %(package)s change recipient is %(helpdesk_ticket.status)s" |
Telegram Bot Commands
| Command | Description |
|---|---|
| /start <access_token> | Connect your KIVVI account to the Telegram bot. |
| /status | Checks the status of a package using its package number or tracking number. Shows package details and the Contents, Combined Package, and Included Package buttons when applicable. |
| /declare | Adds an expected package. |
| /support | Creates a support request. Available options include Change Recipient. |
| /profile | Shows your profile information and includes a US Warehouse Address button. |
| /delivery_methods | Lets you choose between delivery to an address and pickup at a Boxberry location. |
| /cancel | Cancels the current action. |
Support
If you have any questions about the Telegram bot, our support team is always ready to help