Restructure omni services and add Chatwoot research snapshot

research/chatwoot/app/services/telegram/incoming_message_service.rb

@@ -0,0 +1,226 @@
+# Find the various telegram payload samples here: https://core.telegram.org/bots/webhooks#testing-your-bot-with-updates
+# https://core.telegram.org/bots/api#available-types
+
+class Telegram::IncomingMessageService
+  include ::FileTypeHelper
+  include ::Telegram::ParamHelpers
+  pattr_initialize [:inbox!, :params!]
+
+  def perform
+    # chatwoot doesn't support group conversations at the moment
+    transform_business_message!
+    return unless private_message?
+
+    set_contact
+    update_contact_avatar
+    set_conversation
+    # TODO: Since the recent Telegram Business update, we need to explicitly mark messages as read using an additional request.
+    # Otherwise, the client will see their messages as unread.
+    # Chatwoot defines a 'read' status in its enum but does not currently update this status for Telegram conversations.
+    # We have two options:
+    # 1. Send the read request to Telegram here, immediately when the message is created.
+    # 2. Properly update the read status in the Chatwoot UI and trigger the Telegram request when the agent actually reads the message.
+    # See: https://core.telegram.org/bots/api#readbusinessmessage
+    @message = @conversation.messages.build(
+      content: telegram_params_message_content,
+      account_id: @inbox.account_id,
+      inbox_id: @inbox.id,
+      message_type: message_type,
+      sender: message_sender,
+      content_attributes: telegram_params_content_attributes,
+      source_id: telegram_params_message_id.to_s
+    )
+
+    process_message_attachments if message_params?
+    @message.save!
+  end
+
+  private
+
+  def set_contact
+    contact_inbox = ::ContactInboxWithContactBuilder.new(
+      source_id: telegram_params_from_id,
+      inbox: inbox,
+      contact_attributes: contact_attributes
+    ).perform
+
+    # TODO: Should we update contact_attributes when the user changes their first or last name?
+    # In business chats, when our Telegram bot initiates the conversation,
+    # the message does not include a language code.
+    # This is critical for AI assistants and translation plugins.
+
+    @contact_inbox = contact_inbox
+    @contact = contact_inbox.contact
+  end
+
+  def process_message_attachments
+    attach_location
+    attach_files
+    attach_contact
+  end
+
+  def update_contact_avatar
+    return if @contact.avatar.attached?
+
+    avatar_url = inbox.channel.get_telegram_profile_image(telegram_params_from_id)
+    ::Avatar::AvatarFromUrlJob.perform_later(@contact, avatar_url) if avatar_url
+  end
+
+  def conversation_params
+    {
+      account_id: @inbox.account_id,
+      inbox_id: @inbox.id,
+      contact_id: @contact.id,
+      contact_inbox_id: @contact_inbox.id,
+      additional_attributes: conversation_additional_attributes
+    }
+  end
+
+  def set_conversation
+    # if lock to single conversation is disabled, we will create a new conversation if previous conversation is resolved
+    @conversation = if @inbox.lock_to_single_conversation
+                      @contact_inbox.conversations.last
+                    else
+                      @contact_inbox.conversations
+                                    .where.not(status: :resolved).last
+                    end
+    return if @conversation
+
+    @conversation = ::Conversation.create!(conversation_params)
+  end
+
+  def contact_attributes
+    {
+      name: "#{telegram_params_first_name} #{telegram_params_last_name}",
+      additional_attributes: additional_attributes
+    }
+  end
+
+  def additional_attributes
+    {
+      # TODO: Remove this once we show the social_telegram_user_name in the UI instead of the username
+      username: telegram_params_username,
+      language_code: telegram_params_language_code,
+      social_telegram_user_id: telegram_params_from_id,
+      social_telegram_user_name: telegram_params_username
+    }
+  end
+
+  def conversation_additional_attributes
+    {
+      chat_id: telegram_params_chat_id,
+      business_connection_id: telegram_params_business_connection_id
+    }
+  end
+
+  def message_type
+    business_message_outgoing? ? :outgoing : :incoming
+  end
+
+  def message_sender
+    business_message_outgoing? ? nil : @contact
+  end
+
+  def file_content_type
+    return :image if image_message?
+    return :audio if audio_message?
+    return :video if video_message?
+
+    file_type(params[:message][:document][:mime_type])
+  end
+
+  def image_message?
+    params[:message][:photo].present? || params.dig(:message, :sticker, :thumb).present?
+  end
+
+  def audio_message?
+    params[:message][:voice].present? || params[:message][:audio].present?
+  end
+
+  def video_message?
+    params[:message][:video].present? || params[:message][:video_note].present?
+  end
+
+  def attach_files
+    return unless file
+
+    file_download_path = inbox.channel.get_telegram_file_path(file[:file_id])
+    if file_download_path.blank?
+      Rails.logger.info "Telegram file download path is blank for #{file[:file_id]} : inbox_id: #{inbox.id}"
+      return
+    end
+
+    attachment_file = Down.download(
+      inbox.channel.get_telegram_file_path(file[:file_id])
+    )
+
+    @message.attachments.new(
+      account_id: @message.account_id,
+      file_type: file_content_type,
+      file: {
+        io: attachment_file,
+        filename: attachment_file.original_filename,
+        content_type: attachment_file.content_type
+      }
+    )
+  end
+
+  def attach_location
+    return unless location
+
+    @message.attachments.new(
+      account_id: @message.account_id,
+      file_type: :location,
+      fallback_title: location_fallback_title,
+      coordinates_lat: location['latitude'],
+      coordinates_long: location['longitude']
+    )
+  end
+
+  def attach_contact
+    return unless contact_card
+
+    @message.attachments.new(
+      account_id: @message.account_id,
+      file_type: :contact,
+      fallback_title: contact_card['phone_number'].to_s,
+      meta: {
+        first_name: contact_card['first_name'],
+        last_name: contact_card['last_name']
+      }
+    )
+  end
+
+  def file
+    @file ||= visual_media_params || params[:message][:voice].presence || params[:message][:audio].presence || params[:message][:document].presence
+  end
+
+  def location_fallback_title
+    return '' if venue.blank?
+
+    venue[:title] || ''
+  end
+
+  def venue
+    @venue ||= params.dig(:message, :venue).presence
+  end
+
+  def location
+    @location ||= params.dig(:message, :location).presence
+  end
+
+  def contact_card
+    @contact_card ||= params.dig(:message, :contact).presence
+  end
+
+  def visual_media_params
+    params[:message][:photo].presence&.last ||
+      params.dig(:message, :sticker, :thumb).presence ||
+      params[:message][:video].presence ||
+      params[:message][:video_note].presence
+  end
+
+  def transform_business_message!
+    params[:message] = params[:business_message] if params[:business_message] && !params[:message]
+  end
+end

research/chatwoot/app/services/telegram/param_helpers.rb

@@ -0,0 +1,104 @@
+module Telegram::ParamHelpers
+  # ensures that message is from a private chat and not a group chat
+  def private_message?
+    return true if callback_query_params?
+
+    params.dig(:message, :chat, :type) == 'private'
+  end
+
+  def telegram_params_content_attributes
+    reply_to = params.dig(:message, :reply_to_message, :message_id)
+    return { 'in_reply_to_external_id' => reply_to } if reply_to
+
+    {}
+  end
+
+  def business_message?
+    telegram_params_business_connection_id.present?
+  end
+
+  # In business bot mode we will receive messages from our telegram.
+  # This is our messages posted via telegram client.
+  # Such messages should be outgoing (from us to client)
+  def business_message_outgoing?
+    business_message? && telegram_params_base_object[:chat][:id] != telegram_params_base_object[:from][:id]
+  end
+
+  def message_params?
+    params[:message].present?
+  end
+
+  def callback_query_params?
+    params[:callback_query].present?
+  end
+
+  def telegram_params_base_object
+    if callback_query_params?
+      params[:callback_query]
+    else
+      params[:message]
+    end
+  end
+
+  def contact_params
+    if business_message_outgoing?
+      telegram_params_base_object[:chat]
+    else
+      telegram_params_base_object[:from]
+    end
+  end
+
+  def telegram_params_from_id
+    return telegram_params_base_object[:chat][:id] if business_message?
+
+    telegram_params_base_object[:from][:id]
+  end
+
+  def telegram_params_first_name
+    contact_params[:first_name]
+  end
+
+  def telegram_params_last_name
+    contact_params[:last_name]
+  end
+
+  def telegram_params_username
+    contact_params[:username]
+  end
+
+  def telegram_params_language_code
+    contact_params[:language_code]
+  end
+
+  def telegram_params_chat_id
+    if callback_query_params?
+      params[:callback_query][:message][:chat][:id]
+    else
+      telegram_params_base_object[:chat][:id]
+    end
+  end
+
+  def telegram_params_business_connection_id
+    if callback_query_params?
+      params[:callback_query][:message][:business_connection_id]
+    else
+      telegram_params_base_object[:business_connection_id]
+    end
+  end
+
+  def telegram_params_message_content
+    if callback_query_params?
+      params[:callback_query][:data]
+    else
+      params[:message][:text].presence || params[:message][:caption]
+    end
+  end
+
+  def telegram_params_message_id
+    if callback_query_params?
+      params[:callback_query][:id]
+    else
+      params[:message][:message_id]
+    end
+  end
+end

research/chatwoot/app/services/telegram/send_attachments_service.rb

@@ -0,0 +1,173 @@
+require 'faraday/multipart'
+
+# Telegram Attachment APIs: ref: https://core.telegram.org/bots/api#inputfile
+
+# Media attachments like photos, videos can be clubbed together and sent as a media group
+# Audio can be clubbed together and send as a media group, but can't be mixed with other types
+# Documents are sent individually
+
+# We are using `HTTP URL` to send media attachments, telegram will directly download the media from the URL and send it to the user.
+# But for documents, we need to send the file as a multipart request. as telegram only support pdf and zip for the download from the URL option.
+
+# ref: `In sendDocument, sending by URL will currently only work for GIF, PDF and ZIP files.`
+# ref: `https://core.telegram.org/bots/api#senddocument`
+# ref: `https://core.telegram.org/bots/api#sendmediaGroup
+
+# The service will terminate if any of the attachment requests fail when the message has multiple attachments
+# We will create multiple messages in telegram if the message has multiple attachments (if its documents or mixed media).
+class Telegram::SendAttachmentsService
+  pattr_initialize [:message!]
+
+  def perform
+    attachment_message_id = nil
+
+    group_attachments_by_type.each do |type, attachments|
+      attachment_message_id = process_attachments_by_type(type, attachments)
+      break if attachment_message_id.nil?
+    end
+
+    attachment_message_id
+  end
+
+  private
+
+  def process_attachments_by_type(type, attachments)
+    response = send_attachments(type, attachments)
+    return extract_attachment_message_id(response) if handle_response(response)
+
+    nil
+  end
+
+  def send_attachments(type, attachments)
+    if [:media, :audio].include?(type)
+      media_group_request(channel.chat_id(message), attachments, channel.reply_to_message_id(message))
+    else
+      send_individual_attachments(attachments)
+    end
+  end
+
+  def group_attachments_by_type
+    attachments_by_type = { media: [], audio: [], document: [] }
+
+    message.attachments.each do |attachment|
+      type = attachment_type(attachment[:file_type])
+      attachment_data = { type: type, media: attachment.download_url, attachment: attachment }
+      case type
+      when 'document'
+        attachments_by_type[:document] << attachment_data
+      when 'audio'
+        attachments_by_type[:audio] << attachment_data
+      when 'photo', 'video'
+        attachments_by_type[:media] << attachment_data
+      end
+    end
+
+    attachments_by_type.reject { |_, v| v.empty? }
+  end
+
+  def attachment_type(file_type)
+    { 'audio' => 'audio', 'image' => 'photo', 'file' => 'document', 'video' => 'video' }[file_type] || 'document'
+  end
+
+  def media_group_request(chat_id, attachments, reply_to_message_id)
+    HTTParty.post("#{channel.telegram_api_url}/sendMediaGroup",
+                  body: {
+                    chat_id: chat_id,
+                    **business_connection_body,
+                    media: attachments.map { |hash| hash.except(:attachment) }.to_json,
+                    reply_to_message_id: reply_to_message_id
+                  })
+  end
+
+  def send_individual_attachments(attachments)
+    response = nil
+    attachments.map do |attachment|
+      response = document_request(channel.chat_id(message), attachment, channel.reply_to_message_id(message))
+      break unless handle_response(response)
+    end
+    response
+  end
+
+  def document_request(chat_id, attachment, reply_to_message_id)
+    temp_file_path = save_attachment_to_tempfile(attachment[:attachment])
+    response = send_file(chat_id, temp_file_path, reply_to_message_id)
+    File.delete(temp_file_path)
+    response
+  end
+
+  # Telegram picks up the file name from original field name, so we need to save the file with the original name.
+  # Hence not using Tempfile here.
+  def save_attachment_to_tempfile(attachment)
+    temp_dir = Rails.root.join('tmp/uploads', "telegram-#{attachment.message_id}")
+    FileUtils.mkdir_p(temp_dir)
+    temp_file_path = File.join(temp_dir, attachment.file.filename.to_s)
+
+    File.open(temp_file_path, 'wb') do |file|
+      attachment.file.blob.open do |blob_file|
+        IO.copy_stream(blob_file, file)
+      end
+    end
+
+    temp_file_path
+  end
+
+  def send_file(chat_id, file_path, reply_to_message_id)
+    File.open(file_path, 'rb') do |file|
+      file_name = File.basename(file_path)
+      mime_type = Marcel::MimeType.for(name: file_name) || 'application/octet-stream'
+
+      payload = { chat_id: chat_id, document: Faraday::Multipart::FilePart.new(file, mime_type, file_name) }
+      payload[:reply_to_message_id] = reply_to_message_id if reply_to_message_id
+      payload.merge!(business_connection_body)
+
+      response = multipart_post_connection.post("#{channel.telegram_api_url}/sendDocument", payload)
+      parse_faraday_response(response)
+    end
+  end
+
+  def multipart_post_connection
+    @multipart_post_connection ||= Faraday.new do |f|
+      f.request :multipart
+      f.options.timeout = 300
+      f.options.open_timeout = 60
+    end
+  end
+
+  def parse_faraday_response(response)
+    parsed = JSON.parse(response.body)
+    OpenStruct.new(success?: response.success?, parsed_response: parsed)
+  rescue JSON::ParserError
+    OpenStruct.new(success?: false, parsed_response: { 'ok' => false, 'error_code' => response.status, 'description' => response.reason_phrase })
+  end
+
+  def handle_response(response)
+    return true if response.success?
+
+    Rails.logger.error "Message Id: #{message.id}  - Error sending attachment to telegram:  #{response.parsed_response}"
+    channel.process_error(message, response)
+    false
+  end
+
+  def extract_attachment_message_id(response)
+    return unless response.success?
+
+    result = response.parsed_response['result']
+    # response will be an array if the request for media group
+    # response will be a hash if the request for document
+    result.is_a?(Array) ? result.first['message_id'] : result['message_id']
+  end
+
+  def channel
+    @channel ||= message.inbox.channel
+  end
+
+  def business_connection_id
+    @business_connection_id ||= channel.business_connection_id(message)
+  end
+
+  def business_connection_body
+    body = {}
+    body[:business_connection_id] = business_connection_id if business_connection_id
+    body
+  end
+end

research/chatwoot/app/services/telegram/send_on_telegram_service.rb

@@ -0,0 +1,22 @@
+class Telegram::SendOnTelegramService < Base::SendOnChannelService
+  private
+
+  def channel_class
+    Channel::Telegram
+  end
+
+  def perform_reply
+    ## send reply to telegram message api
+    # https://core.telegram.org/bots/api#sendmessage
+    message_id = channel.send_message_on_telegram(message)
+    message.update!(source_id: message_id) if message_id.present?
+  end
+
+  def inbox
+    @inbox ||= message.inbox
+  end
+
+  def channel
+    @channel ||= inbox.channel
+  end
+end

research/chatwoot/app/services/telegram/update_message_service.rb

@@ -0,0 +1,44 @@
+# Find the various telegram payload samples here: https://core.telegram.org/bots/webhooks#testing-your-bot-with-updates
+# https://core.telegram.org/bots/api#available-types
+
+class Telegram::UpdateMessageService
+  pattr_initialize [:inbox!, :params!]
+
+  def perform
+    transform_business_message!
+    find_contact_inbox
+    find_conversation
+    find_message
+    update_message
+  rescue StandardError => e
+    Rails.logger.error "Error while processing telegram message update #{e.message}"
+  end
+
+  private
+
+  def find_contact_inbox
+    @contact_inbox = inbox.contact_inboxes.find_by!(source_id: params[:edited_message][:chat][:id])
+  end
+
+  def find_conversation
+    @conversation = @contact_inbox.conversations.last
+  end
+
+  def find_message
+    @message = @conversation.messages.find_by(source_id: params[:edited_message][:message_id])
+  end
+
+  def update_message
+    edited_message = params[:edited_message]
+
+    if edited_message[:text].present?
+      @message.update!(content: edited_message[:text])
+    elsif edited_message[:caption].present?
+      @message.update!(content: edited_message[:caption])
+    end
+  end
+
+  def transform_business_message!
+    params[:edited_message] = params[:edited_business_message] if params[:edited_business_message].present?
+  end
+end