Send a Telegram message

This guide shows how to enqueue an outbound Telegram message and then poll for its delivery status via the Public API.

All requests go to the base URL https://api.crmsolid.com and must include your API key as a bearer token. New here? Start with the Quickstart and Authentication guides.

Note

Enqueuing a message requires the telegram:send scope. Reading job status requires telegram:read.

How sending works

Sends are asynchronous. When you call the API, the message is written to a queue and the endpoint returns immediately with a job in the queued state. A background job worker on the server picks up queued jobs and dispatches them through Telegram, respecting rate limits and flood-wait backoff. You then poll the job to see when it transitions to sent (or failed).

Enqueue a message

Send a POST to /v1/telegram/messages.

1. Pick the account and recipient. accountId and text are always required. Provide exactly one recipient identifier — contactId, username, or telegramUserId.

   Field	Type	Required	Notes
   accountId	integer	Yes	Id of the Telegram account (owned by you) to send from.
   text	string	Yes	Message body. Maximum 4000 characters.
   contactId	integer	One of three	CRM contact to message; the contact’s stored username / Telegram user id is used as the target.
   username	string	One of three	Recipient @username (leading @ is stripped server-side).
   telegramUserId	integer	One of three	Recipient’s numeric Telegram user id.
   runAt	string	No	Scheduled delivery time (UTC, ISO-8601). Omit or set to null for immediate dispatch.

2. Send the request.

   cURL

   curl -X POST https://api.crmsolid.com/v1/telegram/messages \
     -H "Authorization: Bearer csk_live_..." \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": 7,
       "username": "john_doe",
       "text": "Hi from Acme Inc.!",
       "runAt": null
     }'

   JavaScript

   const res = await fetch(
     "https://api.crmsolid.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 Inc.!",
         runAt: null,
       }),
     },
   );
   
   const job = await res.json();
   console.log(job.id, job.status); // -> 1024 "queued"

   Python

   import requests
   
   res = requests.post(
       "https://api.crmsolid.com/v1/telegram/messages",
       headers={"Authorization": "Bearer csk_live_..."},
       json={
           "accountId": 7,
           "username": "john_doe",
           "text": "Hi from Acme Inc.!",
           "runAt": None,
       },
   )
   
   job = res.json()
   print(job["id"], job["status"])  # -> 1024 "queued"

3. Read the response. A successful enqueue returns 202 Accepted with the queued job. Save the id — you’ll use it to check status.

   {
     "id": 1024,
     "accountId": 7,
     "status": "queued",
     "runAt": "2024-05-01T08:00:00Z",
     "createdAt": "2024-04-30T18:00:00Z"
   }

Caution

Expect a 400 if text is empty or longer than 4000 characters, if accountId is missing, if none of contactId / username / telegramUserId is provided, or if a contactId has no resolvable Telegram identity. A 404 means the accountId (or contactId) isn’t owned by your workspace.

Schedule for later

To schedule a send instead of dispatching immediately, set runAt to a UTC ISO-8601 timestamp:

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

Check delivery status

Poll GET /v1/telegram/messages/{id} with the job id from the enqueue response. The status field moves through queued → sent, or to failed (in which case lastError explains why).

cURL

curl https://api.crmsolid.com/v1/telegram/messages/1024 \
  -H "Authorization: Bearer csk_live_..."

JavaScript

const res = await fetch(
  "https://api.crmsolid.com/v1/telegram/messages/1024",
  { headers: { Authorization: "Bearer csk_live_..." } },
);

const job = await res.json();
console.log(job.status, job.lastError);

Python

import requests

res = requests.get(
    "https://api.crmsolid.com/v1/telegram/messages/1024",
    headers={"Authorization": "Bearer csk_live_..."},
)

job = res.json()
print(job["status"], job["lastError"])

The detail response includes updatedAt and lastError:

{
  "id": 1024,
  "accountId": 7,
  "status": "sent",
  "runAt": "2024-05-01T08:00:00Z",
  "createdAt": "2024-04-30T18:00:00Z",
  "updatedAt": "2024-05-01T08:00:05Z",
  "lastError": null
}

Poll until terminal

Keep polling until status is no longer queued. Use a sensible interval and backoff — the worker processes the queue on a short cycle, not instantly.

JavaScript

async function waitForDelivery(jobId) {
  while (true) {
    const res = await fetch(
      `https://api.crmsolid.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));
  }
}

Python

import time
import requests

def wait_for_delivery(job_id):
    while True:
        res = requests.get(
            f"https://api.crmsolid.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)

Tip

If status is failed, read lastError for the reason (for example a Telegram flood-wait or an unreachable recipient).

Next steps

• Need a recipient first? See Sync contacts to create one and pass its id as contactId.
• Browse every field, scope, and error code in the full API reference.