SMM panel API: orders and automation

From connection to the first publication

1. Choose a service

   Get the service_id of an autopost service from the catalog. Call GET /autopost/capabilities?service_id=… for publication modes, available AI models and limits.

2. Create a client

   PUT /autopost/clients/customer_42 with a name or an empty object creates the client context. Repeating PUT updates it.

3. Confirm the account in the bot

   POST link-sessions returns a deep_link. Give it to your customer and poll GET link-sessions with the returned id until status=linked. If expired, create a new session. For MAX, set platform=max.

4. Check the channel and choose sources

   Grant the bot the required permissions, then call channels/check. Look for permissions=ready and can_order=true. Save the response UUID id as channel_id. GET sources with service_id returns available sources; you can also provide your own HTTPS source URLs.

5. Create an order

   Send service_id, channel_id, external_order_id, months and settings. Choose a schedule or timer. max_amount caps the charge; the example’s 1500.00 is an illustrative cap, not a service price.

6. Wait for the result

   202 means the command was accepted. Poll the Location URL at the Retry-After interval until succeeded or failed. Use subscription_id from a successful operation to read the subscription, settings and queue. Read error if the operation failed.

Request examples

Paths are relative to the API domain. Replace the key, UUIDs, URLs, identifiers and spending cap with your values. The UUIDs below are illustrative. Use one Idempotency-Key per command.

PUT /api/v1/autopost/clients/customer_42
X-API-Key: vw_your_key
Content-Type: application/json

{
  "name": "Customer 42"
}

POST /api/v1/autopost/clients/customer_42/link-sessions
X-API-Key: vw_your_key
Idempotency-Key: link-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "platform": "telegram"
}

GET /api/v1/autopost/clients/customer_42/link-sessions/{id}
X-API-Key: vw_your_key

POST /api/v1/autopost/clients/customer_42/channels/check
X-API-Key: vw_your_key
Idempotency-Key: check-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "platform": "telegram",
  "target": "https://t.me/your_channel"
}

GET /api/v1/autopost/clients/customer_42/sources?service_id=11111111-1111-4111-8111-111111111111&kind=catalog
X-API-Key: vw_your_key

POST /api/v1/autopost/clients/customer_42/orders
X-API-Key: vw_your_key
Idempotency-Key: order-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "channel_id": "22222222-2222-4222-8222-222222222222",
  "external_order_id": "order-2026-001",
  "months": 1,
  "max_amount": "1500.00",
  "settings": {
    "source_selection": {
      "type": "catalog",
      "source_ids": [
        "33333333-3333-4333-8333-333333333333"
      ]
    },
    "queue_mode": "new_and_old",
    "publication": {
      "mode": "schedule",
      "timezone": "Europe/Moscow",
      "days": {
        "1": [
          {
            "at": "09:00"
          },
          {
            "from": "17:00",
            "to": "19:00"
          }
        ]
      }
    }
  }
}

HTTP/1.1 202 Accepted
Location: /api/v1/autopost/clients/customer_42/operations/{id}
Retry-After: 2

GET /api/v1/autopost/clients/customer_42/operations/{id}
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/orders/{order_id}
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/subscriptions/{subscription_id}/queue
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/subscriptions/{id}
X-API-Key: vw_your_key

HTTP/1.1 200 OK
ETag: "1"

PATCH /api/v1/autopost/clients/customer_42/subscriptions/{id}/settings
X-API-Key: vw_your_key
If-Match: "1"
Content-Type: application/json

{
  "publication": {
    "mode": "ad_timer",
    "interval_min": 30,
    "interval_max": 60
  }
}

{
  "source_selection": {
    "type": "custom",
    "urls": [
      "https://t.me/your_source"
    ]
  },
  "queue_mode": "new",
  "publication": {
    "mode": "ad_timer",
    "interval_min": 30,
    "interval_max": 60
  },
  "signature_settings": {
    "mode": "append",
    "text": "Our channel",
    "url": "https://t.me/your_channel"
  },
  "source_signature_settings": {
    "https://t.me/your_source": {
      "mode": "replace",
      "url": "https://t.me/your_channel"
    }
  }
}

Integration rules

Retrying requests

Every POST requires Idempotency-Key: 1–128 ASCII letters, digits or . _ : -. After a timeout, retry the same URL with the same key and body. A different body with the same key returns 409 idempotency_conflict. Use a new key for a new command. PUT and DELETE do not require this header.

Your order reference and spending cap

external_order_id is required for each order and renewal: 1–128 ASCII letters, digits or . _ : -. It is unique within client_ref. Repeating the same parameters returns the original operation; different parameters cause external_order_conflict. max_amount is a string with two decimal places; a higher price causes price_changed.

Updating settings

PATCH requires If-Match from GET subscription. A missing header returns 428; an outdated version returns 412. Read the settings again and reconcile your changes. Send each changed section in full; omitted sections are preserved. null is not accepted. Also check the subscription’s actions.

Sources and AI

Choose one source_selection type: catalog with source_ids, or custom with urls. Custom sources support HTTPS URLs on t.me, telegram.me and max.ru. Prompts, models and individual AI settings are managed by an administrator. Do not send ai_settings or source_settings when creating an order or updating settings, even as empty objects: the request will be rejected. The plan's AI processing uses the saved settings.

Linked signatures

signature_settings.mode: off disables the feature, remove deletes a detected signature, replace replaces it only when found, and append always adds yours. text is the clickable label (defaults to the channel name), url is the destination or invitation (required for private channels). Detection covers a separate short final line linking to a Telegram/MAX channel. source_signature_settings fully overrides settings for a source; mode: off disables the shared rule. Changes affect unsent posts and do not bypass other ad filters.

Schedule and timer

schedule requires timezone and days. Weekdays: 1 is Monday, 7 is Sunday. Each slot has at or a from/to range in HH:MM format; dates keys use YYYY-MM-DD. ad_timer intervals are in minutes, defaulting to 30–60. queue_mode defaults to new_and_old; new selects only new publications.

Subscriptions and the queue

The subscription list defaults to active and paused; status=all includes other states. publish-next sends the next queued post. delivery_unknown means one post's delivery is unconfirmed: it is not retried and does not block subsequent publications. Use summary and empty_reason to diagnose an empty queue. Check can_cancel before cancelling, and refunded_amount on the order for refunds.

Lists and status polling

Lists return data and next_cursor. Pass the cursor unchanged with the same filters until it is null. limit is 1–100, default 50. Webhooks are not available in this release: poll statuses with GET.

Autopost errors

Errors contain an error object with code, message, request_id, retryable and fields. 401: key; 403: insufficient scopes; 402: balance; 404: resource unavailable in this context; 409: conflict; 422: invalid fields. For 429, follow Retry-After; for 503, retry after a delay with the same key. Save X-Request-ID for support.

Request limits

Limits apply both per key and across its owner’s account. Creating link sessions and checking channels have separate limits. Extra keys do not increase the owner’s total limit; the API returns 429 when a limit is reached.