Skip to content

Send a Telegram message

This guide queues an outbound Telegram message from one of your connected accounts and then follows the job until it is delivered.

All requests go to https://api.pinlyx.com with your API key as a bearer token. New here? Start with the API quickstart and Authentication.

Sending is asynchronous. The API writes the message to the sending queue and returns at once with a job in the queued state. A background worker picks queued jobs up and sends them through Telegram, respecting the account’s rate limits and Telegram’s flood-wait backoff. You then read the job to see it move to sent or failed. The same jobs appear in the panel’s sending queue.

Send a POST to /v1/telegram/messages.

  1. Pick the account and the recipient. accountId and text are always required. Name the recipient with at least one of contactId, username or telegramUserId.

    FieldTypeRequiredNotes
    accountIdintegerYesA Telegram account connected by you. GET /v1/accounts lists them.
    textstringYesMessage body, up to 4000 characters.
    contactIdintegerOne of threeA contact in your workspace. Its stored Telegram user id or username is used.
    usernamestringOne of threeRecipient’s username. A leading @ is removed.
    telegramUserIdintegerOne of threeRecipient’s numeric Telegram user id.
    runAtstringNoWhen to send (UTC, ISO 8601). Leave it out to send as soon as possible.
  2. Send the request.

    Terminal window
    curl -X POST https://api.pinlyx.com/v1/telegram/messages \
    -H "Authorization: Bearer csk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
    "accountId": 7,
    "username": "john_doe",
    "text": "Hi from Acme!"
    }'
  3. Read the response. A successful call returns 202 Accepted with the queued job. Keep its Id to check the status later. This response uses PascalCase field names.

    {
    "Id": 1024,
    "AccountId": 7,
    "Status": "queued",
    "RunAt": "2026-05-01T08:00:00Z",
    "CreatedAt": "2026-04-30T18:00:00Z"
    }

A 400 means text is empty or longer than 4000 characters, accountId is missing, no recipient was given, or the contactId has neither a Telegram user id nor a username. A 404 means the Telegram account is not yours or the contact is not in your workspace.

Set runAt to a UTC timestamp in ISO 8601 format:

{
"accountId": 7,
"username": "john_doe",
"text": "Reminder: your trial ends tomorrow.",
"runAt": "2026-05-01T08:00:00Z"
}

Call GET /v1/telegram/messages/{id} with the job id. status is queued, then sent or failed; on a failure lastError says why. This response uses camelCase field names.

Terminal window
curl https://api.pinlyx.com/v1/telegram/messages/1024 \
-H "Authorization: Bearer csk_live_..."
{
"id": 1024,
"accountId": 7,
"status": "sent",
"runAt": "2026-05-01T08:00:00Z",
"createdAt": "2026-04-30T18:00:00Z",
"updatedAt": "2026-05-01T08:00:05Z",
"lastError": null
}

Keep polling while status is queued. The worker runs on a short cycle, so a few seconds between calls is enough; every call counts against your key’s rate limit.

async function waitForDelivery(jobId) {
while (true) {
const res = await fetch(`https://api.pinlyx.com/v1/telegram/messages/${jobId}`, {
headers: { Authorization: "Bearer csk_live_..." },
});
const job = await res.json();
if (job.status !== "queued") return job; // "sent" or "failed"
await new Promise((r) => setTimeout(r, 5000));
}
}

If you would rather not poll, subscribe a webhook to message.sent.