feat(voice): bridge WhatsApp Cloud Calling to Chatwoot voice pipeline [4] (#14356)

# Pull Request Template

## Description

Bridges WhatsApp Cloud Calling onto Chatwoot's voice pipeline so agents
can answer and place calls on WhatsApp Cloud inboxes with the same UX as
Twilio voice. Browser ↔ Meta WebRTC is direct (no media-server hop);
Chatwoot owns signalling, recording upload, and `Call`/`Message`
lifecycle state.

Companion PRs:
- FE: #14346 (`feat/whatsapp-call-ui`) — UI consumer for these
endpoints.
- Specs: #14357 (`feat/whatsapp-call-meta-bridge-specs`) — backend test
coverage.

## Type of change

- [x] New feature (non-breaking change which adds functionality)

## What changed

- **API** — new `Api::V1::Accounts::WhatsappCallsController` with `show
/ accept / reject / terminate / initiate / upload_recording`.
Conversation-level Pundit auth. `initiate` is gated on the channel being
embedded-signup voice-enabled. Permission-blocked initiations (Meta
error 138006) return **422** with `{ status: 'permission_requested' |
'permission_pending' }` and trigger a throttled opt-in template send
under a conversation lock.
- **State machine** — `Whatsapp::CallService` handles accept / reject /
terminate with call-level locking. Meta failures are wrapped as
`Voice::CallErrors::CallFailed` so the controller renders 422 instead of
leaking 500s.
- **Webhooks** — `Whatsapp::IncomingCallService` processes Meta
connect/terminate events. Pins `setup:active` on outbound answers,
materialises a missed-call record when terminate arrives before connect
(out-of-order delivery), and broadcasts `voice_call.*` events to the
assignee's pubsub stream when assigned, otherwise account-wide.
- **Provider** — `Whatsapp::Providers::WhatsappCloudService` adds
`pre_accept_call / accept_call / reject_call / terminate_call /
initiate_call / send_call_permission_request`. Uses configurable
`WHATSAPP_API_VERSION` (default v22) since Calls API needs v17+ and the
OSS `phone_id_path` is locked at v13 for legacy `/messages`
compatibility.
- **Audio recordings** — `Attachment after_create_commit` enqueues
transcription and rebroadcasts the message so the FE bubble updates
immediately. Active Storage initializer allows audio MIME types to serve
inline.

## How to test

1. Set up a WhatsApp Cloud Embedded Signup inbox; flip
`provider_config.calling_enabled = true` (Calls tab in inbox settings —
ships with FE PR #14346).
2. Place a real call from a phone number that has previously messaged
the business → expect `voice_call.incoming` cable + `Call` row +
`voice_call` Message bubble.
3. Click Accept (FE PR) → `/whatsapp_calls/:id/accept` 200, audio flows
browser ↔ Meta, recording uploads on hangup, Whisper transcript appears
within ~10s.
4. From Chatwoot, click outbound → `/whatsapp_calls/initiate` 200 if the
contact is opted-in, otherwise **422** with `status:
'permission_requested'` and a template send (FE shows a banner instead
of an error toast).
5. Refresh during a ringing call → call survives on Meta, FE seeds it
back from the conversation cache, agent can still accept.
6. Refresh during an active call → `pagehide` beacon terminates the call
on Meta with `status: 'completed'` (no orphan).

## Checklist

- [x] Code follows project style (RuboCop / ESLint clean)
- [x] Self-review done
- [x] Hard-to-understand areas commented
- [ ] Documentation update (architecture doc lives in companion branch)
- [x] No new warnings
- [x] Tests live in companion PR #14357
- [x] Existing tests pass locally
- [x] Dependent changes merged downstream (FE #14346 consumes these
endpoints)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/builders/messages/messenger/message_builder.rb

@@ -28,6 +28,10 @@ class Messages::Messenger::MessageBuilder
       filename: attachment_file.original_filename,
       content_type: attachment_file.content_type
     )
+    # The Attachment row is saved before the blob is attached, so the
+    # after_create_commit broadcast bails on `file.attached?`. Re-fire here
+    # for audio so the bubble updates without waiting on transcription.
+    attachment.message&.reload&.send_update_event if attachment.file_type.to_sym == :audio
   end
 
   def attachment_params(attachment)

app/models/attachment.rb

@@ -104,11 +104,23 @@ class Attachment < ApplicationRecord
     audio_file_data = base_data.merge(file_metadata)
     audio_file_data.merge(
       {
+        # ActiveStorage's redirect endpoint defaults to Content-Disposition: attachment,
+        # which makes <audio> elements download instead of play. Force inline so the
+        # call-recording chip (and any other audio bubble) can stream directly.
+        data_url: inline_audio_url,
         transcribed_text: meta&.[]('transcribed_text') || ''
       }
     )
   end
 
+  def inline_audio_url
+    return '' unless file.attached?
+
+    # Proxy endpoint streams through Rails and honours `disposition: 'inline'`,
+    # unlike the redirect endpoint which always sends Content-Disposition: attachment.
+    Rails.application.routes.url_helpers.rails_storage_proxy_url(file, disposition: 'inline')
+  end
+
   def file_metadata
     metadata = {
       extension: extension,

app/models/channel/whatsapp.rb

@@ -41,8 +41,13 @@ class Channel::Whatsapp < ApplicationRecord
   end
 
   # Mirrors Channel::TwilioSms#voice_enabled? so the call subsystem can duck-type across providers.
+  # Meta's Calling API is only available via the embedded-signup whatsapp_cloud flow —
+  # 360dialog (default provider) and manual whatsapp_cloud setups can't reach the call APIs.
   def voice_enabled?
-    provider_config['calling_enabled'].present?
+    provider == 'whatsapp_cloud' &&
+      provider_config['source'] == 'embedded_signup' &&
+      provider_config['calling_enabled'].present? &&
+      account.feature_enabled?('channel_voice')
   end
 
   def provider_service

app/services/base/send_on_channel_service.rb

@@ -46,7 +46,8 @@ class Base::SendOnChannelService
   def invalid_message?
     # private notes aren't send to the channels
     # we should also avoid the case of message loops, when outgoing messages are created from channel
-    message.private? || outgoing_message_originated_from_channel?
+    # voice_call bubbles are call status indicators, not deliverable messages
+    message.private? || outgoing_message_originated_from_channel? || message.content_type == 'voice_call'
   end
 
   def validate_target_channel

app/services/whatsapp/facebook_api_client.rb

@@ -86,7 +86,7 @@ class Whatsapp::FacebookApiClient
       body: {
         override_callback_uri: callback_url,
         verify_token: verify_token,
-        subscribed_fields: %w[messages smb_message_echoes]
+        subscribed_fields: %w[messages smb_message_echoes calls]
       }.to_json
     )
 

app/views/api/v1/models/_inbox.json.jbuilder

@@ -142,3 +142,6 @@ if resource.twilio? && resource.channel.respond_to?(:voice_enabled?)
     json.voice_status_webhook_url resource.channel.try(:voice_status_webhook_url)
   end
 end
+
+## Voice attribute for WhatsApp Cloud (only embedded-signup channels surface true)
+json.voice_enabled resource.channel.voice_enabled? if resource.channel_type == 'Channel::Whatsapp' && resource.channel.respond_to?(:voice_enabled?)

config/initializers/active_storage.rb

@@ -0,0 +1,13 @@
+# Allow audio attachments (call recordings, voice notes) to serve inline so the
+# in-app <audio> player can stream them. Without this, ActiveStorage's blob model
+# forces Content-Disposition: attachment for any MIME outside the default allowlist
+# (images + PDF), which makes the browser download instead of play.
+Rails.application.config.active_storage.content_types_allowed_inline += %w[
+  audio/webm
+  audio/ogg
+  audio/mpeg
+  audio/mp4
+  audio/x-m4a
+  audio/wav
+  audio/x-wav
+]

config/locales/en.yml

@@ -116,6 +116,13 @@ en:
       reauthorization:
         generic: 'Failed to reauthorize WhatsApp. Please try again.'
         not_supported: 'Reauthorization is not supported for this type of WhatsApp channel.'
+      calls:
+        not_enabled: 'Calling is not enabled for this inbox'
+        no_recording: 'No recording file provided'
+        no_message: 'Call has no associated message'
+        sdp_offer_required: 'sdp_offer is required'
+        contact_phone_required: 'Contact phone number is required'
+        permission_request_failed: 'Failed to send call permission request'
     inboxes:
       imap:
         socket_error: Please check the network connection, IMAP address and try again.
@@ -293,6 +300,9 @@ en:
         issue_created: 'Linear issue %{issue_id} was created by %{user_name}'
         issue_linked: 'Linear issue %{issue_id} was linked by %{user_name}'
         issue_unlinked: 'Linear issue %{issue_id} was unlinked by %{user_name}'
+      whatsapp_call:
+        permission_requested: 'Sent a call permission request to %{contact_name}.'
+        permission_granted: '%{contact_name} accepted the call permission request.'
       csat:
         not_sent_due_to_messaging_window: 'CSAT survey not sent due to outgoing message restrictions'
       auto_resolve:

config/routes.rb

@@ -226,6 +226,21 @@ Rails.application.routes.draw do
             end
           end
           resources :reporting_events, only: [:index] if ChatwootApp.enterprise?
+
+          if ChatwootApp.enterprise?
+            resources :whatsapp_calls, only: [:show] do
+              member do
+                post :accept
+                post :reject
+                post :terminate
+                post :upload_recording
+              end
+              collection do
+                post :initiate
+              end
+            end
+          end
+
           resources :custom_attribute_definitions, only: [:index, :show, :create, :update, :destroy]
           resources :custom_filters, only: [:index, :show, :create, :update, :destroy]
           resources :inboxes, only: [:index, :show, :create, :update, :destroy] do

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

@@ -10,7 +10,8 @@ class Api::V1::Accounts::Contacts::CallsController < Api::V1::Accounts::BaseCont
       account: Current.account,
       inbox: voice_inbox,
       user: Current.user,
-      contact: contact
+      contact: contact,
+      conversation: existing_conversation
     )
 
     render json: {
@@ -38,4 +39,16 @@ class Api::V1::Accounts::Contacts::CallsController < Api::V1::Accounts::BaseCont
       inbox
     end
   end
+
+  # Reuse the open conversation when the caller is already inside it; ignore
+  # the hint if it doesn't belong to the picked voice inbox or dialed contact.
+  def existing_conversation
+    return nil if params[:conversation_id].blank?
+
+    conversation = Current.account.conversations.find_by(display_id: params[:conversation_id])
+    return nil unless conversation
+    return nil unless conversation.inbox_id == voice_inbox.id && conversation.contact_id == contact.id
+
+    conversation
+  end
 end

enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb

@@ -0,0 +1,187 @@
+class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseController
+  PERMISSION_REQUEST_THROTTLE = 5.minutes
+
+  before_action :set_call, only: %i[show accept reject terminate upload_recording]
+  before_action :set_conversation, only: :initiate
+  before_action :ensure_calling_enabled, only: :initiate
+  before_action :ensure_sdp_offer, only: :initiate
+  before_action :ensure_contact_phone, only: :initiate
+  before_action :ensure_recording_present, only: :upload_recording
+  before_action :ensure_call_message, only: :upload_recording
+
+  rescue_from Voice::CallErrors::NotRinging,
+              Voice::CallErrors::AlreadyAccepted,
+              Voice::CallErrors::CallFailed,
+              with: :render_call_error
+  rescue_from Voice::CallErrors::NoCallPermission, with: :render_permission_request
+
+  def show; end
+
+  def accept
+    call_service.accept
+  end
+
+  def reject
+    call_service.reject
+  end
+
+  def terminate
+    call_service.terminate
+  end
+
+  def upload_recording
+    @upload_status = @call.message.with_lock { attach_recording_idempotently }
+  end
+
+  def initiate
+    @call = create_outbound_call
+    @message = Voice::CallMessageBuilder.new(@call).perform!
+    @call.update!(message_id: @message.id)
+  end
+
+  private
+
+  def call_service
+    @call_service ||= Whatsapp::CallService.new(call: @call, agent: Current.user, sdp_answer: params[:sdp_answer])
+  end
+
+  def provider_service
+    @provider_service ||= @conversation.inbox.channel.provider_service
+  end
+
+  def set_call
+    @call = Current.account.calls.whatsapp.find(params[:id])
+    authorize @call.conversation, :show?
+  end
+
+  def set_conversation
+    @conversation = Current.account.conversations.find_by!(display_id: params[:conversation_id])
+    authorize @conversation, :show?
+  end
+
+  def ensure_calling_enabled
+    channel = @conversation.inbox.channel
+    return if channel.is_a?(Channel::Whatsapp) && channel.voice_enabled?
+
+    render_could_not_create_error(I18n.t('errors.whatsapp.calls.not_enabled'))
+  end
+
+  def ensure_sdp_offer
+    return if params[:sdp_offer].present?
+
+    render_could_not_create_error(I18n.t('errors.whatsapp.calls.sdp_offer_required'))
+  end
+
+  def ensure_contact_phone
+    return if @conversation.contact&.phone_number.present?
+
+    render_could_not_create_error(I18n.t('errors.whatsapp.calls.contact_phone_required'))
+  end
+
+  def ensure_recording_present
+    return if params[:recording].present?
+
+    render_could_not_create_error(I18n.t('errors.whatsapp.calls.no_recording'))
+  end
+
+  def ensure_call_message
+    return if @call.message.present?
+
+    render_could_not_create_error(I18n.t('errors.whatsapp.calls.no_message'))
+  end
+
+  def attach_recording_idempotently
+    return 'already_uploaded' if @call.message.attachments.exists?(file_type: :audio)
+
+    @call.message.attachments.create!(account_id: @call.account_id, file_type: :audio, file: params[:recording])
+    'uploaded'
+  end
+
+  def create_outbound_call
+    contact_phone = @conversation.contact.phone_number.delete('+')
+    result = provider_service.initiate_call(contact_phone, params[:sdp_offer])
+    provider_call_id = result.dig('calls', 0, 'id') || result['call_id']
+
+    Current.account.calls.create!(
+      provider: :whatsapp, inbox: @conversation.inbox, conversation: @conversation, contact: @conversation.contact,
+      provider_call_id: provider_call_id, direction: :outgoing, status: 'ringing',
+      accepted_by_agent_id: Current.user.id,
+      meta: { 'sdp_offer' => params[:sdp_offer], 'ice_servers' => Call.default_ice_servers }
+    )
+  end
+
+  # Meta error 138006 means the contact hasn't opted in yet; send the opt-in
+  # template (throttled, behind a conversation lock to prevent double-send).
+  def render_permission_request
+    status = nil
+    @conversation.with_lock do
+      if permission_request_throttled?
+        status = 'permission_pending'
+        next
+      end
+
+      sent = send_permission_request_safely
+      if sent
+        record_permission_request_wamid(sent)
+        emit_permission_requested_activity
+        status = 'permission_requested'
+      else
+        status = 'failed'
+      end
+    end
+
+    return render_could_not_create_error(I18n.t('errors.whatsapp.calls.permission_request_failed')) if status == 'failed'
+
+    # 422 (not 200) so any client treating 2xx as "call placed" can't mistake
+    # the permission-template path for a successful dial. The FE composable
+    # detects this status and surfaces the banner instead of throwing.
+    render json: { status: status }, status: :unprocessable_entity
+  end
+
+  def permission_request_throttled?
+    last_requested = @conversation.additional_attributes&.dig('call_permission_requested_at')
+    last_requested.present? && Time.zone.parse(last_requested) > PERMISSION_REQUEST_THROTTLE.ago
+  end
+
+  # Treat transport errors as a falsy return so we render 422 rather than 500.
+  def send_permission_request_safely
+    provider_service.send_call_permission_request(
+      @conversation.contact.phone_number.delete('+'),
+      *permission_request_body_args
+    )
+  rescue StandardError => e
+    Rails.logger.warn "[WHATSAPP CALL] permission_request failed: #{e.class} #{e.message}"
+    nil
+  end
+
+  # Pass the inbox-level override only when present so the provider falls back
+  # to the i18n default for inboxes that haven't customized the prompt.
+  def permission_request_body_args
+    custom_body = @conversation.inbox.channel.provider_config&.dig('call_permission_request_body').presence
+    custom_body ? [custom_body] : []
+  end
+
+  def emit_permission_requested_activity
+    content = I18n.t(
+      'conversations.activity.whatsapp_call.permission_requested',
+      contact_name: @conversation.contact.name
+    )
+    ::Conversations::ActivityMessageJob.perform_later(
+      @conversation,
+      { account_id: @conversation.account_id, inbox_id: @conversation.inbox_id, message_type: :activity, content: content }
+    )
+  end
+
+  # Stash the outbound wamid so the reply webhook can match context.id back here.
+  def record_permission_request_wamid(sent)
+    attrs = (@conversation.additional_attributes || {}).merge(
+      'call_permission_requested_at' => Time.current.iso8601,
+      'call_permission_request_message_id' => sent.dig('messages', 0, 'id')
+    )
+    @conversation.update!(additional_attributes: attrs)
+  end
+
+  def render_call_error(error)
+    render_could_not_create_error(error.message)
+  end
+end

enterprise/app/jobs/enterprise/webhooks/whatsapp_events_job.rb

@@ -23,16 +23,34 @@ module Enterprise::Webhooks::WhatsappEventsJob
     params.dig(:entry, 0, :changes, 0, :value, :messages, 0, :interactive, :type) == 'call_permission_reply'
   end
 
-  # Per-call_id mutex so connect/terminate for the same call serialize across batches.
+  # Per-call_id mutex so connect/status/terminate for the same call serialize
+  # across batches. Meta delivers two payload shapes under field=calls:
+  #   - value.calls[]    → event-based (connect, terminate)
+  #   - value.statuses[] → status-based (RINGING, ACCEPTED) — the real pickup
+  #     signal for outbound; without this, only `connect` (tunnel-up) is seen
+  #     and timer/recorder kick off before the contact actually answers.
   def handle_call_events(channel, params)
-    calls = params.dig(:entry, 0, :changes, 0, :value, :calls) || []
-    calls.each do |call_payload|
-      lock_key = format(::Redis::Alfred::WHATSAPP_MESSAGE_MUTEX,
-                        inbox_id: channel.inbox.id, sender_id: "call:#{call_payload[:id]}")
-      with_lock(lock_key, 30.seconds) do
+    value = params.dig(:entry, 0, :changes, 0, :value) || {}
+
+    Array(value[:calls]).each do |call_payload|
+      with_call_lock(channel, call_payload[:id]) do
         Whatsapp::IncomingCallService.new(inbox: channel.inbox, params: { calls: [call_payload] }).perform
       end
     end
+
+    Array(value[:statuses]).each do |status_payload|
+      next unless status_payload[:type] == 'call'
+
+      with_call_lock(channel, status_payload[:id]) do
+        Whatsapp::IncomingCallService.new(inbox: channel.inbox, params: { statuses: [status_payload] }).perform
+      end
+    end
+  end
+
+  def with_call_lock(channel, call_id, &)
+    lock_key = format(::Redis::Alfred::WHATSAPP_MESSAGE_MUTEX,
+                      inbox_id: channel.inbox.id, sender_id: "call:#{call_id}")
+    with_lock(lock_key, 30.seconds, &)
   end
 
   def handle_call_permission_reply(channel, params)

enterprise/app/models/call.rb

@@ -29,9 +29,7 @@
 #  index_calls_on_provider_and_provider_call_id   (provider,provider_call_id) UNIQUE
 #
 class Call < ApplicationRecord
-  # All valid call statuses
   STATUSES = %w[ringing in_progress completed no_answer failed].freeze
-  # Statuses where the call is finished and won't change again
   TERMINAL_STATUSES = %w[completed no_answer failed].freeze
 
   store_accessor :meta, :conference_sid, :twilio_conference_sid, :recording_sid, :parent_call_sid, :initiated_at, :ended_at

enterprise/app/models/enterprise/concerns/attachment.rb

@@ -3,6 +3,11 @@ module Enterprise::Concerns::Attachment
 
   included do
     after_create_commit :enqueue_audio_transcription
+    # Broadcast the message update so the FE bubble picks up the new audio
+    # attachment immediately. Without this, the FE has to wait until Whisper
+    # finishes (or fall back to a page refresh) — and if Whisper returns blank,
+    # the bubble never gets the audio at all.
+    after_create_commit :broadcast_message_update_for_audio
   end
 
   private
@@ -10,6 +15,20 @@ module Enterprise::Concerns::Attachment
   def enqueue_audio_transcription
     return unless file_type.to_sym == :audio
 
+    # No file.attached? guard: the social-media ingest path saves the
+    # Attachment before attaching the blob. AudioTranscriptionJob retries
+    # on ActiveStorage::FileNotFoundError to ride out that race.
     Messages::AudioTranscriptionJob.perform_later(id)
   end
+
+  def broadcast_message_update_for_audio
+    return unless file_type.to_sym == :audio
+    return unless message
+    # Without an attached file, the message serializer's audio_metadata path
+    # dereferences `file.metadata[:width]` on nil and raises. The pre-attach
+    # broadcast wouldn't carry useful audio info anyway — skip until upload completes.
+    return unless file.attached?
+
+    message.reload.send_update_event
+  end
 end

enterprise/app/models/enterprise/conversation.rb

@@ -13,6 +13,12 @@ module Enterprise::Conversation
     super + %w[sla_policy_id]
   end
 
+  # Surface call lifecycle changes to the FE: writes to additional_attributes
+  # call_status/call_direction should rebroadcast conversation_updated.
+  def allowed_keys?
+    super || call_attributes_changed?
+  end
+
   def with_captain_activity_context(reason:, reason_type:)
     previous_reason = captain_activity_reason
     previous_reason_type = captain_activity_reason_type
@@ -30,4 +36,13 @@ module Enterprise::Conversation
   def dispatch_captain_inference_event(event_name)
     dispatcher_dispatch(event_name)
   end
+
+  def call_attributes_changed?
+    return false if previous_changes['additional_attributes'].blank?
+
+    # Compare before/after values for call keys — checking key presence alone
+    # rebroadcasts on any unrelated additional_attributes write once the keys exist.
+    before, after = previous_changes['additional_attributes']
+    %w[call_status call_direction].any? { |key| (before || {})[key] != (after || {})[key] }
+  end
 end

enterprise/app/services/enterprise/whatsapp/providers/whatsapp_cloud_service.rb

@@ -1,4 +1,9 @@
 module Enterprise::Whatsapp::Providers::WhatsappCloudService
+  # Calls API + the call_permission_request interactive message both require Graph
+  # API v17+; OSS phone_id_path is locked at v13.0 for legacy /messages compatibility.
+  # Use the configured global version (defaulting to v22.0) for call-flow endpoints.
+  WHATSAPP_CALLING_API_VERSION_FALLBACK = 'v22.0'.freeze
+
   def pre_accept_call(call_id, sdp_answer)
     call_api('pre_accept_call', call_action_body(call_id, 'pre_accept', sdp_answer))
   end
@@ -17,7 +22,7 @@ module Enterprise::Whatsapp::Providers::WhatsappCloudService
 
   def send_call_permission_request(to_phone_number, body_text = I18n.t('conversations.messages.whatsapp.call_permission_request_body'))
     response = HTTParty.post(
-      "#{phone_id_path}/messages", headers: api_headers, body: permission_request_body(to_phone_number, body_text)
+      "#{calls_phone_id_path}/messages", headers: api_headers, body: permission_request_body(to_phone_number, body_text)
     )
 
     unless response.success?
@@ -30,13 +35,19 @@ module Enterprise::Whatsapp::Providers::WhatsappCloudService
 
   def initiate_call(to_phone_number, sdp_offer)
     response = HTTParty.post(
-      "#{phone_id_path}/calls", headers: api_headers, body: initiate_call_body(to_phone_number, sdp_offer)
+      "#{calls_phone_id_path}/calls", headers: api_headers, body: initiate_call_body(to_phone_number, sdp_offer)
     )
     process_initiate_call_response(response)
   end
 
   private
 
+  def calls_phone_id_path
+    base = ENV.fetch('WHATSAPP_CLOUD_BASE_URL', 'https://graph.facebook.com')
+    version = GlobalConfigService.load('WHATSAPP_API_VERSION', WHATSAPP_CALLING_API_VERSION_FALLBACK)
+    "#{base}/#{version}/#{whatsapp_channel.provider_config['phone_number_id']}"
+  end
+
   def call_action_body(call_id, action, sdp_answer = nil)
     body = { messaging_product: 'whatsapp', call_id: call_id, action: action }
     body[:session] = { sdp: sdp_answer, sdp_type: 'answer' } if sdp_answer
@@ -44,7 +55,7 @@ module Enterprise::Whatsapp::Providers::WhatsappCloudService
   end
 
   def call_api(action_name, body)
-    url = "#{phone_id_path}/calls"
+    url = "#{calls_phone_id_path}/calls"
     Rails.logger.info "[WHATSAPP CALL] #{action_name} POST #{url} body=#{body.except(:session).to_json}"
     response = HTTParty.post(url, headers: api_headers, body: body.to_json)
     Rails.logger.error "[WHATSAPP CALL] #{action_name} failed: status=#{response.code} body=#{response.body}" unless response.success?
@@ -65,7 +76,7 @@ module Enterprise::Whatsapp::Providers::WhatsappCloudService
 
   def initiate_call_body(to_phone_number, sdp_offer)
     {
-      messaging_product: 'whatsapp', to: to_phone_number, type: 'audio',
+      messaging_product: 'whatsapp', to: to_phone_number, action: 'connect',
       session: { sdp: sdp_offer, sdp_type: 'offer' }
     }.to_json
   end

enterprise/app/services/voice/outbound_call_builder.rb

@@ -1,15 +1,16 @@
 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!
+  def self.perform!(account:, inbox:, user:, contact:, conversation: nil)
+    new(account: account, inbox: inbox, user: user, contact: contact, conversation: conversation).perform!
   end
 
-  def initialize(account:, inbox:, user:, contact:)
+  def initialize(account:, inbox:, user:, contact:, conversation: nil)
     @account = account
     @inbox = inbox
     @user = user
     @contact = contact
+    @existing_conversation = conversation
   end
 
   def perform!
@@ -18,7 +19,7 @@ class Voice::OutboundCallBuilder
 
     ActiveRecord::Base.transaction do
       contact_inbox = ensure_contact_inbox!
-      conversation = create_conversation!(contact_inbox)
+      conversation = @existing_conversation || create_conversation!(contact_inbox)
       call_sid = initiate_call!
       call = create_call!(conversation, call_sid)
       message = Voice::CallMessageBuilder.new(call).perform!

enterprise/app/services/whatsapp/call_permission_reply_service.rb

@@ -11,11 +11,23 @@ class Whatsapp::CallPermissionReplyService
     return unless conversation
 
     clear_permission_flag(conversation)
+    emit_permission_granted_activity(conversation)
     broadcast_permission_granted(conversation.contact, conversation)
   end
 
   private
 
+  def emit_permission_granted_activity(conversation)
+    content = I18n.t(
+      'conversations.activity.whatsapp_call.permission_granted',
+      contact_name: conversation.contact.name
+    )
+    ::Conversations::ActivityMessageJob.perform_later(
+      conversation,
+      { account_id: conversation.account_id, inbox_id: conversation.inbox_id, message_type: :activity, content: content }
+    )
+  end
+
   def extract_reply_data
     message = params.dig(:entry, 0, :changes, 0, :value, :messages, 0)
     reply = message&.dig(:interactive, :call_permission_reply)

enterprise/app/services/whatsapp/call_service.rb

@@ -0,0 +1,102 @@
+class Whatsapp::CallService
+  pattr_initialize [:call!, :agent!, :sdp_answer]
+
+  def accept
+    raise Voice::CallErrors::CallFailed, 'sdp_answer is required' if sdp_answer.blank?
+
+    # All side effects under the lock so a concurrent terminate cannot finalize
+    # the call between status update and the message/conversation/broadcast writes.
+    call.with_lock do
+      transition_to_in_progress!
+      update_message_status('in_progress')
+      update_conversation_call_status(call.display_status)
+      broadcast(:accepted, accepted_by_agent_id: agent.id)
+    end
+    call
+  end
+
+  def reject
+    call.with_lock do
+      next if call.terminal? || call.in_progress?
+
+      invoke_provider!(:reject_call)
+      finalize_call('failed')
+    end
+    call
+  end
+
+  def terminate
+    call.with_lock do
+      next if call.terminal?
+
+      invoke_provider!(:terminate_call)
+      # Agent hangs up before contact picks up → no_answer; mirrors the webhook terminate path.
+      finalize_call(call.in_progress? ? 'completed' : 'no_answer')
+    end
+    call
+  end
+
+  private
+
+  def transition_to_in_progress!
+    # Order matters: in_progress and terminal both make ringing? false, so we have to
+    # branch on in_progress? first to surface the distinct AlreadyAccepted state.
+    raise Voice::CallErrors::AlreadyAccepted, 'Call already accepted by another agent' if call.in_progress?
+    raise Voice::CallErrors::NotRinging, 'Call is not in ringing state' unless call.ringing?
+
+    forward_answer_to_meta!
+    call.update!(status: 'in_progress', accepted_by_agent_id: agent.id, started_at: Time.current,
+                 meta: (call.meta || {}).merge('sdp_answer' => sdp_answer))
+    claim_conversation_for_agent
+  end
+
+  def forward_answer_to_meta!
+    invoke_provider!(:pre_accept_call, sdp_answer)
+    invoke_provider!(:accept_call, sdp_answer)
+  end
+
+  # Take ownership of the conversation if no one holds it; leave assignee alone otherwise (transfer via UI).
+  def claim_conversation_for_agent
+    call.conversation.update!(assignee: agent) if call.conversation.assignee_id.blank?
+  end
+
+  # Raise on Meta failure (bool false or transport error) so callers bail before
+  # finalizing local state — otherwise we'd mark a still-active call as ended
+  # and broadcast voice_call.ended while Meta thinks it's live.
+  def invoke_provider!(method, *)
+    success = call.inbox.channel.provider_service.public_send(method, call.provider_call_id, *)
+    raise Voice::CallErrors::CallFailed, "Meta #{method} failed" unless success
+  rescue Voice::CallErrors::CallFailed
+    raise
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP CALL] #{method} failed: #{e.class} #{e.message}"
+    raise Voice::CallErrors::CallFailed, "Meta #{method} failed"
+  end
+
+  def finalize_call(status)
+    meta = (call.meta || {}).merge('ended_at' => Time.zone.now.to_i)
+    call.update!(status: status, meta: meta)
+    update_message_status(status)
+    update_conversation_call_status(call.display_status)
+    broadcast(:ended, status: call.display_status)
+  end
+
+  def update_message_status(status)
+    Voice::CallMessageBuilder.new(call).update_status!(status: status, agent: agent)
+  end
+
+  def update_conversation_call_status(status)
+    call.conversation.update!(
+      additional_attributes: (call.conversation.additional_attributes || {}).merge('call_status' => status)
+    )
+  end
+
+  def broadcast(event, **extra)
+    payload = {
+      event: "voice_call.#{event}",
+      data: { id: call.id, call_id: call.provider_call_id, provider: call.provider,
+              conversation_id: call.conversation_id, account_id: call.account_id }.merge(extra)
+    }
+    ActionCable.server.broadcast("account_#{call.account_id}", payload)
+  end
+end

enterprise/app/services/whatsapp/incoming_call_service.rb

@@ -5,6 +5,7 @@ class Whatsapp::IncomingCallService
     return unless inbox.channel.voice_enabled?
 
     Array(params[:calls]).each { |c| handle_event(c.with_indifferent_access) }
+    Array(params[:statuses]).each { |s| handle_status(s.with_indifferent_access) }
   end
 
   private
@@ -17,6 +18,32 @@ class Whatsapp::IncomingCallService
     end
   end
 
+  # Meta's `connect` event for outbound calls fires when the WebRTC tunnel is
+  # up — empirically ~20s before the contact actually answers. The real pickup
+  # is reported as a separate webhook with status=ACCEPTED, and is what
+  # `terminate.start_time` aligns to. Treat ACCEPTED as the pickup transition.
+  def handle_status(payload)
+    return unless payload[:type] == 'call'
+
+    call = Call.whatsapp.find_by(provider_call_id: payload[:id])
+    return unless call
+
+    case payload[:status]
+    when 'ACCEPTED' then mark_outbound_accepted(call, payload)
+    when 'RINGING' then nil # informational
+    else Rails.logger.info "[WHATSAPP CALL] Unhandled call status: #{payload[:status]} for #{payload[:id]}"
+    end
+  end
+
+  def mark_outbound_accepted(call, payload)
+    return unless call.outgoing?
+    return if call.in_progress? || call.terminal?
+
+    started_at = Time.zone.at(payload[:timestamp].to_i) if payload[:timestamp].present?
+    update_call!(call, 'in_progress', started_at: started_at || Time.current)
+    broadcast(call, 'voice_call.outbound_accepted')
+  end
+
   def handle_connect(payload)
     call = Call.whatsapp.find_by(provider_call_id: payload[:id])
     if call.nil?
@@ -50,19 +77,23 @@ class Whatsapp::IncomingCallService
     broadcast_incoming(call, sdp_offer)
   end
 
+  # `connect` is the WebRTC tunnel-ready signal, not the pickup signal. Apply
+  # Meta's SDP answer so the handshake completes during ringing; the call
+  # stays in `ringing` until status=ACCEPTED arrives.
   def accept_outbound_call(call, payload)
     return if call.in_progress? || call.terminal?
 
     # Pin setup:active so browsers don't renegotiate when Meta echoes actpass.
     sdp_answer = payload.dig(:session, :sdp)&.gsub('a=setup:actpass', 'a=setup:active')
-    update_call!(call, 'in_progress',
-                 started_at: Time.current,
-                 meta: (call.meta || {}).merge('sdp_answer' => sdp_answer))
+    call.update!(meta: (call.meta || {}).merge('sdp_answer' => sdp_answer))
     broadcast(call, 'voice_call.outbound_connected', sdp_answer: sdp_answer)
   end
 
   def handle_terminate(payload)
-    call = Call.whatsapp.find_by(provider_call_id: payload[:id])
+    # Webhooks can arrive out of order (terminate before connect under tunnel/network
+    # delays). Materialise a missed-call record so the contact's "called and hung up"
+    # still surfaces in the dashboard instead of being silently dropped.
+    call = Call.whatsapp.find_by(provider_call_id: payload[:id]) || build_missed_inbound_call(payload)
     return unless call
     # Webhook retries can re-deliver terminate after we've already finalized the
     # call; don't recompute status or a duration=0 retry can flip a completed
@@ -76,6 +107,18 @@ class Whatsapp::IncomingCallService
     broadcast(call, 'voice_call.ended', status: call.display_status, duration_seconds: call.duration_seconds)
   end
 
+  # No connect was ever processed (webhook reordering or never delivered) — build a
+  # bare Call+Message for the contact so the UI shows the missed-call bubble.
+  def build_missed_inbound_call(payload)
+    Voice::InboundCallBuilder.perform!(
+      inbox: inbox, from_number: "+#{payload[:from]}", call_sid: payload[:id],
+      provider: :whatsapp,
+      extra_meta: { 'ice_servers' => Call.default_ice_servers }
+    )
+  rescue ActiveRecord::RecordNotUnique
+    Call.whatsapp.find_by(provider_call_id: payload[:id])
+  end
+
   # accepted_by_agent_id is the initiating agent on outbound calls, so it only signals "answered" for inbound.
   def answered?(call, duration)
     call.in_progress? || duration.to_i.positive? || (call.incoming? && call.accepted_by_agent_id.present?)

enterprise/app/views/api/v1/accounts/whatsapp_calls/accept.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/whatsapp_call', call: @call

enterprise/app/views/api/v1/accounts/whatsapp_calls/initiate.json.jbuilder

@@ -0,0 +1,5 @@
+json.status 'calling'
+json.call_id @call.provider_call_id
+json.id @call.id
+json.message_id @message.id
+json.provider 'whatsapp'

enterprise/app/views/api/v1/accounts/whatsapp_calls/reject.json.jbuilder

@@ -0,0 +1,2 @@
+json.id @call.id
+json.status @call.display_status

enterprise/app/views/api/v1/accounts/whatsapp_calls/show.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/whatsapp_call', call: @call

enterprise/app/views/api/v1/accounts/whatsapp_calls/terminate.json.jbuilder

@@ -0,0 +1,2 @@
+json.id @call.id
+json.status @call.display_status

enterprise/app/views/api/v1/accounts/whatsapp_calls/upload_recording.json.jbuilder

@@ -0,0 +1,2 @@
+json.id @call.id
+json.status @upload_status

enterprise/app/views/api/v1/models/_whatsapp_call.json.jbuilder

@@ -0,0 +1,24 @@
+contact = call.conversation&.contact
+
+json.id call.id
+json.call_id call.provider_call_id
+json.provider call.provider
+json.status call.display_status
+json.direction call.direction_label
+json.conversation_id call.conversation_id
+json.inbox_id call.inbox_id
+json.message_id call.message_id
+json.accepted_by_agent_id call.accepted_by_agent_id
+json.elapsed_seconds(call.started_at ? (Time.current - call.started_at).to_i : 0)
+json.sdp_offer call.meta&.dig('sdp_offer')
+json.ice_servers(call.meta&.dig('ice_servers') || Call.default_ice_servers)
+
+if contact
+  json.caller do
+    json.name contact.name
+    json.phone contact.phone_number
+    json.avatar contact.avatar_url
+  end
+else
+  json.caller({})
+end

spec/enterprise/services/enterprise/whatsapp/providers/whatsapp_cloud_service_spec.rb

@@ -40,7 +40,7 @@ describe Whatsapp::Providers::WhatsappCloudService do
   describe '#initiate_call' do
     it 'returns the parsed body on success' do
       stub_request(:post, calls_url)
-        .with(body: { messaging_product: 'whatsapp', to: '15551234567', type: 'audio',
+        .with(body: { messaging_product: 'whatsapp', to: '15551234567', action: 'connect',
                       session: { sdp: 'sdp_offer', sdp_type: 'offer' } }.to_json)
         .to_return(status: 200, body: { messages: [{ id: 'wacall_1' }] }.to_json, headers: headers)
 

spec/services/whatsapp/facebook_api_client_spec.rb

@@ -177,7 +177,7 @@ describe Whatsapp::FacebookApiClient do
           .with(
             headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
             body: { override_callback_uri: callback_url, verify_token: verify_token,
-                    subscribed_fields: %w[messages smb_message_echoes] }.to_json
+                    subscribed_fields: %w[messages smb_message_echoes calls] }.to_json
           )
           .to_return(
             status: 200,
@@ -224,7 +224,7 @@ describe Whatsapp::FacebookApiClient do
           .with(
             headers: { 'Authorization' => "Bearer #{access_token}", 'Content-Type' => 'application/json' },
             body: { override_callback_uri: callback_url, verify_token: verify_token,
-                    subscribed_fields: %w[messages smb_message_echoes] }.to_json
+                    subscribed_fields: %w[messages smb_message_echoes calls] }.to_json
           )
           .to_return(status: 400, body: { error: 'Webhook callback override failed' }.to_json)
       end