Skip to content
CRM Solid Docs
Open app

Enqueue a Telegram outbound message

POST
/v1/telegram/messages

Enqueues a message for delivery by the background job worker and returns immediately with the queued job. The recipient is resolved from contactId, username, or telegramUserId - at least one must be supplied. If contactId is provided and the contact has no resolved Telegram identity, the request fails with 400. Set runAt (UTC) to schedule delivery for later; omit for immediate dispatch. The accountId must belong to the authenticated user. Requires scope telegram:send.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Provide exactly one of contactId, username, or telegramUserId to identify the recipient (or let contactId resolve to one automatically).

object
accountId
required

Id of the Telegram account (owned by the caller) to send from.

integer
contactId

CRM contact to message. The contact’s stored username/telegramUserId is used as the target.

integer
nullable
username

Telegram @username of the recipient (leading @ is stripped server-side).

string
nullable
telegramUserId

Telegram numeric user id of the recipient.

integer format: int64
nullable
text
required

Message body. Maximum 4000 characters.

string
<= 4000 characters
runAt

Scheduled delivery time (UTC). Omit or set to null for immediate dispatch.

string format: date-time
nullable
Example
{
  "accountId": 7,
  "username": "john_doe",
  "text": "Hi from Acme Inc.!",
  "runAt": null
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Message job accepted and queued.

Queued message job returned by POST /v1/telegram/messages (202 Accepted).

object
id
integer
accountId
integer
status

Current job status.

string
Allowed values: queued sent failed
runAt

Scheduled or effective send time (UTC).

string format: date-time
createdAt
string format: date-time

400

Section titled “400 ”

The request body or parameters failed validation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "bad_request",
  "message": "at least one of name, username, phone is required"
}

401

Section titled “401 ”

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

403

Section titled “403 ”

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}

404

Section titled “404 ”

The requested resource does not exist or is not owned by the caller.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "not_found",
  "message": "contact not found"
}

429

Section titled “429 ”

Per-key rate limit exceeded. Retry after the time indicated by X-RateLimit-Reset.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "rate_limited",
  "message": "rate limit exceeded"
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
integer

Maximum requests allowed per minute for this key.

X-RateLimit-Remaining
integer

Requests remaining in the current window.

X-RateLimit-Reset
integer

Unix timestamp (seconds) when the rate limit window resets.