feat: outbound voice call essentials (#12782)

- Enables outbound voice calls in voice channel . We are only caring
about wiring the logic to trigger outgoing calls to the call button
introduced in previous PRs. We will connect it to call component in
subsequent PRs

ref: #11602 

## Screens

<img width="2304" height="1202" alt="image"
src="https://github.com/user-attachments/assets/b91543a8-8d4e-4229-bd80-9727b42c7b0f"
/>

<img width="2304" height="1200" alt="image"
src="https://github.com/user-attachments/assets/1a1dad2a-8cb2-4aa2-9702-c062416556a7"
/>

---------

Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
Co-authored-by: iamsivin <iamsivin@gmail.com>
Co-authored-by: Vishnu Narayanan <vishnu@chatwoot.com>

enterprise/app/builders/enterprise/contact_inbox_builder.rb

@@ -0,0 +1,21 @@
+module Enterprise::ContactInboxBuilder
+  private
+
+  def generate_source_id
+    return super unless @inbox.channel_type == 'Channel::Voice'
+
+    phone_source_id
+  end
+
+  def phone_source_id
+    return super unless @inbox.channel_type == 'Channel::Voice'
+
+    return SecureRandom.uuid if @contact.phone_number.blank?
+
+    @contact.phone_number
+  end
+
+  def allowed_channels?
+    super || @inbox.channel_type == 'Channel::Voice'
+  end
+end

enterprise/app/builders/enterprise/messages/message_builder.rb

@@ -0,0 +1,9 @@
+module Enterprise::Messages::MessageBuilder
+  private
+
+  def message_type
+    return @message_type if @message_type == 'incoming' && @conversation.inbox.channel_type == 'Channel::Voice'
+
+    super
+  end
+end

enterprise/app/controllers/api/v1/accounts/contacts/calls_controller.rb

@@ -0,0 +1,38 @@
+class Api::V1::Accounts::Contacts::CallsController < Api::V1::Accounts::BaseController
+  before_action :contact
+  before_action :voice_inbox
+
+  def create
+    authorize contact, :show?
+    authorize voice_inbox, :show?
+
+    result = Voice::OutboundCallBuilder.perform!(
+      account: Current.account,
+      inbox: voice_inbox,
+      user: Current.user,
+      contact: contact
+    )
+
+    conversation = result[:conversation]
+
+    render json: {
+      conversation_id: conversation.display_id,
+      inbox_id: voice_inbox.id,
+      call_sid: result[:call_sid],
+      conference_sid: conversation.additional_attributes['conference_sid']
+    }
+  end
+
+  private
+
+  def contact
+    @contact ||= Current.account.contacts.find(params[:id])
+  end
+
+  def voice_inbox
+    @voice_inbox ||= Current.user.assigned_inboxes.where(
+      account_id: Current.account.id,
+      channel_type: 'Channel::Voice'
+    ).find(params.require(:inbox_id))
+  end
+end

enterprise/app/controllers/twilio/voice_controller.rb

@@ -1,38 +1,189 @@
 class Twilio::VoiceController < ApplicationController
+  CONFERENCE_EVENT_PATTERNS = {
+    /conference-start/i => 'start',
+    /participant-join/i => 'join',
+    /participant-leave/i => 'leave',
+    /conference-end/i => 'end'
+  }.freeze
+
   before_action :set_inbox!
 
   def status
     Voice::StatusUpdateService.new(
-      account: @inbox.account,
-      call_sid: params[:CallSid],
-      call_status: params[:CallStatus]
+      account: current_account,
+      call_sid: twilio_call_sid,
+      call_status: params[:CallStatus],
+      payload: params.to_unsafe_h
     ).perform
+
     head :no_content
   end
 
   def call_twiml
-    account = @inbox.account
-    call_sid = params[:CallSid]
-    from_number = params[:From].to_s
-    to_number = params[:To].to_s
+    account = current_account
+    Rails.logger.info(
+      "TWILIO_VOICE_TWIML account=#{account.id} call_sid=#{twilio_call_sid} from=#{twilio_from} direction=#{twilio_direction}"
+    )
 
-    builder = Voice::InboundCallBuilder.new(
-      account: account,
-      inbox: @inbox,
-      from_number: from_number,
-      to_number: to_number,
-      call_sid: call_sid
-    ).perform
-    render xml: builder.twiml_response
+    conversation = resolve_conversation
+    conference_sid = ensure_conference_sid!(conversation)
+
+    render xml: conference_twiml(conference_sid, agent_leg?(twilio_from))
+  end
+
+  def conference_status
+    event = mapped_conference_event
+    return head :no_content unless event
+
+    conversation = find_conversation_for_conference!(
+      friendly_name: params[:FriendlyName],
+      call_sid: twilio_call_sid
+    )
+
+    Voice::Conference::Manager.new(
+      conversation: conversation,
+      event: event,
+      call_sid: twilio_call_sid,
+      participant_label: participant_label
+    ).process
+
+    head :no_content
   end
 
   private
 
+  def twilio_call_sid
+    params[:CallSid]
+  end
+
+  def twilio_from
+    params[:From].to_s
+  end
+
+  def twilio_to
+    params[:To]
+  end
+
+  def twilio_direction
+    @twilio_direction ||= (params['Direction'] || params['CallDirection']).to_s
+  end
+
+  def mapped_conference_event
+    event = params[:StatusCallbackEvent].to_s
+    CONFERENCE_EVENT_PATTERNS.each do |pattern, mapped|
+      return mapped if event.match?(pattern)
+    end
+    nil
+  end
+
+  def agent_leg?(from_number)
+    from_number.start_with?('client:')
+  end
+
+  def resolve_conversation
+    return find_conversation_for_agent if agent_leg?(twilio_from)
+
+    case twilio_direction
+    when 'inbound'
+      Voice::InboundCallBuilder.perform!(
+        account: current_account,
+        inbox: inbox,
+        from_number: twilio_from,
+        call_sid: twilio_call_sid
+      )
+    when 'outbound-api', 'outbound-dial'
+      sync_outbound_leg(
+        call_sid: twilio_call_sid,
+        from_number: twilio_from,
+        direction: twilio_direction
+      )
+    else
+      raise ArgumentError, "Unsupported Twilio direction: #{twilio_direction}"
+    end
+  end
+
+  def find_conversation_for_agent
+    if params[:conversation_id].present?
+      current_account.conversations.find_by!(display_id: params[:conversation_id])
+    else
+      current_account.conversations.find_by!(identifier: twilio_call_sid)
+    end
+  end
+
+  def sync_outbound_leg(call_sid:, from_number:, direction:)
+    parent_sid = params['ParentCallSid'].presence
+    lookup_sid = direction == 'outbound-dial' ? parent_sid || call_sid : call_sid
+    conversation = current_account.conversations.find_by!(identifier: lookup_sid)
+
+    Voice::CallSessionSyncService.new(
+      conversation: conversation,
+      call_sid: call_sid,
+      message_call_sid: conversation.identifier,
+      leg: {
+        from_number: from_number,
+        to_number: twilio_to,
+        direction: 'outbound'
+      }
+    ).perform
+  end
+
+  def ensure_conference_sid!(conversation)
+    attrs = conversation.additional_attributes || {}
+    attrs['conference_sid'] ||= Voice::Conference::Name.for(conversation)
+    conversation.update!(additional_attributes: attrs)
+    attrs['conference_sid']
+  end
+
+  def conference_twiml(conference_sid, agent_leg)
+    Twilio::TwiML::VoiceResponse.new.tap do |response|
+      response.dial do |dial|
+        dial.conference(
+          conference_sid,
+          start_conference_on_enter: agent_leg,
+          end_conference_on_exit: false,
+          status_callback: conference_status_callback_url,
+          status_callback_event: 'start end join leave',
+          status_callback_method: 'POST',
+          participant_label: agent_leg ? 'agent' : 'contact'
+        )
+      end
+    end.to_s
+  end
+
+  def conference_status_callback_url
+    host = ENV.fetch('FRONTEND_URL', '')
+    phone_digits = inbox_channel.phone_number.delete_prefix('+')
+    "#{host}/twilio/voice/conference_status/#{phone_digits}"
+  end
+
+  def find_conversation_for_conference!(friendly_name:, call_sid:)
+    name = friendly_name.to_s
+    scope = current_account.conversations
+
+    if name.present?
+      conversation = scope.where("additional_attributes->>'conference_sid' = ?", name).first
+      return conversation if conversation
+    end
+
+    scope.find_by!(identifier: call_sid)
+  end
+
   def set_inbox!
-    # Resolve from the digits in the route param and look up exact E.164 match
     digits = params[:phone].to_s.gsub(/\D/, '')
     e164 = "+#{digits}"
     channel = Channel::Voice.find_by!(phone_number: e164)
     @inbox = channel.inbox
   end
+
+  def current_account
+    @current_account ||= inbox_account
+  end
+
+  def participant_label
+    params[:ParticipantLabel].to_s
+  end
+
+  attr_reader :inbox
+
+  delegate :account, :channel, to: :inbox, prefix: true
 end

enterprise/app/models/channel/voice.rb

@@ -42,6 +42,17 @@ class Channel::Voice < ApplicationRecord
     false
   end
 
+  def initiate_call(to:)
+    case provider
+    when 'twilio'
+      Voice::Provider::TwilioAdapter.new(self).initiate_call(
+        to: to
+      )
+    else
+      raise "Unsupported voice provider: #{provider}"
+    end
+  end
+
   # Public URLs used to configure Twilio webhooks
   def voice_call_webhook_url
     digits = phone_number.delete_prefix('+')
@@ -76,6 +87,15 @@ class Channel::Voice < ApplicationRecord
       errors.add(:provider_config, "#{key} is required for Twilio provider") if config[key].blank?
     end
   end
+  # twilio_client and initiate_twilio_call moved to Voice::Provider::TwilioAdapter
+
+  def provider_config_hash
+    if provider_config.is_a?(Hash)
+      provider_config
+    else
+      JSON.parse(provider_config.to_s)
+    end
+  end
 
   def provision_twilio_on_create
     service = ::Twilio::VoiceWebhookSetupService.new(channel: self)
@@ -96,4 +116,6 @@ class Channel::Voice < ApplicationRecord
     Rails.logger.error("TWILIO_VOICE_SETUP_ON_CREATE_ERROR: #{error_details}")
     errors.add(:base, "Twilio setup failed: #{e.message}")
   end
+
+  public :provider_config_hash
 end

enterprise/app/services/enterprise/contacts/contactable_inboxes_service.rb

@@ -0,0 +1,16 @@
+module Enterprise::Contacts::ContactableInboxesService
+  private
+
+  # Extend base selection to include Voice inboxes
+  def get_contactable_inbox(inbox)
+    return voice_contactable_inbox(inbox) if inbox.channel_type == 'Channel::Voice'
+
+    super
+  end
+
+  def voice_contactable_inbox(inbox)
+    return if @contact.phone_number.blank?
+
+    { source_id: @contact.phone_number, inbox: inbox }
+  end
+end

enterprise/app/services/voice/call_message_builder.rb

@@ -0,0 +1,90 @@
+class Voice::CallMessageBuilder
+  def self.perform!(conversation:, direction:, payload:, user: nil, timestamps: {})
+    new(
+      conversation: conversation,
+      direction: direction,
+      payload: payload,
+      user: user,
+      timestamps: timestamps
+    ).perform!
+  end
+
+  def initialize(conversation:, direction:, payload:, user:, timestamps:)
+    @conversation = conversation
+    @direction = direction
+    @payload = payload
+    @user = user
+    @timestamps = timestamps
+  end
+
+  def perform!
+    validate_sender!
+    message = latest_message
+    message ? update_message!(message) : create_message!
+  end
+
+  private
+
+  attr_reader :conversation, :direction, :payload, :user, :timestamps
+
+  def latest_message
+    conversation.messages.voice_calls.order(created_at: :desc).first
+  end
+
+  def update_message!(message)
+    message.update!(
+      message_type: message_type,
+      content_attributes: { 'data' => base_payload },
+      sender: sender
+    )
+  end
+
+  def create_message!
+    params = {
+      content: 'Voice Call',
+      message_type: message_type,
+      content_type: 'voice_call',
+      content_attributes: { 'data' => base_payload }
+    }
+    Messages::MessageBuilder.new(sender, conversation, params).perform
+  end
+
+  def base_payload
+    @base_payload ||= begin
+      data = payload.slice(
+        :call_sid,
+        :status,
+        :call_direction,
+        :conference_sid,
+        :from_number,
+        :to_number
+      ).stringify_keys
+      data['call_direction'] = direction
+      data['meta'] = {
+        'created_at' => timestamps[:created_at] || current_timestamp,
+        'ringing_at' => timestamps[:ringing_at] || current_timestamp
+      }.compact
+      data
+    end
+  end
+
+  def message_type
+    direction == 'outbound' ? 'outgoing' : 'incoming'
+  end
+
+  def sender
+    return user if direction == 'outbound'
+
+    conversation.contact
+  end
+
+  def validate_sender!
+    return unless direction == 'outbound'
+
+    raise ArgumentError, 'Agent sender required for outbound calls' unless user
+  end
+
+  def current_timestamp
+    @current_timestamp ||= Time.zone.now.to_i
+  end
+end

enterprise/app/services/voice/call_session_sync_service.rb

@@ -0,0 +1,94 @@
+class Voice::CallSessionSyncService
+  attr_reader :conversation, :call_sid, :message_call_sid, :from_number, :to_number, :direction
+
+  def initialize(conversation:, call_sid:, leg:, message_call_sid: nil)
+    @conversation = conversation
+    @call_sid = call_sid
+    @message_call_sid = message_call_sid || call_sid
+    @from_number = leg[:from_number]
+    @to_number = leg[:to_number]
+    @direction = leg[:direction]
+  end
+
+  def perform
+    ActiveRecord::Base.transaction do
+      attrs = refreshed_attributes
+      conversation.update!(
+        additional_attributes: attrs,
+        last_activity_at: current_time
+      )
+      sync_voice_call_message!(attrs)
+    end
+
+    conversation
+  end
+
+  private
+
+  def refreshed_attributes
+    attrs = (conversation.additional_attributes || {}).dup
+    attrs['call_direction'] = direction
+    attrs['call_status'] ||= 'ringing'
+    attrs['conference_sid'] ||= Voice::Conference::Name.for(conversation)
+    attrs['meta'] ||= {}
+    attrs['meta']['initiated_at'] ||= current_timestamp
+    attrs
+  end
+
+  def sync_voice_call_message!(attrs)
+    Voice::CallMessageBuilder.perform!(
+      conversation: conversation,
+      direction: direction,
+      payload: {
+        call_sid: message_call_sid,
+        status: attrs['call_status'],
+        conference_sid: attrs['conference_sid'],
+        from_number: origin_number_for(direction),
+        to_number: target_number_for(direction)
+      },
+      user: agent_for(attrs),
+      timestamps: {
+        created_at: attrs.dig('meta', 'initiated_at'),
+        ringing_at: attrs.dig('meta', 'ringing_at')
+      }
+    )
+  end
+
+  def origin_number_for(current_direction)
+    return outbound_origin if current_direction == 'outbound'
+
+    from_number.presence || inbox_number
+  end
+
+  def target_number_for(current_direction)
+    return conversation.contact&.phone_number || to_number if current_direction == 'outbound'
+
+    to_number || conversation.contact&.phone_number
+  end
+
+  def agent_for(attrs)
+    agent_id = attrs['agent_id']
+    return nil unless agent_id
+
+    agent = conversation.account.users.find_by(id: agent_id)
+    raise ArgumentError, 'Agent sender required for outbound call sync' if direction == 'outbound' && agent.nil?
+
+    agent
+  end
+
+  def current_timestamp
+    @current_timestamp ||= current_time.to_i
+  end
+
+  def current_time
+    @current_time ||= Time.zone.now
+  end
+
+  def outbound_origin
+    inbox_number || from_number
+  end
+
+  def inbox_number
+    conversation.inbox&.channel&.phone_number
+  end
+end

enterprise/app/services/voice/call_status/manager.rb

@@ -0,0 +1,66 @@
+class Voice::CallStatus::Manager
+  pattr_initialize [:conversation!, :call_sid]
+
+  ALLOWED_STATUSES = %w[ringing in-progress completed no-answer failed].freeze
+  TERMINAL_STATUSES = %w[completed no-answer failed].freeze
+
+  def process_status_update(status, duration: nil, timestamp: nil)
+    return unless ALLOWED_STATUSES.include?(status)
+
+    current_status = conversation.additional_attributes&.dig('call_status')
+    return if current_status == status
+
+    apply_status(status, duration: duration, timestamp: timestamp)
+    update_message(status)
+  end
+
+  private
+
+  def apply_status(status, duration:, timestamp:)
+    attrs = (conversation.additional_attributes || {}).dup
+    attrs['call_status'] = status
+
+    if status == 'in-progress'
+      attrs['call_started_at'] ||= timestamp || now_seconds
+    elsif TERMINAL_STATUSES.include?(status)
+      attrs['call_ended_at'] = timestamp || now_seconds
+      attrs['call_duration'] = resolved_duration(attrs, duration, timestamp)
+    end
+
+    conversation.update!(
+      additional_attributes: attrs,
+      last_activity_at: current_time
+    )
+  end
+
+  def resolved_duration(attrs, provided_duration, timestamp)
+    return provided_duration if provided_duration
+
+    started_at = attrs['call_started_at']
+    return unless started_at && timestamp
+
+    [timestamp - started_at.to_i, 0].max
+  end
+
+  def update_message(status)
+    message = conversation.messages
+                          .where(content_type: 'voice_call')
+                          .order(created_at: :desc)
+                          .first
+    return unless message
+
+    data = (message.content_attributes || {}).dup
+    data['data'] ||= {}
+    data['data']['status'] = status
+
+    message.update!(content_attributes: data)
+  end
+
+  def now_seconds
+    current_time.to_i
+  end
+
+  def current_time
+    @current_time ||= Time.zone.now
+  end
+end

enterprise/app/services/voice/conference/manager.rb

@@ -0,0 +1,71 @@
+class Voice::Conference::Manager
+  pattr_initialize [:conversation!, :event!, :call_sid!, :participant_label]
+
+  def process
+    case event
+    when 'start'
+      ensure_conference_sid!
+      mark_ringing!
+    when 'join'
+      mark_in_progress! if agent_participant?
+    when 'leave'
+      handle_leave!
+    when 'end'
+      finalize_conference!
+    end
+  end
+
+  private
+
+  def status_manager
+    @status_manager ||= Voice::CallStatus::Manager.new(
+      conversation: conversation,
+      call_sid: call_sid
+    )
+  end
+
+  def ensure_conference_sid!
+    attrs = conversation.additional_attributes || {}
+    return if attrs['conference_sid'].present?
+
+    attrs['conference_sid'] = Voice::Conference::Name.for(conversation)
+    conversation.update!(additional_attributes: attrs)
+  end
+
+  def mark_ringing!
+    return if current_status
+
+    status_manager.process_status_update('ringing')
+  end
+
+  def mark_in_progress!
+    status_manager.process_status_update('in-progress', timestamp: current_timestamp)
+  end
+
+  def handle_leave!
+    case current_status
+    when 'ringing'
+      status_manager.process_status_update('no-answer', timestamp: current_timestamp)
+    when 'in-progress'
+      status_manager.process_status_update('completed', timestamp: current_timestamp)
+    end
+  end
+
+  def finalize_conference!
+    return if %w[completed no-answer failed].include?(current_status)
+
+    status_manager.process_status_update('completed', timestamp: current_timestamp)
+  end
+
+  def current_status
+    conversation.additional_attributes&.dig('call_status')
+  end
+
+  def agent_participant?
+    participant_label.to_s.start_with?('agent')
+  end
+
+  def current_timestamp
+    Time.zone.now.to_i
+  end
+end

enterprise/app/services/voice/conference/name.rb

@@ -0,0 +1,5 @@
+module Voice::Conference::Name
+  def self.for(conversation)
+    "conf_account_#{conversation.account_id}_conv_#{conversation.display_id}"
+  end
+end

enterprise/app/services/voice/inbound_call_builder.rb

@@ -1,82 +1,99 @@
 class Voice::InboundCallBuilder
-  pattr_initialize [:account!, :inbox!, :from_number!, :to_number, :call_sid!]
+  attr_reader :account, :inbox, :from_number, :call_sid
 
-  attr_reader :conversation
-
-  def perform
-    contact = find_or_create_contact!
-    contact_inbox = find_or_create_contact_inbox!(contact)
-    @conversation = find_or_create_conversation!(contact, contact_inbox)
-    create_call_message_if_needed!
-    self
+  def self.perform!(account:, inbox:, from_number:, call_sid:)
+    new(account: account, inbox: inbox, from_number: from_number, call_sid: call_sid).perform!
   end
 
-  def twiml_response
-    response = Twilio::TwiML::VoiceResponse.new
-    response.say(message: 'Please wait while we connect you to an agent')
-    response.to_s
+  def initialize(account:, inbox:, from_number:, call_sid:)
+    @account = account
+    @inbox = inbox
+    @from_number = from_number
+    @call_sid = call_sid
+  end
+
+  def perform!
+    timestamp = current_timestamp
+
+    ActiveRecord::Base.transaction do
+      contact = ensure_contact!
+      contact_inbox = ensure_contact_inbox!(contact)
+      conversation = find_conversation || create_conversation!(contact, contact_inbox)
+      conversation.reload
+      update_conversation!(conversation, timestamp)
+      build_voice_message!(conversation, timestamp)
+      conversation
+    end
   end
 
   private
 
-  def find_or_create_conversation!(contact, contact_inbox)
-    account.conversations.find_or_create_by!(
-      account_id: account.id,
-      inbox_id: inbox.id,
-      identifier: call_sid
-    ) do |conv|
-      conv.contact_id = contact.id
-      conv.contact_inbox_id = contact_inbox.id
-      conv.additional_attributes = {
-        'call_direction' => 'inbound',
-        'call_status' => 'ringing'
-      }
+  def ensure_contact!
+    account.contacts.find_or_create_by!(phone_number: from_number) do |record|
+      record.name = from_number if record.name.blank?
     end
   end
 
-  def create_call_message!
-    content_attrs = call_message_content_attributes
+  def ensure_contact_inbox!(contact)
+    ContactInbox.find_or_create_by!(
+      contact_id: contact.id,
+      inbox_id: inbox.id
+    ) do |record|
+      record.source_id = from_number
+    end
+  end
 
-    @conversation.messages.create!(
-      account_id: account.id,
+  def find_conversation
+    return if call_sid.blank?
+
+    account.conversations.includes(:contact).find_by(identifier: call_sid)
+  end
+
+  def create_conversation!(contact, contact_inbox)
+    account.conversations.create!(
+      contact_inbox_id: contact_inbox.id,
       inbox_id: inbox.id,
-      message_type: :incoming,
-      sender: @conversation.contact,
-      content: 'Voice Call',
-      content_type: 'voice_call',
-      content_attributes: content_attrs
+      contact_id: contact.id,
+      status: :open,
+      identifier: call_sid
     )
   end
 
-  def create_call_message_if_needed!
-    return if @conversation.messages.voice_calls.exists?
+  def update_conversation!(conversation, timestamp)
+    attrs = {
+      'call_direction' => 'inbound',
+      'call_status' => 'ringing',
+      'conference_sid' => Voice::Conference::Name.for(conversation),
+      'meta' => { 'initiated_at' => timestamp }
+    }
 
-    create_call_message!
+    conversation.update!(
+      identifier: call_sid,
+      additional_attributes: attrs,
+      last_activity_at: current_time
+    )
   end
 
-  def call_message_content_attributes
-    {
-      data: {
+  def build_voice_message!(conversation, timestamp)
+    Voice::CallMessageBuilder.perform!(
+      conversation: conversation,
+      direction: 'inbound',
+      payload: {
         call_sid: call_sid,
         status: 'ringing',
-        conversation_id: @conversation.display_id,
-        call_direction: 'inbound',
+        conference_sid: conversation.additional_attributes['conference_sid'],
         from_number: from_number,
-        to_number: to_number,
-        meta: {
-          created_at: Time.current.to_i,
-          ringing_at: Time.current.to_i
-        }
-      }
-    }
+        to_number: inbox.channel&.phone_number
+      },
+      timestamps: { created_at: timestamp, ringing_at: timestamp }
+    )
   end
 
-  def find_or_create_contact!
-    account.contacts.find_by(phone_number: from_number) ||
-      account.contacts.create!(phone_number: from_number, name: 'Unknown Caller')
+  def current_timestamp
+    @current_timestamp ||= current_time.to_i
   end
 
-  def find_or_create_contact_inbox!(contact)
-    ContactInbox.where(contact_id: contact.id, inbox_id: inbox.id, source_id: from_number).first_or_create!
+  def current_time
+    @current_time ||= Time.zone.now
   end
 end

enterprise/app/services/voice/outbound_call_builder.rb

@@ -0,0 +1,98 @@
+class Voice::OutboundCallBuilder
+  attr_reader :account, :inbox, :user, :contact
+
+  def self.perform!(account:, inbox:, user:, contact:)
+    new(account: account, inbox: inbox, user: user, contact: contact).perform!
+  end
+
+  def initialize(account:, inbox:, user:, contact:)
+    @account = account
+    @inbox = inbox
+    @user = user
+    @contact = contact
+  end
+
+  def perform!
+    raise ArgumentError, 'Contact phone number required' if contact.phone_number.blank?
+    raise ArgumentError, 'Agent required' if user.blank?
+
+    timestamp = current_timestamp
+
+    ActiveRecord::Base.transaction do
+      contact_inbox = ensure_contact_inbox!
+      conversation = create_conversation!(contact_inbox)
+      conversation.reload
+      conference_sid = Voice::Conference::Name.for(conversation)
+      call_sid = initiate_call!
+      update_conversation!(conversation, call_sid, conference_sid, timestamp)
+      build_voice_message!(conversation, call_sid, conference_sid, timestamp)
+      { conversation: conversation, call_sid: call_sid }
+    end
+  end
+
+  private
+
+  def ensure_contact_inbox!
+    ContactInbox.find_or_create_by!(
+      contact_id: contact.id,
+      inbox_id: inbox.id
+    ) do |record|
+      record.source_id = contact.phone_number
+    end
+  end
+
+  def create_conversation!(contact_inbox)
+    account.conversations.create!(
+      contact_inbox_id: contact_inbox.id,
+      inbox_id: inbox.id,
+      contact_id: contact.id,
+      status: :open
+    )
+  end
+
+  def initiate_call!
+    inbox.channel.initiate_call(
+      to: contact.phone_number
+    )[:call_sid]
+  end
+
+  def update_conversation!(conversation, call_sid, conference_sid, timestamp)
+    attrs = {
+      'call_direction' => 'outbound',
+      'call_status' => 'ringing',
+      'agent_id' => user.id,
+      'conference_sid' => conference_sid,
+      'meta' => { 'initiated_at' => timestamp }
+    }
+
+    conversation.update!(
+      identifier: call_sid,
+      additional_attributes: attrs,
+      last_activity_at: current_time
+    )
+  end
+
+  def build_voice_message!(conversation, call_sid, conference_sid, timestamp)
+    Voice::CallMessageBuilder.perform!(
+      conversation: conversation,
+      direction: 'outbound',
+      payload: {
+        call_sid: call_sid,
+        status: 'ringing',
+        conference_sid: conference_sid,
+        from_number: inbox.channel&.phone_number,
+        to_number: contact.phone_number
+      },
+      user: user,
+      timestamps: { created_at: timestamp, ringing_at: timestamp }
+    )
+  end
+
+  def current_timestamp
+    @current_timestamp ||= current_time.to_i
+  end
+
+  def current_time
+    @current_time ||= Time.zone.now
+  end
+end

enterprise/app/services/voice/provider/twilio_adapter.rb

@@ -0,0 +1,32 @@
+class Voice::Provider::TwilioAdapter
+  def initialize(channel)
+    @channel = channel
+  end
+
+  def initiate_call(to:, _conference_sid: nil, _agent_id: nil)
+    cfg = @channel.provider_config_hash
+
+    host = ENV.fetch('FRONTEND_URL')
+    phone_digits = @channel.phone_number.delete_prefix('+')
+    callback_url = "#{host}/twilio/voice/call/#{phone_digits}"
+
+    params = {
+      from: @channel.phone_number,
+      to: to,
+      url: callback_url,
+      status_callback: "#{host}/twilio/voice/status/#{phone_digits}",
+      status_callback_event: %w[initiated ringing answered completed],
+      status_callback_method: 'POST'
+    }
+
+    call = twilio_client(cfg).calls.create(**params)
+
+    { call_sid: call.sid }
+  end
+
+  private
+
+  def twilio_client(config)
+    Twilio::REST::Client.new(config['account_sid'], config['auth_token'])
+  end
+end

enterprise/app/services/voice/status_update_service.rb

@@ -1,29 +1,60 @@
 class Voice::StatusUpdateService
-  pattr_initialize [:account!, :call_sid!, :call_status]
+  pattr_initialize [:account!, :call_sid!, :call_status, { payload: {} }]
+
+  TWILIO_STATUS_MAP = {
+    'queued' => 'ringing',
+    'initiated' => 'ringing',
+    'ringing' => 'ringing',
+    'in-progress' => 'in-progress',
+    'inprogress' => 'in-progress',
+    'answered' => 'in-progress',
+    'completed' => 'completed',
+    'busy' => 'no-answer',
+    'no-answer' => 'no-answer',
+    'failed' => 'failed',
+    'canceled' => 'failed'
+  }.freeze
 
   def perform
+    normalized_status = normalize_status(call_status)
+    return if normalized_status.blank?
+
     conversation = account.conversations.find_by(identifier: call_sid)
     return unless conversation
-    return if call_status.to_s.strip.empty?
 
-    update_conversation!(conversation)
-    update_last_call_message!(conversation)
+    Voice::CallStatus::Manager.new(
+      conversation: conversation,
+      call_sid: call_sid
+    ).process_status_update(
+      normalized_status,
+      duration: payload_duration,
+      timestamp: payload_timestamp
+    )
   end
 
   private
 
-  def update_conversation!(conversation)
-    attrs = (conversation.additional_attributes || {}).merge('call_status' => call_status)
-    conversation.update!(additional_attributes: attrs)
+  def normalize_status(status)
+    return if status.to_s.strip.empty?
+
+    TWILIO_STATUS_MAP[status.to_s.downcase]
   end
 
-  def update_last_call_message!(conversation)
-    msg = conversation.messages.voice_calls.order(created_at: :desc).first
-    return unless msg
+  def payload_duration
+    return unless payload.is_a?(Hash)
 
-    data = msg.content_attributes.is_a?(Hash) ? msg.content_attributes : {}
-    data['data'] ||= {}
-    data['data']['status'] = call_status
-    msg.update!(content_attributes: data)
+    duration = payload['CallDuration'] || payload['call_duration']
+    duration&.to_i
+  end
+
+  def payload_timestamp
+    return unless payload.is_a?(Hash)
+
+    ts = payload['Timestamp'] || payload['timestamp']
+    return unless ts
+
+    Time.zone.parse(ts).to_i
+  rescue ArgumentError
+    nil
   end
 end