Telegram Bot PHP SDK

Telegram Bot API PHP SDK

Welcome to the Telegram Bot SDK developer hub. You'll find comprehensive guides and documentation to help you start working with Telegram Bot SDK as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog
Suggest Edits

getMe

A simple method for testing your bot's auth token.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/getMe
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->getMe();

$botId = $response->getId();
$firstName = $response->getFirstName();
$username = $response->getUsername();
$response = Telegram::getMe();

$botId = $response->getId();
$firstName = $response->getFirstName();
$username = $response->getUsername();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "id": 12345678,
        "first_name": "YourBot",
        "username": "YourBot"
    }
}
{
    "ok": false,
    "error_code": 401,
    "description": "[Error]: Unauthorized"
}
 

A simple method for testing your bot's auth token. Requires no parameters. Returns basic information about the bot in form of a User object.

Suggest Edits

sendMessage

Use this method to send text messages.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendMessage
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendMessage([
  'chat_id' => 'CHAT_ID', 
  'text' => 'Hello World'
]);

$messageId = $response->getMessageId();
$response = Telegram::sendMessage([
  'chat_id' => 'CHAT_ID', 
  'text' => 'Hello World'
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 1234567890,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459958199,
        "text": "Hello from Bot!"
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: chat_id is empty"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

text
string

Text of the message to be sent

parse_mode
string

Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message.

disable_web_page_preview
boolean

Disables link previews for links in this message

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send text messages. On success, the sent Message is returned.

See sendMessage official docs for a list of supported parameters and other info.

Formatting Options

The Bot API supports basic formatting for messages. You can use bold and italic text, as well as inline links and pre-formatted code in your bots' messages. Telegram clients will render them accordingly. You can use either markdown-style or HTML-style formatting.

Note that Telegram clients will display an alert to the user before opening an inline link (‘Open this link?’ together with the full URL).

Markdown style

To use this mode, pass Markdown in the parse_mode field when using sendMessage. Use the following syntax in your message:

*bold text*
_italic text_
[text](URL)
`inline fixed-width code`
```pre-formatted fixed-width code block```

HTML style

To use this mode, pass HTML in the parse_mode field when using sendMessage. The following tags are currently supported:

<b>bold</b>, <strong>bold</strong>
<i>italic</i>, <em>italic</em>
<a href="URL">inline URL</a>
<code>inline fixed-width code</code>
<pre>pre-formatted fixed-width code block</pre>

Please Note

  • Only the tags mentioned above are currently supported.
  • Tags must not be nested.
  • All <, > and & symbols that are not a part of a tag or an HTML entity must be replaced with the corresponding HTML entities (< with &lt;, > with &gt; and & with &amp;).
  • All numerical HTML entities are supported.
  • The API currently supports only the following named HTML entities: <, >, & and ".
Suggest Edits

forwardMessage

Use this method to forward messages of any kind.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/forwardMessage
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->forwardMessage([
  'chat_id' => 'CHAT_ID', 
  'from_chat_id' => 'FROM_CHAT_ID',
	'message_id' => 'MESSAGE_ID'
]);

$messageId = $response->getMessageId();
$response = Telegram::forwardMessage([
  'chat_id' => 'CHAT_ID', 
  'from_chat_id' => 'FROM_CHAT_ID',
	'message_id' => 'MESSAGE_ID'
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "forward_from": {
            "id": 123456,
            "first_name": "Jason",
            "last_name": "Doe",
            "username": "JasonDoe"
        },
        "forward_date": 1459977304,
        "text": "Hey"
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: message not found"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

from_chat_id
mixed type

Unique identifier for the chat where the original message was sent (or channel username in the format @channelusername)

message_id
int32

Unique message identifier

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

 

Use this method to forward messages of any kind. On success, the sent Message is returned.

See forwardMessage official docs for a list of supported parameters and other info.

Suggest Edits

sendPhoto

Use this method to send photos.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendPhoto
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendPhoto([
  'chat_id' => 'CHAT_ID', 
  'photo' => 'path/to/photo.jpg', 
	'caption' => 'Some caption'
]);

$messageId = $response->getMessageId();
$response = Telegram::sendPhoto([
  'chat_id' => 'CHAT_ID', 
  'photo' => 'path/to/photo.jpg', 
	'caption' => 'Some caption'
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "photo": [
            {
                "file_id": "AbCdE123XyZ...",
                "file_size": 1437,
                "width": 70,
                "height": 90
            },
            {
                "file_id": "AbCdE123XyZ...",
                "file_size": 17334,
                "width": 248,
                "height": 320
            },
            {
                "file_id": "AbCdE123XyZ...",
                "file_size": 62089,
                "width": 620,
                "height": 800
            },
            {
                "file_id": "AbCdE123XyZ...",
                "file_size": 122255,
                "width": 992,
                "height": 1280
            },
            {
                "file_id": "AbCdE123XyZ...",
                "file_size": 128541,
                "width": 1280,
                "height": 1652
            }
        ]
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no photo in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

photo
string

Photo to send. You can either pass a file_id as String to resend a photo that is already on the Telegram servers, or upload a new photo by just passing the path to the file as String and the SDK will take care of uploading the file for you. You can also directly pass Image URL as String to automatically download and send it to Telegram.

caption
string

Photo caption (may also be used when resending photos by file_id), 0-200 characters

disable_notification
boolean

Sends the message (silently)[https://telegram.org/blog/channels-2-0#silent-messages]. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a (custom reply keyboard)[https://core.telegram.org/bots#keyboards], instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send photos. On success, the sent Message is returned.

See sendPhoto official docs for a list of supported parameters and other info.

Sending Photo Using Image URL

The ability to send an image directly from a URL is also supported in the library. Instead of supplying a local path and filename, you may just pass the image URL and it'll take care of downloading and sending it to the Telegram directly.

Example

use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendPhoto([
	'chat_id' => 'CHAT_ID', 
	'photo' => 'http://example.com/photos/image.jpg',
	'caption' => 'Some caption'
]);

$messageId = $response->getMessageId();
$response = Telegram::sendPhoto([
	'chat_id' => 'CHAT_ID', 
	'photo' => 'http://example.com/photos/image.jpg',
	'caption' => 'Some caption'
]);

$messageId = $response->getMessageId();

Sending Photo using a File or URL!

The API Explorer below doesn't support file upload or URL based photo sending. You can only use it to test using an existing file_id, if you have one.

This is a limitation of this API Explorer, Not the SDK.

Suggest Edits

sendAudio

Use this method to send audio files, if you want Telegram clients to display them in the music player.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendAudio
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendAudio([
  'chat_id' => 'CHAT_ID', 
  'audio' => 'path/to/audio.mp3',
]);

$messageId = $response->getMessageId();
$response = Telegram::sendAudio([
  'chat_id' => 'CHAT_ID', 
  'audio' => 'path/to/audio.mp3',
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "audio": {
            "file_id": "aBc124XyZ...",
            "duration": 154,
            "mime_type": "audio/mpeg",
            "title": "My Audio File",
            "performer": "John Doe",
            "file_size": 2521100
        }
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no audio in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

audio
string

Audio file to send. You can either pass a file_id as String to resend an audio that is already on the Telegram servers, or upload a new audio file by just passing the path to audio file as String and the SDK will take care of uploading the file for you.

duration
int32

Duration of the audio in seconds

performer
string

Performer

track
string

Track name

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send audio files, if you want Telegram clients to display them in the music player. Your audio must be in the .mp3 format. On success, the sent Message is returned. Bots can currently send audio files of up to 50 MB in size, this limit may be changed in the future.

For sending voice messages, use the sendVoice method instead.

See sendAudio official docs for a list of supported parameters and other info.

Suggest Edits

sendDocument

Use this method to send general files.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendDocument
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendDocument([
  'chat_id' => 'CHAT_ID', 
  'document' => 'path/to/document.pdf',
	'caption' => 'This is a document',
]);

$messageId = $response->getMessageId();
$response = Telegram::sendDocument([
  'chat_id' => 'CHAT_ID', 
  'document' => 'path/to/document.pdf',
	'caption' => 'This is a document',
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "document": {
            "file_id": "Abc123XyZ....",
            "file_name": "Document.pdf",
            "mime_type": "application/pdf",
            "thumb": {
                "file_id": "Abc532xYz...",
                "file_size": 6859,
                "width": 200,
                "height": 200
            },
            "file_size": 306738
        },
        "caption": "This is document"
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no document in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

document
string

File to send. You can either pass a file_id as String to resend a file that is already on the Telegram servers, or upload a new file by just passing the path to the file as String and the SDK will take care of uploading it for you.

caption
string

Document caption (may also be used when resending documents by file_id), 0-200 characters

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.

See sendDocument official docs for a list of supported parameters and other info.

Suggest Edits

sendSticker

Use this method to send .webp stickers.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendSticker
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendSticker([
  'chat_id' => 'CHAT_ID', 
  'sticker' => 'path/to/sticker.webp',
]);

$messageId = $response->getMessageId();
$response = Telegram::sendSticker([
  'chat_id' => 'CHAT_ID', 
  'sticker' => 'path/to/sticker.webp',
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "sticker": {
            "file_id": "Abc124xYz...",
            "width": 457,
            "height": 512,
            "thumb": {
                "file_id": "Abc124xYz...",
                "file_size": 6306,
                "width": 114,
                "height": 128
            },
            "file_size": 39082
        }
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no sticker in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

sticker
string

Sticker to send. You can either pass a file_id as String to resend a sticker that is already on the Telegram servers, or upload a new sticker file by just passing the path to the file as String and the SDK will take care of uploading the file for you.

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send .webp stickers. On success, the sent Message is returned.

See sendSticker official docs for a list of supported parameters and other info.

Suggest Edits

sendVideo

Use this method to send video files.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendVideo
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendVideo([
  'chat_id' => 'CHAT_ID', 
  'video' => 'path/to/video.mp4',
]);

$messageId = $response->getMessageId();
$response = Telegram::sendVideo([
  'chat_id' => 'CHAT_ID', 
  'video' => 'path/to/video.mp4',
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976718,
        "video": {
            "file_id": "Abc124xYz...",
            "width": 457,
            "height": 512,
            "duration": 120,
            "thumb": {
                "file_id": "Abc124xYz...",
                "file_size": 6306,
                "width": 114,
                "height": 128
            },
            "mime_type": "video/mp4",
            "file_size": 39082
        }
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no video in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

video
string

Video to send. You can either pass a file_id as String to resend a video that is already on the Telegram servers, or upload a new video file by just passing the path to the file as String and the SDK will take care of uploading the file for you.

duration
int32

Duration of sent video in seconds

width
int32

Video width

height
int32

Video height

caption
string

Video caption (may also be used when resending videos by file_id), 0-200 characters

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document). On success, the sent Message is returned. Bots can currently send video files of up to 50 MB in size, this limit may be changed in the future.

See sendVideo official docs for a list of supported parameters and other info.

Suggest Edits

sendVoice

Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendVoice
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->sendVoice([
  'chat_id' => 'CHAT_ID', 
  'voice' => 'path/to/voice.ogg',
]);

$messageId = $response->getMessageId();
$response = Telegram::sendVoice([
  'chat_id' => 'CHAT_ID', 
  'voice' => 'path/to/voice.ogg',
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976225,
        "voice": {
          	"file_id": "Abc123XyZ....",
            "duration": 5,
          	"mime_type": "audio/ogg",
          	"file_size": 35015
        }
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: there is no voice in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

voice
string

Audio file to send. You can either pass a file_id as String to resend an audio that is already on the Telegram servers, or upload a new audio file by just passing the path to audio file as String and the SDK will take care of uploading the file for you.

duration
int32

Duration of the audio in seconds

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message. For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as Audio or Document). On success, the sent Message is returned. Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the future.

See sendVoice official docs for a list of supported parameters and other info.

Suggest Edits

sendLocation

Use this method to send point on the map.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendLocation
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

// Sends San Francisco, CA Location.
$response = $telegram->sendLocation([
  'chat_id' => 'CHAT_ID', 
  'latitude' => 37.7576793,
	'longitude' => -122.5076402,
]);

$messageId = $response->getMessageId();
// Sends San Francisco, CA Location.
$response = Telegram::sendLocation([
  'chat_id' => 'CHAT_ID', 
  'latitude' => 37.7576793,
	'longitude' => -122.5076402,
]);

$messageId = $response->getMessageId();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "message_id": 1,
        "from": {
            "id": 12345678,
            "first_name": "YourBot",
            "username": "YourBot"
        },
        "chat": {
            "id": 123456789,
            "first_name": "John",
            "last_name": "Doe",
            "username": "JohnDoe",
            "type": "private"
        },
        "date": 1459976225,
        "location": {
            "latitude": 37.7576793,
            "longitude": -122.5076402
        }
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: longitude is empty"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

latitude
double

Latitude of location

longitude
double

Longitude of location

disable_notification
boolean

Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. Other apps coming soon.

reply_to_message_id
int32

If the message is a reply, ID of the original message

reply_markup
object

Additional interface options. A JSON-serialized object for a custom reply keyboard, instructions to hide keyboard or to force a reply from the user.

 
 

Use this method to send point on the map. On success, the sent Message is returned.

See sendLocation official docs for a list of supported parameters and other info.

Suggest Edits

sendChatAction

Use this method when you need to tell the user that something is happening on the bot's side.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/sendChatAction
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$telegram->sendChatAction([
  'chat_id' => 'CHAT_ID', 
  'action' => 'upload_photo'
]);
Telegram::sendChatAction([
  'chat_id' => 'CHAT_ID', 
  'action' => 'upload_photo'
]);
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": true
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: wrong parameter action in request"
}

Body Params

chat_id
mixed type

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

action
string

Type of action to broadcast. Choose one, depending on what the user is about to receive: typing for text messages, upload_photo for photos, record_video or upload_video for videos, record_audio or upload_audio for audio files, upload_document for general files, find_location for location data.

 

Use this method when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).

Example: The ImageBot needs some time to process a request and upload the image. Instead of sending a text message along the lines of “Retrieving image, please wait…”, the bot may use sendChatAction with action = upload_photo. The user will see a “sending photo” status for the bot.

Telegram only recommends using this method when a response from the bot will take a noticeable amount of time to arrive.

See sendChatAction official docs for a list of supported actions and other info.

Actions Helper

The SDK also has a helper method for supplying the chat action. This is especially useful with code completion with your IDE.

Example

use Telegram\Bot\Api;
use Telegram\Bot\Actions;

$telegram = new Api('BOT TOKEN');

$telegram->sendChatAction([
  'chat_id' => 'CHAT_ID', 
  'action' => Actions::RECORD_VIDEO
]);
use Telegram\Bot\Actions;

Telegram::sendChatAction([
  'chat_id' => 'CHAT_ID', 
  'action' => Actions::RECORD_VIDEO
]);
Suggest Edits

getUserProfilePhotos

Use this method to get a list of profile pictures for a user.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/getUserProfilePhotos
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->getUserProfilePhotos(['user_id' => 'USER_ID']);

$photos_count = $response->getTotalCount();
$photos = $response->getPhotos();
$response = Telegram::getUserProfilePhotos(['user_id' => 'USER_ID']);

$photos_count = $response->getTotalCount();
$photos = $response->getPhotos();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "total_count": 2,
        "photos": [
            [
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 8394,
                    "width": 160,
                    "height": 160
                },
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 21897,
                    "width": 320,
                    "height": 320
                },
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 57547,
                    "width": 640,
                    "height": 640
                }
            ],
            [
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 12119,
                    "width": 160,
                    "height": 160
                },
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 40456,
                    "width": 320,
                    "height": 320
                },
                {
                    "file_id": "AgABC12345678910111213abc...",
                    "file_size": 145749,
                    "width": 640,
                    "height": 640
                }
            ]
        ]
    }
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad Request: user not found"
}

Body Params

user_id
int32

Unique identifier of the target user

offset
int32

Sequential number of the first photo to be returned. By default, all photos are returned.

limit
int32

Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100.

 

Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object.

See getUserProfilePhotos official docs for a list of supported parameters and other info.

Suggest Edits

getUpdates

Use this method to receive incoming updates using long polling.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/getUpdates
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->getUpdates();
$response = Telegram::getUpdates();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": [
        {
            "update_id": 123456789,
            "message": {
                "message_id": 1,
                "from": {
                    "id": 1234567890,
                    "first_name": "John",
                    "last_name": "Doe",
                    "username": "JohnDoe"
                },
                "chat": {
                    "id": 1234567890,
                    "first_name": "John",
                    "last_name": "Doe",
                    "username": "JohnDoe",
                    "type": "private"
                },
                "date": 1459957719,
                "text": "/start start"
            }
        },
        {
            "update_id": 1234567810,
            "message": {
                "message_id": 2,
                "from": {
                    "id": 1234567890,
                    "first_name": "John",
                    "last_name": "Doe",
                    "username": "JohnDoe"
                },
                "chat": {
                    "id": 1234567890,
                    "first_name": "John",
                    "last_name": "Doe",
                    "username": "JohnDoe",
                    "type": "private"
                },
                "date": 1459957722,
                "text": "Hello Bot!"
            }
        }
    ]
}

Body Params

offset
int32

Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will forgotten.

limit
int32

Limits the number of updates to be retrieved. Values between 1—100 are accepted. Defaults to 100.

timeout
int32

Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling

 

Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned.

Notes

1. This method will not work if an outgoing webhook is set up.
2. In order to avoid getting duplicate updates, recalculate offset after each server response.

Suggest Edits

setWebhook

Use this method to specify a url and receive incoming updates via an outgoing webhook.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/setWebhook
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->setWebhook(['url' => 'https://example.com/<token>/webhook']);

// Or if you are supplying a self-signed-certificate
$response = $telegram->setWebhook([
  'url' => 'https://example.com/<token>/webhook',
  'certificate' => '/path/to/public_key_certificate.pub'
]);
// Don't forget to setup a POST route in your Laravel Project.
$response = Telegram::setWebhook(['url' => 'https://example.com/<token>/webhook']);

// Or if you are supplying a self-signed-certificate
$response = Telegram::setWebhook([
  'url' => 'https://example.com/<token>/webhook',
  'certificate' => '/path/to/public_key_certificate.pub'
]);
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": true,
    "description": "Webhook was set"
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad webhook: [Error]: HTTPS url must be provided for webhooks"
}
{
    "ok": false,
    "error_code": 400,
    "description": "[Error]: Bad webhook: [Error]: getaddrinfo: Name or service not known"
}

Body Params

url
string

HTTPS url to send updates to. Use an empty string to remove webhook integration

certificate
file

Upload your public key certificate so that the root certificate in use can be checked. See our self-signed guide for details.

 

Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified url, containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts.

If you'd like to make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL, e.g. https://www.example.com/<token>. Since nobody else knows your bot‘s token, you can be pretty sure it’s us.

See setWebhook official docs for a list of supported parameters and other info.

Notes

1. You will not be able to receive updates using getUpdates for as long as an outgoing webhook is set up.
2. To use a self-signed certificate, you need to upload your public key certificate using certificate parameter. Please upload as InputFile, sending a String will not work.
3. Ports currently supported for Webhooks: 443, 80, 88, 8443.

Suggest Edits

removeWebhook

Use this method to remove a previously set outgoing webhook.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/setWebhook
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->removeWebhook();
$response = Telegram::removeWebhook();
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": true,
    "description": "Webhook was deleted"
}
{
    "ok": true,
    "result": true,
    "description": "There is no webhook to delete"
}
{
    "ok": true,
    "result": true,
    "description": "Webhook is already deleted"
}

Body Params

url
string

You need not specify any params. The helper method will take care for you.

 

Use this method to remove a previously set outgoing webhook.

This is a helper method from the SDK. The Official API doesn't support this method directly.
The method simply makes a call to setWebhook using empty url param. This tells Telegram to remove the webhook (If there's one).

Suggest Edits

getFile

Use this method to get basic info about a file and prepare it for downloading.

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.telegram.org/bot[[app:token]]/getFile
use Telegram\Bot\Api;

$telegram = new Api('BOT TOKEN');

$response = $telegram->getFile(['file_id' => 'ABC12345XYZ6789...']);
$response = Telegram::getFile(['file_id' => 'ABC12345XYZ6789...']);
A binary file was returned

You couldn't be authenticated

{
    "ok": true,
    "result": {
        "file_id": "ABC12345XYZ6789...",
        "file_size": 39082,
        "file_path": "document/file_1.webp"
    }
}

Body Params

file_id
string

File identifier to get info about

 

Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size. On success, a File object is returned.

The file can then be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>, where <file_path> is taken from the response. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling getFile again.

See getFile official docs for a list of supported parameters and other info.