Telegram bots

Quick start

Connect your Telegram bot and send your first notification in under 5 minutes.

Create a bot with BotFather

Open @BotFather in Telegram, run /newbot, and copy the bot token.

Connect it to Shoppex

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_token": "123456:AAExampleToken"}'

Share your deep link

The response includes a deep_link_url. Share it with customers so they can opt in to notifications through Telegram.

Send a broadcast

Once customers connect, you can send broadcasts, set up journeys, or enable the AI agent.

Your bot is now live. The sections below cover notifications, broadcasts, journeys, the inbox, and the AI agent.

Bot response shape

When you connect a bot, Shoppex returns a grouped resource:

{
  "data": {
    "id": "9d40c284-4f39-4d2e-a9d5-56ea2e7d5bc7",
    "shop_id": "3c649ff2-0a87-42de-897a-c07fc2f9a79d",
    "identity": {
      "telegram_bot_id": "123456789",
      "username": "shoppex_demo_bot",
      "display_name": "Shoppex Demo Bot"
    },
    "verification": {
      "status": "VERIFIED",
      "last_verified_at": "2026-04-06T11:20:00.000Z",
      "last_error": null
    },
    "connection": {
      "webhook_url": "https://api.shoppex.io/telegram-webhook-url",
      "deep_link_url": "https://t.me/shoppex_demo_bot?start=shop:3c649ff2-0a87-42de-897a-c07fc2f9a79d",
      "merchant_deep_link_url": "https://t.me/shoppex_demo_bot?start=shop%3A3c649ff2-0a87-42de-897a-c07fc2f9a79d%2Cmanager%3Ausr_123%2Csig%3Aabc123"
    },
    "agent": {
      "enabled": false,
      "mode": "CUSTOMER_SALES",
      "has_api_key": false,
      "api_key_generated_at": null,
      "last_routed_at": null
    }
  }
}

Customer linking

Customers connect to your shop through the bot deep link https://t.me/<bot_username>?start=shop:<shop_id>. Add context to the link for richer linking:

Link format	Use case
`?start=shop:<shop_id>`	Basic opt-in
`?start=shop:<shop_id>,customer:<customer_id>`	Link to an existing customer for order confirmations
`?start=shop:<shop_id>,email:<urlencoded_email>`	Link guest checkouts by email
`?start=shop:<shop_id>,manager:<user_id>,sig:<signature>`	Merchant assistant mode (signed)

The bot response includes the merchant deep link pre-built under connection.merchant_deep_link_url. It binds the Telegram chat to a Shoppex manager, so merchant-only agent flows route safely. List linked users:

curl "https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/users?is_active=true&limit=25" \
  -H "Authorization: Bearer YOUR_DEV_API_KEY"

Notifications

Shoppex sends Telegram messages automatically for order confirmations, restock alerts, and promotional broadcasts. Each user’s notification_preferences object controls what they receive, and the defaults apply until you change them. Update a single user:

curl -X PUT https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/users/USER_ID/notifications \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_preferences": {
      "enabled_types": ["ORDER_CONFIRMATION", "PRODUCT_RESTOCK"]
    }
  }'

Update multiple users at once:

curl -X PUT https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/users/bulk/notifications \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "11111111-1111-4111-8111-111111111111",
      "22222222-2222-4222-8222-222222222222"
    ],
    "notification_preferences": {
      "enabled_types": ["PROMOTIONAL_OFFERS"]
    }
  }'

Broadcasts

A broadcast sends a message to a filtered audience, right away or on a schedule. A broadcast request has three parts:

Group	What it controls
`content`	The message body, parse mode, and inline keyboard buttons
`audience`	Filter by notification type, activity (`only_active_users`, `last_activity_after`), or saved segments (`segment_ids`)
`delivery`	When to send (`scheduled_for`) and the rate, up to 30 messages per second (`messages_per_second`)

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/broadcasts \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "body": "<b>Restock alert</b>\nYour item is back in stock.",
      "parse_mode": "HTML",
      "inline_keyboard": [
        [{"text": "Open product", "url": "https://demo.myshoppex.io/product/prod_123"}]
      ]
    },
    "audience": {
      "notification_types": ["PRODUCT_RESTOCK"],
      "only_active_users": true
    },
    "delivery": {
      "messages_per_second": 15
    }
  }'

URL buttons are automatically wrapped in Shoppex tracking links, so you get click-through rates and revenue attribution for free.

Broadcasts move through these states: DRAFT → SCHEDULED → SENDING → COMPLETED / CANCELLED / FAILED. For product-specific restocks, use the dedicated endpoint. Shoppex builds the message from the product data:

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/broadcasts/warehouse-restock \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "33333333-3333-4333-8333-333333333333",
    "variant_id": "44444444-4444-4444-8444-444444444444",
    "content": {"body": "Back in stock now", "parse_mode": "HTML"},
    "audience": {"only_active_users": true},
    "delivery": {"messages_per_second": 10}
  }'

Saved segments

Save a repeated audience filter as a segment:

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/segments \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active buyers",
    "description": "Customers active in the last 30 days",
    "filters": {
      "only_active_users": true,
      "linked_only": true,
      "notification_types": ["ORDER_CONFIRMATION"]
    }
  }'

Reference the saved segment in any broadcast with audience.segment_ids: ["<segment_id>"]. Manage segments with GET, PUT, and DELETE on /dev/v1/telegram/bots/:botId/segments/:segmentId.

Analytics and click tracking

Shoppex tracks URL button clicks per broadcast and attributes completed orders back to the broadcast that drove them:

You send a broadcast with a product button.
Shoppex rewrites the URL to a tracking link.
The customer clicks, and Shoppex records the click before it redirects to the product page.
If the customer completes an order inside the attribution window, the revenue counts back to that broadcast.

curl https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/broadcasts/BROADCAST_ID/analytics \
  -H "Authorization: Bearer YOUR_DEV_API_KEY"

The response overview object reports:

Field	Meaning
`delivered_count`, `failed_count`	Messages delivered and messages that failed
`unique_clicked_users`, `click_count`	Distinct clickers and total clicks
`click_through_rate`	Click-through rate as a percentage
`attributed_orders`, `attributed_revenue`	Orders and revenue linked back to this broadcast

Each entry in the buttons array reports button_id, text, destination_url, unique_clicked_users, and click_count. Track delivery and bot-level performance with:

GET /dev/v1/telegram/bots/:botId/broadcasts — list all broadcasts
GET /dev/v1/telegram/bots/:botId/broadcasts/:id — a single broadcast
GET /dev/v1/telegram/bots/:botId/broadcasts/:id/stats — delivery progress
GET /dev/v1/telegram/bots/:botId/analytics — bot-level analytics

The broadcast response groups delivery progress under delivery: sent_count, failed_count, progress_percentage, estimated_time_remaining_seconds, and failure_reasons.

Journeys

Journeys are event-driven follow-up flows, such as a post-purchase drip or an abandoned-cart reminder. Shoppex sends each message on its own schedule, so you do not send them by hand.

Trigger	When it fires
`ORDER_COMPLETED`	After a successful order
`ABANDONED_CART`	When a customer starts checkout but does not complete it
`PAYMENT_REMINDER`	Before a payment deadline
`SUBSCRIPTION_RENEWAL`	Before a subscription renews
`MANUAL`	Triggered by your API call

Example post-purchase follow-up:

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/journeys \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Post-purchase follow-up",
    "trigger": "ORDER_COMPLETED",
    "filters": {"only_active_users": true},
    "steps": [
      {
        "delay_minutes": 0,
        "content": {"body": "Thanks for your order.", "parse_mode": "HTML"}
      },
      {
        "delay_minutes": 1440,
        "content": {"body": "Need help with your order?", "parse_mode": "NONE"}
      }
    ]
  }'

This journey fires when a customer completes an order. It sends the first message immediately and queues the follow-up for 24 hours later. Test a journey before you turn it on with POST /dev/v1/telegram/bots/:botId/journeys/:journeyId/test.

Support commands and inbox

The bot doubles as a two-way support channel. Customer commands:

Command	What it does
`/settings`	Opens the notification preference center
`/track`	Tracks an order
`/buyagain`	Reorders the last purchase
`/help`	Opens the support flow

Merchant inbox endpoints:

GET /dev/v1/telegram/bots/:botId/inbox — list conversations
GET /dev/v1/telegram/bots/:botId/inbox/:conversationId — read a conversation
POST /dev/v1/telegram/bots/:botId/inbox/:conversationId/reply — send a reply
PUT /dev/v1/telegram/bots/:botId/inbox/:conversationId/status — close or reopen

curl -X POST https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/inbox/CONVERSATION_ID/reply \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "We are checking your order now.", "parse_mode": "HTML"}'

AI agent

The AI agent routes inbound Telegram messages through Shoppex commerce tools: product search, order lookup, coupon creation, and payment links.

Mode	Who it serves	What it can do
`CUSTOMER_SALES`	Customers	Search products, look up orders, share payment links
`MERCHANT_ASSISTANT`	Merchants, through a signed deep link	Create coupons, check revenue, manage products
`BOTH`	Both, on the same bot	Routes based on whether the chat is linked to a customer or a merchant

Enable the agent:

curl -X PUT https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/agent \
  -H "Authorization: Bearer YOUR_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_enabled": true, "agent_mode": "BOTH"}'

When you enable the agent, Shoppex creates a shop-scoped Dev API key for the bot. It stores inbound messages as inbox history, routes each message to the AI model, and sends the response back to Telegram. Check usage:

curl https://api.shoppex.io/dev/v1/telegram/bots/BOT_ID/agent/stats \
  -H "Authorization: Bearer YOUR_DEV_API_KEY"

The response reports calls, completed_calls, failed_calls, rate_limited_calls, conversations, total_tokens, estimated_cost_usd, average_response_time_ms, and last_run_at. A customer asking “Do you have the hoodie in black?” gets a product search and a direct answer. A merchant saying “Create a 15% coupon for the hoodie” gets a coupon created through the Dev API. The estimated_cost_usd field tracks AI token costs, so there are no surprises on your bill.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Quick start

Bot response shape

Customer linking

Notifications

Broadcasts

Saved segments

Analytics and click tracking

Journeys

Support commands and inbox

AI agent

​Quick start

​Bot response shape

​Customer linking

​Notifications

​Broadcasts

​Saved segments

​Analytics and click tracking

​Journeys

​Support commands and inbox

​AI agent

Quick start

Bot response shape

Customer linking

Notifications

Broadcasts

Saved segments

Analytics and click tracking

Journeys

Support commands and inbox

AI agent