Skip to content

Commit

Permalink
README UPDATE
Browse files Browse the repository at this point in the history
  • Loading branch information
@MBoretto
MBoretto committed Sep 8, 2015
1 parent 2ba5c48 commit 606cf12
Showing 1 changed file with 122 additions and 69 deletions.
191 changes: 122 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,69 @@
# PHP Telegram Bot
======================

[![Join the chat at https://gitter.im/akalongman/php-telegram-bot](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/akalongman/php-telegram-bot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Join the chat at
https://gitter.im/akalongman/php-telegram-bot](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/akalongman/php-telegram-bot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

[![Build Status](https://travis-ci.org/akalongman/php-telegram-bot.svg?branch=master)](https://travis-ci.org/akalongman/php-telegram-bot)
[![Latest Stable Version](https://img.shields.io/packagist/v/Longman/telegram-bot.svg)](https://packagist.org/packages/longman/telegram-bot)
[![Latest Stable
Version](https://img.shields.io/packagist/v/Longman/telegram-bot.svg)](https://packagist.org/packages/longman/telegram-bot)
[![Total Downloads](https://img.shields.io/packagist/dt/Longman/telegram-bot.svg)](https://packagist.org/packages/longman/telegram-bot)
[![Downloads Month](https://img.shields.io/packagist/dm/Longman/telegram-bot.svg)](https://packagist.org/packages/longman/telegram-bot)
[![License](https://img.shields.io/packagist/l/Longman/telegram-bot.svg)](https://packagist.org/packages/longman/telegram-bot)


A Telegram Bot based on the official [Telegram Bot API](https://core.telegram.org/bots/api)
A Telegram Bot based on the official [Telegram Bot
API](https://core.telegram.org/bots/api)


## Introduction
This is a pure php Telegram Bot, fully extensible via plugins. Telegram recently announced official support for a [Bot API](https://telegram.org/blog/bot-revolution) allowing integrators of all sorts to bring automated interactions to the mobile platform. This Bot aims to provide a platform where one could simply write a plugin and have interactions in a matter of minutes.
The Bot supports Reply Markup and handle commands in group chat with multiple bot.
### Introduction
This is a pure php Telegram Bot, fully extensible via plugins.
Telegram recently announced official support for a [Bot
API](https://telegram.org/blog/bot-revolution) allowing integrators of
all sorts to bring automated interactions to the mobile platform. This
Bot aims to provide a platform where one could simply write a plugin
and have interactions in a matter of minutes.
- The Bot supports Reply Markup and handle commands in group chat with
multiple bot.
- The Bot can retrive update with webhook and by getUpdate methods.


Instructions
============
## Instructions
### Create your first bot

1. Message @botfather https://telegram.me/botfather with the following text: `/newbot`
If you don't know how to message by username, click the search field on your Telegram app and type `@botfather`, you should be able to initiate a conversation. Be careful not to send it to the wrong contact, because some users has similar usernames to `botfather`.
1. Message @botfather https://telegram.me/botfather with the following
text: `/newbot`
If you don't know how to message by username, click the search
field on your Telegram app and type `@botfather`, you should be able
to initiate a conversation. Be careful not to send it to the wrong
contact, because some users has similar usernames to `botfather`.

![botfather initial conversation](http://i.imgur.com/aI26ixR.png)

2. @botfather replies with `Alright, a new bot. How are we going to call it? Please choose a name for your bot.`
2. @botfather replies with `Alright, a new bot. How are we going to
call it? Please choose a name for your bot.`

3. Type whatever name you want for your bot.

4. @botfather replies with `Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.`
4. @botfather replies with `Good. Now let's choose a username for your
bot. It must end in `bot`. Like this, for example: TetrisBot or
tetris_bot.`

5. Type whatever username you want for your bot, minimum 5 characters, and must end with `bot`. For example: `telesample_bot`
5. Type whatever username you want for your bot, minimum 5 characters,
and must end with `bot`. For example: `telesample_bot`

6. @botfather replies with:

Done! Congratulations on your new bot. You will find it at telegram.me/telesample_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
Done! Congratulations on your new bot. You will find it at
telegram.me/telesample_bot. You can now add a description, about
section and profile picture for your bot, see /help for a list of
commands.

Use this token to access the HTTP API:
<b>123456789:AAG90e14-0f8-40183D-18491dDE</b>

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
For a description of the Bot API, see this page:
https://core.telegram.org/bots/api

7. Note down the 'token' mentioned above.

Expand All @@ -51,27 +73,28 @@ Instructions

9. @botfather replies with `Choose a bot to change group messages settings.`

10. Type `@telesample_bot` (change to the username you set at step 5 above, but start it with `@`)
10. Type `@telesample_bot` (change to the username you set at step 5
above, but start it with `@`)

11. @botfather replies with

'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Enable' - your bot will only receive messages that either start
with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED

12. Type `Disable` to let your bot receive all messages sent to a group. This step is up to you actually.
12. Type `Disable` to let your bot receive all messages sent to a
group. This step is up to you actually.

13. @botfather replies with `Success! The new status is: DISABLED. /help`


### Require this package with Composer
Install this package through [Composer](https://getcomposer.org/).
Edit your project's `composer.json` file to require
`longman/telegram-bot`.


## Installation
You need server with https and composer support.

Install this package through [Composer](https://getcomposer.org/). Edit your project's `composer.json` file to require `longman/telegram-bot`.

Create composer.json file:
Create *composer.json* file:
```js
{
"name": "yourproject/yourproject",
Expand All @@ -90,14 +113,20 @@ And run composer update
composer require longman/telegram-bot
```

###### Bot token
You will notice that the Telegram Bot wants a value for `API_KEY`. This token may be obtained via a telegram client for your bot. See [this](https://core.telegram.org/bots#botfather) link if you are unsure of how to so this.
### Choose how to retrieve Telegram updates
The bot can handle updates with **webhook** or **getUpdate** method:

| Method | Webhook | getUpdate |
| ---- | :----: | :----: |
| Description | Telegram send the update directy to your host | Yuo
have to fetch Telegram updates |
| Host with https | Required | Not required |
| Mysql | Not required | Required |

## Usage
## Webhook installation
You need server with https and composer support.
You must set a [WebHook](https://core.telegram.org/bots/api#setwebhook)

Create set.php and put into it:
Create *set.php* (just edit *example-set.php*) and put into it:
```php
<?php
$loader = require __DIR__.'/vendor/autoload.php';
Expand All @@ -114,10 +143,10 @@ try {
echo $e->getMessage();
}
```
And open your set.php via browser
And open your *set.php* via browser.


After create hook.php and put:
After create *hook.php* (just edit *example-hook.php*) and put:
```php
<?php
$loader = require __DIR__.'/vendor/autoload.php';
Expand All @@ -127,9 +156,7 @@ $BOT_NAME = 'namebot';

try {
// create Telegram API object
$telegram = new Longman\TelegramBot\Telegram($API_KEY,$BOT_NAME);
// here you can set some command specified parameters, for example, google geocode/timezone api key for date command:
$telegram->setCommandConfig('date', array('google_api_key'=>'your_google_api_key_here'));
$telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);

// handle telegram webhook request
$telegram->handle();
Expand All @@ -138,25 +165,44 @@ try {
// echo $e->getMessage();
}
```
## getUpdate installation NEW!
You need the database Mysql active.

##MySQL storage
If you want insert in database messages/users for further usage in commands, create database and import structure.sql and enable mysql support after object creation and BEFORE handle method
Create *getUpdateCLI.php* (just edit *example-getUpdateCLI.php*) and
put into it:
```php
code
```
give to the file the permission for execution:
```
chmod 775 getUpdateCLI.php
```
then run
```
./getUpdateCLI.php
```
## Utilis
### MySQL storage (Recomended)
If you want insert in database messages/users/chats for further usage
in commands, create database and import *structure.sql* and enable
Mysql support after object creation and BEFORE handle method:

```php
<?php
$credentials = array('host'=>'localhost', 'user'=>'dbuser', 'password'=>'dbpass', 'database'=>'dbname');

$credentials = array('host'=>'localhost', 'user'=>'dbuser',
'password'=>'dbpass', 'database'=>'dbname');

$telegram->enableMySQL($credentials);
```
You can set a custom prefix to all the tables while you are enabling mysql:
You can set a custom prefix to all the tables while you are enabling Mysql:

```php
$telegram->enableMySQL($credentials, $BOT_NAME.'_');

```

##Commands
The bot is able to recognise commands in chat with multiple bot.
### Commands
The bot is able to recognise commands in chat with multiple bot(
/command@mybot ).
It can execute command triggering a chat event. Here's the list:

- Group chat created (**GroupchatcreatedCommand.php**)
Expand All @@ -165,38 +211,47 @@ It can execute command triggering a chat event. Here's the list:
- New chat title (**NewchattitleCommand.php**)
- Left chat participant (**LeftchatparticipantCommand.php**)

**GenericCommand.php** lets you handle commands that don't exist or to use commands as a variable:
**GenericCommand.php** lets you handle commands that don't exist or to
use commands as a variable:
Favourite colour? **/black, /red**
Favourite number? **/1, /134**


Maybe you would like to develop your own commands. A good practice is to store them outside vendor/. This can be done adding the method:
Maybe you would like to develop your own commands. A good practice is
to store them outside vendor/. This can be done adding the method:

```php
$COMMANDS_FOLDER = __DIR__.'/Commands/';
$telegram->addCommandsPath($COMMANDS_FOLDER);

```

##Admin Commands (new!)
Enabling this feature, the admin bot can perform some super user command like send message to all.
### Admin Commands (new!)
Enabling this feature, the admin bot can perform some super user
command like send message to all.
You can specify one or more admin with this option:

```php
$telegram->enableAdmins(array('TelegramUserID','Othersid'));
```
Telegram user id can be retrieved with the command /whoami.
Admin commands are stored in src/Admin/ folder.
To know all the commands avaiable type /help.
Telegram user id can be retrieved with the command **/whoami**.
Admin commands are stored in *src/Admin/* folder.
To know all the commands avaiable type **/help**.

##Send message to all active chats
To do this you have to enable the mysql connection.
### Commands Configuration
With this method you can set some command specified parameters, for
example, google geocode/timezone api key for date command:
```php
$telegram->setCommandConfig('date',
array('google_api_key'=>'your_google_api_key_here'));
```
### Send message to all active chats
To do this you have to enable the Mysql connection.
Here's an example of use:

```php
$results = $telegram->sendToActiveChats(
'sendMessage', //callback function to execute (see Request.php methods)
array('text'=>'Hey! Checkout the new feature!!'), //Param to evaluate the request
array('text'=>'Hey! Checkout the new feature!!'), //Param to
evaluate the request
true, //Send to chats (group chat)
true, //Send to users (single chat)
null, //'yyyy-mm-dd hh:mm:ss' date range from
Expand All @@ -206,28 +261,26 @@ $results = $telegram->sendToActiveChats(
print_r($results);
```

##Utilis
You can also log incoming messages on a text file, set this option with the methods:
### Logging
You can also log incoming messages on a text file, set this option
with the methods:
```php
$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');

```
-----

This code is available on [Github](https://github.com/akalongman/php-telegram-bot). Pull requests are welcome.

This code is available on
[Github](https://github.com/akalongman/php-telegram-bot). Pull
requests are welcome.

##Troubleshooting

If you like living on the edge, please report any bugs you find on the [PHP Telegram Bot issues](https://github.com/akalongman/php-telegram-bot/issues) page.


##Contributing

## Troubleshooting
If you like living on the edge, please report any bugs you find on the
[PHP Telegram Bot
issues](https://github.com/akalongman/php-telegram-bot/issues) page.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for information.


## Credits

Credit list in [CREDITS](CREDITS)

0 comments on commit 606cf12

Please sign in to comment.