Comece aqui

Sua primeira solicitação em quatro etapas

Keep your main SMSMobileAPI subscription active; Telegram connection, API access, sending and sent-message history pause when it expires.

Conecte sua própria conta Telegram por QR code no painel e sincronize seus contatos.

Copie sua chave SMSMobileAPI em My API Key e mantenha-a no seu servidor.

Liste contatos e copie o contact_id do destinatário pretendido.

Send JSON for text, or multipart/form-data to attach an image or document. Use the returned message_id to check the sent log.

SUA CONTA TELEGRAM

Conecte, escolha um contato e em seguida acompanhe o envio.

Conta abrangida

Cada cliente escaneia um QR code para conectar sua própria conta Telegram. Sincronize os contatos no painel, use o ID de contato retornado para enfileirar uma mensagem e depois verifique seu status no log de enviados.

1

Conectar

Digitalize o QR code na página do painel Telegram.

2

Encontrar um contato

Sincronize, depois procure o ID do contato via API.

3

Enviar

POST uma mensagem JSON com uma chave de idempotência.

4

Acompanhar

Leia estados enfileirado, enviado, desconhecido ou erro.

Autenticação

Mantenha as credenciais no seu servidor

Send X-SMSMobileAPI-Key: YOUR_API_KEY in an HTTPS header. Keep this key on your server, never in browser JavaScript or a public repository. The endpoints are scoped to the Telegram account connected to that SMSMobileAPI account. A short-lived signed download_url can be opened without the key. Access can be disabled in My API Key.

Antes de integrar

An expired SMSMobileAPI subscription blocks Telegram API access with HTTP 402 subscription_expired, including attachment downloads. Renew in the dashboard to restore access; existing connection and history are preserved.
O QR code vincula a conta Telegram de cada cliente. As mensagens são enviadas dessa conta, não de uma conta SMSMobileAPI compartilhada.
Uma resposta 202 significa que a solicitação foi enfileirada. Isso não comprova que Telegram aceitou ou entregou a mensagem. Consulte o log de enviados para status enviado ou erro.
O serviço atualmente envia para um contato sincronizado ou @username salvo por requisição. Respeite as regras Telegram e o consentimento do destinatário.
As solicitações são limitadas a 15 mensagens novas por minuto e 30 mensagens enfileiradas por conta conectada. Use uma idempotency_key estável ao tentar novamente.
Images and documents can be up to 5 MB. The send queue holds file bytes only until processing finishes; a separate private copy supports later downloads. File bytes are never embedded in the sent log.
Newly sent attachments are kept in private storage for 90 days. The sent log returns a download_url valid for 15 minutes; request the log again to get a new link. Older attachments sent before this feature have no downloadable copy.

PEGAR

Listar contatos Telegram

FIMhttps://api.smsmobileapi.com/telegram/contacts/

Retorna contatos disponíveis na sua conta Telegram conectada.

Quando usá-lo

Pesquise por nome exibido ou @username, depois use contact_id para enviar.

Parâmetros

Nome	Tipo	Requisito	Descrição
`q`	corda	Opcional	Busca opcional por nome ou nome de usuário, até 80 caracteres.
`limit`	inteiro	Opcional	Tamanho da página de 1 a 100; padrão 50.
`cursor`	inteiro	Opcional	Use paging.next_cursor da resposta anterior; omita na primeira página.

Exemplo de solicitação

enrolar

curl -G 'https://api.smsmobileapi.com/telegram/contacts/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  --data-urlencode 'q=Alex' \
  --data-urlencode 'limit=50'

Exemplo de resposta

JSON

{"ok":true,"data":[{"contact_id":42,"display_name":"Alex Example","username":"alex_example","source":"telegram"}],"paging":{"has_more":false,"next_cursor":null}}

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

Os IDs de contato pertencem à conta conectada; um ID de outra conta não pode ser usado.
Atualize contatos em Dashboard → Telegram Contacts quando alguém novo não aparecer.

PUBLICAR

Envie uma mensagem Telegram

FIMhttps://api.smsmobileapi.com/telegram/send/

Enfileira uma mensagem de texto para um contato da sua conta Telegram conectada.

Quando usá-lo

Use contact_id do endpoint de contatos. Salve message_id para rastreamento.

Parâmetros

Nome	Tipo	Requisito	Descrição
`contact_id`	inteiro	Obrigatório	ID de contato retornado por /telegram/contacts/.
`message`	corda	Obrigatório	Texto UTF-8, 1–4096 caracteres e no máximo 16.000 bytes.
`idempotency_key`	String UUID	Opcional	Chave estável de 36 caracteres no formato UUID em minúsculas. Reutilize em novas tentativas de rede para evitar mensagens duplicadas.

Exemplo de solicitação

enrolar

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"contact_id":42,"message":"Your appointment is confirmed.","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161"}'

Exemplo de resposta

JSON

{"ok":true,"message_id":123,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

HTTP 202 significa em fila; não é um recibo de entrega. Uma nova tentativa idêntica retorna HTTP 200 com duplicate=true e o message_id original.
Para reenvios, reutilize a mesma idempotency_key com o mesmo contato e mensagem. Um payload alterado com a mesma chave retorna HTTP 409.

PUBLICAR

Send a Telegram image or document

FIMhttps://api.smsmobileapi.com/telegram/send/

Queue one file for a contact, with an optional caption.

Quando usá-lo

Use multipart/form-data. The field name for the attachment is file.

Parâmetros

Nome	Tipo	Requisito	Descrição
`contact_id`	inteiro	Obrigatório	ID de contato retornado por /telegram/contacts/.
`file`	file	Obrigatório	One JPG, PNG, WebP, PDF, TXT, CSV, JSON, ZIP or Office file, at most 5 MB.
`message`	corda	Opcional	Optional caption of at most 1024 characters.
`idempotency_key`	String UUID	Opcional	Reuse the same key and identical file and caption when retrying.

Exemplo de solicitação

enrolar

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -F 'contact_id=42' \
  -F 'message=Here is the document.' \
  -F 'file=@./document.pdf' \
  -F 'idempotency_key=2d40bb10-cc42-4c30-a282-93fc6dd8e161'

Exemplo de resposta

JSON

{"ok":true,"message_id":124,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

Do not set Content-Type manually; cURL adds the multipart boundary.
For JSON clients, send file_base64 with the Base64 file contents and filename, alongside contact_id and an optional message caption.
A queued response is not proof of delivery. Check GET /telegram/sent/?message_id=124.
The connected Telegram account sends the file to one contact.

PUBLICAR

Send a Telegram file using JSON

FIMhttps://api.smsmobileapi.com/telegram/send/

Queue one image or document using a Base64 string when multipart upload is inconvenient.

Quando usá-lo

Encode the original file bytes with Base64. Do not include an API key in the JSON body.

Parâmetros

Nome	Tipo	Requisito	Descrição
`contact_id`	inteiro	Obrigatório	ID de contato retornado por /telegram/contacts/.
`filename`	corda	Obrigatório	Original file name, for example photo.png or invoice.pdf.
`file_base64`	corda	Obrigatório	Raw Base64 file contents or a data URI; decoded file must be 5 MB or smaller.
`message`	corda	Opcional	Optional caption of at most 1024 characters.
`idempotency_key`	String UUID	Opcional	Reuse the same key with identical file contents, filename and caption on retries.

Exemplo de solicitação

enrolar

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"contact_id":42,"filename":"photo.png","file_base64":"BASE64_ENCODED_FILE","message":"See attached","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161"}'

Exemplo de resposta

JSON

{"ok":true,"message_id":125,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

Replace BASE64_ENCODED_FILE with the actual Base64 of a supported file.
Use multipart/form-data instead if your client supports direct file upload; it avoids Base64 size overhead.

PEGAR

Listar mensagens Telegram enviadas

FIMhttps://api.smsmobileapi.com/telegram/sent/

Retorna mensagens recentes em fila, enviando, enviadas e com falha, da mais nova para a mais antiga.

Quando usá-lo

Faça polling deste endpoint com message_id para acompanhar uma mensagem retornada por /telegram/send/.

Parâmetros

Nome	Tipo	Requisito	Descrição
`message_id`	inteiro	Opcional	Retorne o ID de mensagem específico de /telegram/send/.
`contact_id`	inteiro	Opcional	Limitar resultados a um ID de contato.
`status`	queued \| sending \| sent \| error \| unknown	Opcional	Filtrar por estado de envio.
`limit`	inteiro	Opcional	Tamanho da página de 1 a 100; padrão 50.
`cursor`	inteiro	Opcional	Use paging.next_cursor para buscar mensagens mais antigas.

Exemplo de solicitação

enrolar

curl -G 'https://api.smsmobileapi.com/telegram/sent/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  --data-urlencode 'message_id=123'

Exemplo de resposta

JSON

{"ok":true,"data":[{"message_id":123,"contact_id":42,"contact_name":"Alex Example","username":"alex_example","message":"Your appointment is confirmed.","type":"text","media":null,"status":"sent","telegram_message_id":781,"error_code":null,"error_detail":null,"attempts":1,"queued_at":"2026-11-06T09:42:00+00:00","sent_at":"2026-11-06T09:42:04+00:00"}],"paging":{"has_more":false,"next_cursor":null}}

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

The top-level type is text, image or file. For an attachment, media contains the filename, MIME type, size, download_url and available_until; media is null for text messages. File bytes are not embedded in the log.
The download_url opens in a browser for 15 minutes. Refresh this endpoint for a new link while the file remains available.
sent significa que o Telegram aceitou a mensagem da conta conectada; a entrega ao destinatário e os recibos de leitura não são reportados.
unknown significa que o resultado do envio não pôde ser confirmado. Não reenvie uma mensagem automaticamente nesse estado.

PEGAR

Download a sent Telegram attachment

FIMhttps://api.smsmobileapi.com/telegram/media/

Downloads a previously sent image or document while it remains available.

Quando usá-lo

Use media.download_url from the sent log, or call this endpoint with the account API key.

Parâmetros

Nome	Tipo	Requisito	Descrição
`message_id`	inteiro	Obrigatório	Message ID returned by /telegram/send/.

Exemplo de solicitação

enrolar

curl -L 'https://api.smsmobileapi.com/telegram/media/?message_id=124' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -o attachment

Exemplo de resposta

JSON

Binary image or document bytes (Content-Type matches the file)

Deseja executar esta solicitação?Conecte sua chave de API na parte superior da página para desbloquear o interativo testador.

Chave de conexão ↑

É bom saber

A download_url returned by /telegram/sent/ is signed and works without an API key for 15 minutes. Keep it private.
The authenticated endpoint requires the Telegram sent-log API access switch.
Files are retained for 90 days; the type and filename remain in the log after expiry.

Solução de problemas

Erros e novas tentativas seguras

Leia o status HTTP e o campo de erro JSON antes de tentar novamente. Não tente novamente falhas de validação ou autenticação sem primeiro corrigir a solicitação.

HTTP	Código	O que fazer
401	`api_key_required / invalid_api_key`	Envie um cabeçalho X-SMSMobileAPI-Key válido.
402	`subscription_expired`	Renew the SMSMobileAPI subscription linked to the API key. Telegram API access resumes after renewal.
403	`API_ENDPOINT_DISABLED`	Habilite o Telegram API ou este endpoint específico em My API Key.
404	`contact_not_found`	Sincronize contatos e use um ID da sua própria conexão Telegram.
409	`telegram_not_connected / idempotency_conflict`	Conecte Telegram ou escolha uma nova chave de idempotência para conteúdo alterado.
422	`invalid_message / invalid_pagination`	Corrija a mensagem, o ID de contato ou os parâmetros de paginação.
429	`queue_full / rate_limited`	Aguarde a liberação das filas de envio ou do limite por minuto.
503	`sending_unavailable / service_unavailable`	O trabalhador de envio ou o armazenamento está temporariamente indisponível; tente novamente mais tarde.
503	`media_not_ready`	File sending requires the current Telegram service update. Text sending remains available.
404 / 410	`media_not_found / media_expired`	The file is unavailable or past its 90-day retention period.

Regra de nova tentativaTente novamente apenas respostas transitórias 429 e 5xx. Comece após 1 segundo e depois volte para 2, 4 e 8 segundos.

Precisar de ajuda?

Traga o contexto da solicitação, não seus segredos.

Compartilhe o endpoint, o carimbo de data/hora, o status HTTP e a resposta limpa. Nunca inclua chaves de API, tokens ou conteúdo de mensagens privadas.

Entre em contato com o suporte da API →

O aplicativo móvel SMSMobileAPI seguro conectando um telefone ao painel web e REST API para operações de SMS e chamada — Ligação móvel-plataforma criptografada

Aplicação móvel oficial

A ponte segura entre o telefone, o painel e o API.

As operações de SMS e chamada passam pelo aplicativo oficial SMSMobileAPI instalado em seu telefone conectado. O aplicativo combina o dispositivo com sua conta, sincroniza eventos autorizados e liga a rede móvel ao painel de bordo e REST API.

1Aplicativo móvelEmparelha o telefone com o seu SIM 2Ligação criptografadaAutentica e protege dados em trânsito 3Painel de controle e APIControla fluxos de trabalho e atividade

Lançamentos assinados distribuídos através das listas oficiais do Google Play e Apple App Store
Controles de revisão, assinatura e distribuição da plataforma Google e Apple
Emparelhamento seguro de dispositivo, transporte HTTPS e acesso autenticado API
Apenas as permissões necessárias para as funcionalidades móveis que activa

Obtenha o aplicativo oficial SMSMobileAPI no Google Play

Baixe o aplicativo oficial SMSMobileAPI na Apple App Store

As capacidades dependem das permissões e do acesso de fundo permitidos pelo Android ou iOS.

Documentação Telegram API

Sua primeira solicitação em quatro etapas

Conectar

Encontrar um contato

Enviar

Acompanhar

Mantenha as credenciais no seu servidor

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Parâmetros

Exemplo de solicitação

Exemplo de resposta

Erros e novas tentativas seguras

Traga o contexto da solicitação, não seus segredos.

A ponte segura entre o telefone, o painel e o API.