Skip to content

Latest commit

 

History

History
228 lines (163 loc) · 7.16 KB

sending.md

File metadata and controls

228 lines (163 loc) · 7.16 KB
Raw

Sending Messages

Introduction

Bots have to send messages to deliver information and present an interface for their functionality. BotMan can send messages in several different ways, depending on the type and number of messages that will be sent.

Single message replies to incoming commands can be sent using the $bot->reply() function.

Multi-message replies, particularly those that present questions for the end user to respond to, can be sent using the $bot->startConversation() function and the related conversation sub-functions.

Bots can originate messages - that is, send a message based on some internal logic or external stimulus - using $bot->say() method.

Single Message Replies

Once a bot has received a message using hears(), you may send a response using $bot->reply().

This is the simplest way to respond to an incoming command:

$botman->hears('keyword', function (BotMan $bot) {
    $bot->reply("Tell me more!");
});

Do you feel like chatting some more? You may also send multiple responses in a single method.

$botman->hears('keyword', function (BotMan $bot) {
    $bot->reply("Tell me more!");
    $bot->reply("And even more");
});

Attachments

A common use case would be to not only send plain-text messages, but to also include an attachment along with your message. Depending on the messaging services you use, BotMan can send images, videos, audio files, generic files or even location data as attachment information.

You may do this by composing your message using the OutgoingMessage class. This class takes care of transforming your data for each individual messaging service.

use BotMan\BotMan\Messages\Attachments\Image;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('keyword', function (BotMan $bot) {
    // Create attachment
    $attachment = new Image('http://image-url-here.jpg');

    // Build message object
    $message = OutgoingMessage::create('This is my text')
                ->withAttachment($attachment);
    
    // Reply message object
    $bot->reply($message);
});

Images

You may use the Image class to attach an image URL to your outgoing message. It takes an image URL and an optional custom payload as constructor parameters,

use BotMan\BotMan\Messages\Attachments\Image;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

// Create attachment
$attachment = new Image('http://image-url-here.jpg', [
    'custom_payload' => true,
]);

// Build message object
$message = OutgoingMessage::create('This is my text')
            ->withAttachment($attachment);
    
// Reply message object
$bot->reply($message);

Videos

You may use the Video class to attach a video URL to your outgoing message. It takes a video URL and an optional custom payload as constructor parameters.

use BotMan\BotMan\Messages\Attachments\Video;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

// Create attachment
$attachment = new Video('http://video-url-here.mp4', [
    'custom_payload' => true,
]);

// Build message object
$message = OutgoingMessage::create('This is my text')
            ->withAttachment($attachment);
    
// Reply message object
$bot->reply($message);

Audio

You may use the Audio class to attach an audio URL to your outgoing message. It takes an audio URL and an optional custom payload as constructor parameters.

use BotMan\BotMan\Messages\Attachments\Audio;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

// Create attachment
$attachment = new Audio('http://audio-url-here.mp3', [
    'custom_payload' => true,
]);

// Build message object
$message = OutgoingMessage::create('This is my text')
            ->withAttachment($attachment);
    
// Reply message object
$bot->reply($message);

Generic Files

You may use the File class to attach a generic file URL to your outgoing message. It takes a file URL and an optional custom payload as constructor parameters.

use BotMan\BotMan\Messages\Attachments\File;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

// Create attachment
$attachment = new File('http://file-url-here.pdf', [
    'custom_payload' => true,
]);

// Build message object
$message = OutgoingMessage::create('This is my text')
            ->withAttachment($attachment);
    
// Reply message object
$bot->reply($message);

Location Information

You may use the Location class to attach a GPS location information to your outgoing message. It takes the latitude, longitude and an optional custom payload as constructor parameters.

use BotMan\BotMan\Messages\Attachments\Location;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

// Create attachment
$attachment = new Location(61.766130, -6.822510, [
    'custom_payload' => true,
]);

// Build message object
$message = OutgoingMessage::create('This is my text')
            ->withAttachment($attachment);
    
// Reply message object
$bot->reply($message);

Type Indicators

To make your bot feel and act more human, you can make it send "typing ..." indicators.

$botman->hears('keyword', function (BotMan $bot) {
    $bot->typesAndWaits(2);
    $bot->reply("Tell me more!");
});

This will send a typing indicator and sleep for 2 seconds, before actually sending the "Tell me more!" response.

Please note, that not all messaging services support typing indicators. If it is not supported, it will simply do nothing and just reply the message.

Originating Messages

BotMan also allows you to send messages to your chat users programatically. You could, for example, send out a daily message to your users that get's triggered by your cronjob.

The easiest way is to just specify the driver-specific recipient ID when calling the say method and the driver to use.

$botman->say('Message', 'my-recipient-user-id', TelegramDriver::class);

Just as the regular reply method, this method also accepts either simple strings or OutgoingMessage objects.

Sending Low-Level Requests

Sometimes you develop your chatbot and come to the conclusion that you would need to call a particular native messaging service API. As BotMan tries to decouple as many APIs as possible, it is not possible to have all API methods for each messaging service in the core of BotMan.

For this exact reason, there is the sendRequest method on the BotMan instance. What it does is, that it calls the messaging service endpoint with the given arguments and returns a Response object.

// Calling the sendSticker API for Telegram
$botman->hears('sticker', function($bot) {
	$bot->sendRequest('sendSticker', [
		'sticker' => '1234'
	])
});

If your API endpoint needs a Chat-ID, User-ID or Channel-ID that BotMan already knows, it will be passed along in the appropriate format for you, so you do not need to worry about it.