WhatsApp Message Sending

Overview

This document provides technical documentation for the WhatsApp message sending functionality in the Whatsapp module. It describes the components, process flow, and implementation details for sending messages through the WhatsApp API.

The message sending process involves several components working together to build, prepare, and dispatch messages to recipients via the Evolution API or other potential message services in the future.

Technical Components

Models

• Instance: Represents a WhatsApp instance with connection status and configuration
• Contact: Represents a WhatsApp contact with phone number and other details

Enums

MessageType

namespace Modules\Whatsapp\Enums;

enum MessageType: string
{
    case TEXT     = 'text';
    case IMAGE    = 'image';
    case VIDEO    = 'video';
    case DOCUMENT = 'document';
    case AUDIO    = 'audio';

    // Helper methods to determine message type
    public function hasCaption(): bool;
    public function isAudio(): bool;
    public function isText(): bool;
    public function isMedia(): bool;
}

Support Classes

Message

namespace Modules\Whatsapp\Support;

// Class that represents a WhatsApp message
class Message
{
    // Constructor with message type, content, and optional extras
    public function __construct(
        public MessageType $type,
        public mixed $content,
        public array $extras = [],
    );

    // Creates the appropriate job based on message type
    public function makeJob(Contact $contact, ?Instance $instance = null): ?ShouldQueue;
}

Services

MessageService

namespace Modules\Whatsapp\Services;

// Service for preparing and dispatching WhatsApp messages
class MessageService
{
    // Dispatches messages asynchronously using queues
    public function dispatch(array $message, Contact $contact, ?Instance $instance = null): void;

    // Dispatches messages synchronously (immediate execution)
    public function dispatchSync(array $message, Contact $contact, ?Instance $instance = null): void;

    // Prepares message data into Message objects
    public function prepare(array $message): Collection;
}

Jobs

SendTextMessageJob

namespace Modules\Whatsapp\Jobs;

// Job for sending text messages
class SendTextMessageJob implements ShouldQueue
{
    // Constructor with message, contact, and optional instance
    public function __construct(
        public Message $message,
        public Contact $contact,
        public ?Instance $instance = null
    );

    // Handles the actual sending of the text message
    public function handle(): void;

    // Handles job failures
    public function failed(Throwable $exception): void;
}

SendMediaMessageJob

namespace Modules\Whatsapp\Jobs;

// Job for sending media messages (images, videos, documents, audio)
class SendMediaMessageJob implements ShouldQueue
{
    // Constructor with message, media object, contact, and optional instance
    public function __construct(
        public Message $message,
        public MediaObject $mediaObject,
        public Contact $contact,
        public ?Instance $instance = null
    );

    // Handles the actual sending of the media message
    public function handle(): void;

    // Handles job failures
    public function failed(Throwable $exception): void;
}

UI Components

MessageBuilder

namespace Modules\Whatsapp\Filament\Forms\Components;

// Filament form component for building WhatsApp messages
class MessageBuilder extends Builder
{
    // Returns the available message blocks (text, image, video, document, audio)
    public static function getMessageBlocks(): array;
}

Process Flow

1. Message Building

   • User builds a message using the MessageBuilder component in the UI
   • Message data is structured as an array with type and content information
   • Example structure:

     [
         [
             'type' => 'text',
             'data' => [
                 'text' => 'Hello, this is a text message'
             ]
         ],
         [
             'type' => 'image',
             'data' => [
                 'image' => 'path/to/image.jpg',
                 'caption' => 'Image caption'
             ]
         ]
     ]

2. Message Preparation

   • MessageService::prepare() converts the array data into Message objects
   • Each message item is processed to extract type, content, and extras
   • A collection of Message objects is returned

3. Message Dispatching

   • Asynchronous (dispatch): Messages are sent to queue for background processing
     • MessageService::dispatch() creates jobs for each message
     • Jobs are chained and dispatched to the configured queue
   • Synchronous (dispatchSync): Messages are processed immediately
     • MessageService::dispatchSync() executes each message job directly
     • Useful for immediate feedback or testing

4. Job Processing

   • Each Message object creates the appropriate job via makeJob()
   • For text messages, SendTextMessageJob is created
   • For media messages, SendMediaMessageJob is created with a MediaObject

5. Message Sending

   • Jobs handle the actual sending of messages through the Evolution API
   • The job checks if the instance exists and is in the CONNECTED status
   • The Evolution facade is used to send the message to the recipient
   • Error handling is implemented for failed sends

Technical Implementation Notes

Message Structure

The message array structure follows a consistent pattern:

[
    [
        'type' => 'message_type', // One of the MessageType enum values
        'data' => [
            'message_type' => 'content', // Content specific to the message type
            'additional_field' => 'value' // Optional additional fields
        ]
    ],
    // Additional message items...
]

Media Handling

For media messages:

• Files are stored in the configured filesystem disk
• Files are converted to base64 for sending via the Evolution API
• Media messages can include captions for images and videos

Queue Configuration

Messages are dispatched to the queue configured in config('whatsapp.queue', 'default').

Error Handling

• Jobs implement error handling for failed sends
• Errors are logged with contact and instance information
• Failed jobs can be retried based on Laravel's queue configuration

Usage Examples

Sending a Text Message

use Modules\Whatsapp\Facades\Message;
use Modules\Whatsapp\Models\Contact;

$contact = Contact::find($contactId);

$message = [
    [
        'type' => 'text',
        'data' => [
            'text' => 'Hello, this is a test message'
        ]
    ]
];

// Asynchronous (queued)
Message::dispatch($message, $contact);

// Synchronous (immediate)
Message::dispatchSync($message, $contact);

Sending Multiple Message Types

$message = [
    [
        'type' => 'text',
        'data' => [
            'text' => 'Please see the attached image:'
        ]
    ],
    [
        'type' => 'image',
        'data' => [
            'image' => 'uploads/image.jpg',
            'caption' => 'Product image'
        ]
    ]
];

Message::dispatch($message, $contact);

Sending to a Specific Instance

use Modules\Whatsapp\Models\Instance;

$instance = Instance::find($instanceId);
$contact = Contact::find($contactId);

$message = [
    [
        'type' => 'text',
        'data' => [
            'text' => 'Hello from a specific instance'
        ]
    ]
];

Message::dispatch($message, $contact, $instance);