receiving-additional-content.md

Hearing Attachments

• Introduction
• Images
• Videos
• Audio
• Files
• Locations

Introduction

Similar to hearing for text input, BotMan also allows you to listen for incoming attachments like images, videos, audio messages or even shared locations.

Listen for images

Making your bot listen to incoming images is easy. Just use the receivesImages method on the BotMan instance. All received images will be passed to the callback as a second argument.

The images returned will be an array of BotMan\BotMan\Messages\Attachments\Image objects.

use BotMan\BotMan\Messages\Attachments\Image;

$bot->receivesImages(function($bot, $images) {

    foreach ($images as $image) {

        $url = $image->getUrl(); // The direct url
        $title = $image->getTitle(); // The title, if available
        $payload = $image->getPayload(); // The original payload
    }
});

Listen for videos

Just like images, you can use the receivesVideos method on the BotMan instance to listen for incoming video file uploads. All received videos will be passed to the callback as a second argument.

The videos returned will be an array of BotMan\BotMan\Messages\Attachments\Video objects.

use BotMan\BotMan\Messages\Attachments\Video;

$bot->receivesVideos(function($bot, $videos) {

    foreach ($videos as $video) {

        $url = $video->getUrl(); // The direct url
        $payload = $video->getPayload(); // The original payload
    }
});

Listen for audio

Just like images, you can use the receivesAudio method on the BotMan instance to listen for incoming audio file uploads. All received audio files will be passed to the callback as a second argument.

The audio files returned will be an array of BotMan\BotMan\Messages\Attachments\Audio objects.

use BotMan\BotMan\Messages\Attachments\Audio;

$bot->receivesAudio(function($bot, $audios) {

    foreach ($audios as $audio) {

        $url = $audio->getUrl(); // The direct url
        $payload = $audio->getPayload(); // The original payload
    }
});

Listen for files

Just like images, you can use the receivesFiles method on the BotMan instance to listen for incoming file uploads. All received files will be passed to the callback as a second argument.

The files returned will be an array of BotMan\BotMan\Messages\Attachments\File objects.

use BotMan\BotMan\Messages\Attachments\File;

$bot->receivesFiles(function($bot, $files) {

    foreach ($files as $file) {

        $url = $file->getUrl(); // The direct url
        $payload = $file->getPayload(); // The original payload
    }
});

Listen for locations

Some messaging services also allow your bot users to send their GPS location to your bot. You can listen for these location calls using the receivesLocation method on the BotMan instance.

The method will pass a BotMan\BotMan\Messages\Attachments\Location object to the callback method.

use BotMan\BotMan\Messages\Attachments\Location;

$bot->receivesLocation(function($bot, Location $location) {
    $lat = $location->getLatitude();
    $lng = $location->getLongitude();
});

Supported Drivers

Not all drivers support receiving attachments, or because of the lack of reference API, or because it has not yet been implemented in the driver itself.

Can (Receive/Send)	Images	Videos	Audio	Files	Locations
Telegram	✔/✔	✔/✔	✔/✔	✔/✔	✔/✔
Facebook	✔/✔	✔/✔	✔/✔	✔/✔	✔/❌
Slack	✔/✔	✔/❌	✔/❌	✔/✔	❌/❌
Kik	✔/✔	✔/✔	❌/❌	❌/❌	❌/❌
WeChat	✔/✔	✔/❌	✔/❌	❌/❌	✔/❌
HipChat	❌/❌	❌/❌	❌/❌	❌/❌	❌/❌
Nexmo	❌/❌	❌/❌	❌/❌	❌/❌	❌/❌