Messenger API

Everything the panel can do with a connected Telegram, WhatsApp or Instagram account, over REST — one key, one response shape, chapter by chapter.

Errors & rate limits

The error shape, every error code with its HTTP status, and how limits work.

Error shape

Failures always use this shape. Branch on code, never on the message text. details (optional) carries validation errors per field.

{
  "success": false,
  "error": { "code": "DEVICE_OFFLINE", "message": "No available device is currently online.", "details": {} }
}

Error codes

401INVALID_API_KEYThe API key is missing or invalid.

401API_KEY_EXPIREDThis API key has expired.

401API_KEY_REVOKEDThis API key has been revoked.

403INSUFFICIENT_SCOPEThis API key does not have the required scope.

403ORGANIZATION_SUSPENDEDThis account is suspended.

422VALIDATION_FAILEDThe request contains invalid parameters.

422INVALID_PHONE_NUMBERThe recipient phone number could not be parsed.

422MESSAGE_TOO_LONGThe message body exceeds the maximum length.

404MESSAGE_NOT_FOUNDNo message matches that identifier.

404BATCH_NOT_FOUNDNo batch matches that identifier.

404DEVICE_NOT_FOUNDNo device matches that identifier.

404WEBHOOK_NOT_FOUNDNo webhook endpoint matches that identifier.

409DEVICE_OFFLINENo available device is currently online.

409DEVICE_DISABLEDThe selected device is disabled.

409SIM_UNAVAILABLEThe selected SIM card is not available.

409SMS_PERMISSION_MISSINGThe device has not granted SMS permission.

422MESSAGE_NOT_CANCELLABLEThis message can no longer be cancelled.

429RATE_LIMIT_EXCEEDEDRate limit exceeded. Retry after the indicated delay.

402ENTITLEMENT_EXCEEDEDThis action exceeds your plan limits.

422IDEMPOTENCY_KEY_REUSEDThis idempotency key was already used with a different request body.

409IDEMPOTENT_REQUEST_IN_PROGRESSA request with this idempotency key is still in progress.

422INVALID_PAIRING_CODEThe pairing code is invalid.

422PAIRING_CODE_EXPIREDThe pairing code has expired.

500INTERNAL_ERRORAn unexpected error occurred.

402PLAN_REQUIREDMessenger API access is not included in the current plan.

404CHANNEL_NOT_FOUNDNo channel matches that identifier.

409CHANNEL_NOT_CONNECTEDThe channel is not connected.

502CONNECTOR_ERRORThe channel connector did not respond.

429FLOOD_WAITThe messenger asked us to slow down. Retry after the indicated delay.

422CHANNEL_REQUEST_FAILEDThe messenger rejected the request.

Rate limits

Limits are layered: per API key, per workspace, per device and per SIM (the per-SIM limit protects the physical card from a runaway loop). Telegram adds its own flood limits: a 429 FLOOD_WAIT tells you how many seconds to wait. Every 429 carries Retry-After and X-RateLimit-* headers.