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.
How sending works
Section titled “How sending works”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.
Queue a message
Section titled “Queue a message”Send a POST to /v1/telegram/messages.
-
Pick the account and the recipient.
accountIdandtextare always required. Name the recipient with at least one ofcontactId,usernameortelegramUserId.Field Type Required Notes accountIdinteger Yes A Telegram account connected by you. GET /v1/accountslists them.textstring Yes Message body, up to 4000 characters. contactIdinteger One of three A contact in your workspace. Its stored Telegram user id or username is used. usernamestring One of three Recipient’s username. A leading @is removed.telegramUserIdinteger One of three Recipient’s numeric Telegram user id. runAtstring No When to send (UTC, ISO 8601). Leave it out to send as soon as possible. -
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!"}'const res = await fetch("https://api.pinlyx.com/v1/telegram/messages", {method: "POST",headers: {Authorization: "Bearer csk_live_...","Content-Type": "application/json",},body: JSON.stringify({ accountId: 7, username: "john_doe", text: "Hi from Acme!" }),});const job = await res.json();console.log(job.Id, job.Status); // 1024 "queued"import requestsres = requests.post("https://api.pinlyx.com/v1/telegram/messages",headers={"Authorization": "Bearer csk_live_..."},json={"accountId": 7, "username": "john_doe", "text": "Hi from Acme!"},)job = res.json()print(job["Id"], job["Status"]) # 1024 queued -
Read the response. A successful call returns 202 Accepted with the queued job. Keep its
Idto 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.
Schedule for later
Section titled “Schedule for later”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"}Check delivery status
Section titled “Check delivery status”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.
curl https://api.pinlyx.com/v1/telegram/messages/1024 \ -H "Authorization: Bearer csk_live_..."const res = await fetch("https://api.pinlyx.com/v1/telegram/messages/1024", { headers: { Authorization: "Bearer csk_live_..." },});
const job = await res.json();console.log(job.status, job.lastError);import requests
res = requests.get( "https://api.pinlyx.com/v1/telegram/messages/1024", headers={"Authorization": "Bearer csk_live_..."},)
job = res.json()print(job["status"], job["lastError"]){ "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}Poll until it settles
Section titled “Poll until it settles”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)); }}import timeimport requests
def wait_for_delivery(job_id): while True: res = requests.get( f"https://api.pinlyx.com/v1/telegram/messages/{job_id}", headers={"Authorization": "Bearer csk_live_..."}, ) job = res.json()
if job["status"] != "queued": return job # "sent" or "failed" time.sleep(5)If you would rather not poll, subscribe a webhook to message.sent.