feat(voice): Improved voice call creation flow [EE] (#12268)

This PR improves the voice call creation flow by simplifying configuration and automating setup with Twilio APIs. references: #11602 , #11481 ## Key changes - Removed the requirement for twiml_app_sid – provisioning is now automated through APIs. - Auto-configured webhook URLs for: - Voice number callbacks - Status callbacks - twiML callbacks - Disabled business hours, help center, and related options until voice inbox is fully supported. - Added a configuration tab in the voice inbox to display the required Twilio URLs (to make verification easier in Twilio console). ## Test Cases - Provisioning - Create a new voice inbox → verify that Twilio app provisioning happens automatically. - Verify twiML callback - Webhook configuration - Check that both voice number callback and status callback URLs are auto-populated in Twilio. - Disabled features - Confirm that business hours and help center options are hidden/disabled for voice inbox. - Configuration tab - Open the voice inbox configuration tab → verify that the displayed Twilio URLs match what’s set in Twilio.
2025-08-22 13:38:23 +02:00
parent d35b0a9465
commit d48503bdcf
12 changed files with 302 additions and 39 deletions
--- a/app/javascript/dashboard/i18n/locale/en/inboxMgmt.json
+++ b/app/javascript/dashboard/i18n/locale/en/inboxMgmt.json
@@ -330,13 +330,14 @@
            "LABEL": "API Key Secret",
            "PLACEHOLDER": "Enter your Twilio API Key Secret",
            "REQUIRED": "API Key Secret is required"
-          },
-          "TWIML_APP_SID": {
-            "LABEL": "TwiML App SID",
-            "PLACEHOLDER": "Enter your Twilio TwiML App SID (starts with AP)",
-            "REQUIRED": "TwiML App SID is required"
          }
        },
+        "CONFIGURATION": {
+          "TWILIO_VOICE_URL_TITLE": "Twilio Voice URL",
+          "TWILIO_VOICE_URL_SUBTITLE": "Configure this URL as the Voice URL on your Twilio phone number and TwiML App.",
+          "TWILIO_STATUS_URL_TITLE": "Twilio Status Callback URL",
+          "TWILIO_STATUS_URL_SUBTITLE": "Configure this URL as the Status Callback URL on your Twilio phone number."
+        },
        "SUBMIT_BUTTON": "Create Voice Channel",
        "API": {
          "ERROR_MESSAGE": "We were not able to create the voice channel"
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue
@@ -116,16 +116,22 @@ export default {
          key: 'collaborators',
          name: this.$t('INBOX_MGMT.TABS.COLLABORATORS'),
        },
-        {
-          key: 'businesshours',
-          name: this.$t('INBOX_MGMT.TABS.BUSINESS_HOURS'),
-        },
-        {
-          key: 'csat',
-          name: this.$t('INBOX_MGMT.TABS.CSAT'),
-        },
      ];

+      if (!this.isAVoiceChannel) {
+        visibleToAllChannelTabs = [
+          ...visibleToAllChannelTabs,
+          {
+            key: 'businesshours',
+            name: this.$t('INBOX_MGMT.TABS.BUSINESS_HOURS'),
+          },
+          {
+            key: 'csat',
+            name: this.$t('INBOX_MGMT.TABS.CSAT'),
+          },
+        ];
+      }
+
      if (this.isAWebWidgetInbox) {
        visibleToAllChannelTabs = [
          ...visibleToAllChannelTabs,
@@ -144,6 +150,7 @@ export default {
        this.isATwilioChannel ||
        this.isALineChannel ||
        this.isAPIInbox ||
+        this.isAVoiceChannel ||
        (this.isAnEmailChannel && !this.inbox.provider) ||
        this.shouldShowWhatsAppConfiguration ||
        this.isAWebWidgetInbox
@@ -676,7 +683,7 @@ export default {
              }}
            </p>
          </label>
-          <div class="pb-4">
+          <div v-if="!isAVoiceChannel" class="pb-4">
            <label>
              {{ $t('INBOX_MGMT.HELP_CENTER.LABEL') }}
            </label>
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Voice.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/channels/Voice.vue
@@ -22,7 +22,6 @@ const state = reactive({
  authToken: '',
  apiKeySid: '',
  apiKeySecret: '',
-  twimlAppSid: '',
 });

 const uiFlags = useMapGetter('inboxes/getUIFlags');
@@ -33,7 +32,6 @@ const validationRules = {
  authToken: { required },
  apiKeySid: { required },
  apiKeySecret: { required },
-  twimlAppSid: { required },
 };

 const v$ = useVuelidate(validationRules, state);
@@ -55,9 +53,6 @@ const formErrors = computed(() => ({
  apiKeySecret: v$.value.apiKeySecret?.$error
    ? t('INBOX_MGMT.ADD.VOICE.TWILIO.API_KEY_SECRET.REQUIRED')
    : '',
-  twimlAppSid: v$.value.twimlAppSid?.$error
-    ? t('INBOX_MGMT.ADD.VOICE.TWILIO.TWIML_APP_SID.REQUIRED')
-    : '',
 }));

 function getProviderConfig() {
@@ -67,7 +62,6 @@ function getProviderConfig() {
    api_key_sid: state.apiKeySid,
    api_key_secret: state.apiKeySecret,
  };
-  if (state.twimlAppSid) config.outgoing_application_sid = state.twimlAppSid;
  return config;
 }

@@ -160,17 +154,6 @@ async function createChannel() {
        @blur="v$.apiKeySecret?.$touch"
      />

-      <Input
-        v-model="state.twimlAppSid"
-        :label="t('INBOX_MGMT.ADD.VOICE.TWILIO.TWIML_APP_SID.LABEL')"
-        :placeholder="
-          t('INBOX_MGMT.ADD.VOICE.TWILIO.TWIML_APP_SID.PLACEHOLDER')
-        "
-        :message="formErrors.twimlAppSid"
-        :message-type="formErrors.twimlAppSid ? 'error' : 'info'"
-        @blur="v$.twimlAppSid?.$touch"
-      />
-
      <div>
        <NextButton
          :is-loading="uiFlags.isCreating"
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/settingsPage/ConfigurationPage.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/settingsPage/ConfigurationPage.vue
@@ -126,6 +126,25 @@ export default {
      <woot-code :script="inbox.callback_webhook_url" lang="html" />
    </SettingsSection>
  </div>
+  <div v-else-if="isAVoiceChannel" class="mx-8">
+    <SettingsSection
+      :title="$t('INBOX_MGMT.ADD.VOICE.CONFIGURATION.TWILIO_VOICE_URL_TITLE')"
+      :sub-title="
+        $t('INBOX_MGMT.ADD.VOICE.CONFIGURATION.TWILIO_VOICE_URL_SUBTITLE')
+      "
+    >
+      <woot-code :script="inbox.voice_call_webhook_url" lang="html" />
+    </SettingsSection>
+    <SettingsSection
+      :title="$t('INBOX_MGMT.ADD.VOICE.CONFIGURATION.TWILIO_STATUS_URL_TITLE')"
+      :sub-title="
+        $t('INBOX_MGMT.ADD.VOICE.CONFIGURATION.TWILIO_STATUS_URL_SUBTITLE')
+      "
+    >
+      <woot-code :script="inbox.voice_status_webhook_url" lang="html" />
+    </SettingsSection>
+  </div>
+
  <div v-else-if="isALineChannel" class="mx-8">
    <SettingsSection
      :title="$t('INBOX_MGMT.ADD.LINE_CHANNEL.API_CALLBACK.TITLE')"
--- a/app/javascript/shared/mixins/inboxMixin.js
+++ b/app/javascript/shared/mixins/inboxMixin.js
@@ -57,15 +57,15 @@ export default {
    isALineChannel() {
      return this.channelType === INBOX_TYPES.LINE;
    },
+    isAVoiceChannel() {
+      return this.channelType === INBOX_TYPES.VOICE;
+    },
    isAnEmailChannel() {
      return this.channelType === INBOX_TYPES.EMAIL;
    },
    isATelegramChannel() {
      return this.channelType === INBOX_TYPES.TELEGRAM;
    },
-    isAVoiceChannel() {
-      return this.channelType === INBOX_TYPES.VOICE;
-    },
    isATwilioSMSChannel() {
      const { medium: medium = '' } = this.inbox;
      return this.isATwilioChannel && medium === 'sms';
--- a/app/views/api/v1/models/_inbox.json.jbuilder
+++ b/app/views/api/v1/models/_inbox.json.jbuilder
@@ -118,3 +118,9 @@ if resource.whatsapp?
  json.provider_config resource.channel.try(:provider_config) if Current.account_user&.administrator?
  json.reauthorization_required resource.channel.try(:reauthorization_required?)
 end
+
+## Voice Channel Attributes
+if resource.channel_type == 'Channel::Voice'
+  json.voice_call_webhook_url resource.channel.try(:voice_call_webhook_url)
+  json.voice_status_webhook_url resource.channel.try(:voice_status_webhook_url)
+end
--- a/enterprise/app/models/channel/voice.rb
+++ b/enterprise/app/models/channel/voice.rb
@@ -30,6 +30,7 @@ class Channel::Voice < ApplicationRecord

  # Provider-specific configs stored in JSON
  validate :validate_provider_config
+  before_validation :provision_twilio_on_create, on: :create, if: :twilio?

  EDITABLE_ATTRS = [:phone_number, :provider, { provider_config: {} }].freeze

@@ -41,8 +42,23 @@ class Channel::Voice < ApplicationRecord
    false
  end

+  # Public URLs used to configure Twilio webhooks
+  def voice_call_webhook_url
+    base = ENV.fetch('FRONTEND_URL', '').to_s.sub(%r{/*$}, '')
+    "#{base}/twilio/voice/call/#{phone_number}"
+  end
+
+  def voice_status_webhook_url
+    base = ENV.fetch('FRONTEND_URL', '').to_s.sub(%r{/*$}, '')
+    "#{base}/twilio/voice/status/#{phone_number}"
+  end
+
  private

+  def twilio?
+    provider == 'twilio'
+  end
+
  def validate_provider_config
    return if provider_config.blank?

@@ -54,10 +70,30 @@ class Channel::Voice < ApplicationRecord

  def validate_twilio_config
    config = provider_config.with_indifferent_access
-    required_keys = %w[account_sid auth_token api_key_sid api_key_secret]
-
+    # Require credentials and provisioned TwiML App SID
+    required_keys = %w[account_sid auth_token api_key_sid api_key_secret twiml_app_sid]
    required_keys.each do |key|
      errors.add(:provider_config, "#{key} is required for Twilio provider") if config[key].blank?
    end
  end
+
+  def provision_twilio_on_create
+    service = ::Twilio::VoiceWebhookSetupService.new(channel: self)
+    app_sid = service.perform
+    return if app_sid.blank?
+
+    cfg = provider_config.with_indifferent_access
+    cfg[:twiml_app_sid] = app_sid
+    self.provider_config = cfg
+  rescue StandardError => e
+    error_details = {
+      error_class: e.class.to_s,
+      message: e.message,
+      phone_number: phone_number,
+      account_id: account_id,
+      backtrace: e.backtrace&.first(5)
+    }
+    Rails.logger.error("TWILIO_VOICE_SETUP_ON_CREATE_ERROR: #{error_details}")
+    errors.add(:base, "Twilio setup failed: #{e.message}")
+  end
 end
--- a/enterprise/app/services/twilio/voice_webhook_setup_service.rb
+++ b/enterprise/app/services/twilio/voice_webhook_setup_service.rb
@@ -0,0 +1,99 @@
+class Twilio::VoiceWebhookSetupService
+  include Rails.application.routes.url_helpers
+
+  pattr_initialize [:channel!]
+
+  HTTP_METHOD = 'POST'.freeze
+
+  # Returns created TwiML App SID on success.
+  def perform
+    validate_token_credentials!
+
+    app_sid = create_twiml_app!
+    configure_number_webhooks!
+    app_sid
+  end
+
+  private
+
+  def validate_token_credentials!
+    # Only validate Account SID + Auth Token
+    token_client.incoming_phone_numbers.list(limit: 1)
+  rescue StandardError => e
+    log_twilio_error('AUTH_VALIDATION_TOKEN', e)
+    raise
+  end
+
+  def create_twiml_app!
+    friendly_name = "Chatwoot Voice #{channel.phone_number}"
+    app = api_key_client.applications.create(
+      friendly_name: friendly_name,
+      voice_url: channel.voice_call_webhook_url,
+      voice_method: HTTP_METHOD
+    )
+    app.sid
+  rescue StandardError => e
+    log_twilio_error('TWIML_APP_CREATE', e)
+    raise
+  end
+
+  def configure_number_webhooks!
+    numbers = api_key_client.incoming_phone_numbers.list(phone_number: channel.phone_number)
+    if numbers.empty?
+      Rails.logger.warn "TWILIO_PHONE_NUMBER_NOT_FOUND: #{channel.phone_number}"
+      return
+    end
+
+    api_key_client
+      .incoming_phone_numbers(numbers.first.sid)
+      .update(
+        voice_url: channel.voice_call_webhook_url,
+        voice_method: HTTP_METHOD,
+        status_callback: channel.voice_status_webhook_url,
+        status_callback_method: HTTP_METHOD
+      )
+  rescue StandardError => e
+    log_twilio_error('NUMBER_WEBHOOKS_UPDATE', e)
+    raise
+  end
+
+  def api_key_client
+    @api_key_client ||= begin
+      cfg = channel.provider_config.with_indifferent_access
+      ::Twilio::REST::Client.new(cfg[:api_key_sid], cfg[:api_key_secret], cfg[:account_sid])
+    end
+  end
+
+  def token_client
+    @token_client ||= begin
+      cfg = channel.provider_config.with_indifferent_access
+      ::Twilio::REST::Client.new(cfg[:account_sid], cfg[:auth_token])
+    end
+  end
+
+  def log_twilio_error(context, error)
+    details = build_error_details(context, error)
+    add_twilio_specific_details(details, error)
+
+    backtrace = error.backtrace.is_a?(Array) ? error.backtrace.first(5) : []
+    Rails.logger.error("TWILIO_VOICE_SETUP_ERROR: #{details} backtrace=#{backtrace}")
+  end
+
+  def build_error_details(context, error)
+    cfg = channel.provider_config.with_indifferent_access
+    {
+      context: context,
+      phone_number: channel.phone_number,
+      account_sid: cfg[:account_sid],
+      error_class: error.class.to_s,
+      message: error.message
+    }
+  end
+
+  def add_twilio_specific_details(details, error)
+    details[:status_code] = error.status_code if error.respond_to?(:status_code)
+    details[:twilio_code] = error.code if error.respond_to?(:code)
+    details[:more_info] = error.more_info if error.respond_to?(:more_info)
+    details[:details] = error.details if error.respond_to?(:details)
+  end
+end
--- a/spec/enterprise/controllers/enterprise/api/v1/accounts/inboxes_controller_spec.rb
+++ b/spec/enterprise/controllers/enterprise/api/v1/accounts/inboxes_controller_spec.rb
@@ -24,6 +24,9 @@ RSpec.describe 'Enterprise Inboxes API', type: :request do
      end

      it 'creates a voice inbox when administrator' do
+        allow(Twilio::VoiceWebhookSetupService).to receive(:new).and_return(instance_double(Twilio::VoiceWebhookSetupService,
+                                                                                            perform: "AP#{SecureRandom.hex(16)}"))
+
        post "/api/v1/accounts/#{account.id}/inboxes",
             headers: admin.create_new_auth_token,
             params: { name: 'Voice Inbox',
@@ -31,7 +34,8 @@ RSpec.describe 'Enterprise Inboxes API', type: :request do
                                  provider_config: { account_sid: "AC#{SecureRandom.hex(16)}",
                                                     auth_token: SecureRandom.hex(16),
                                                     api_key_sid: SecureRandom.hex(8),
-                                                     api_key_secret: SecureRandom.hex(16) } } },
+                                                     api_key_secret: SecureRandom.hex(16),
+                                                     twiml_app_sid: "AP#{SecureRandom.hex(16)}" } } },
             as: :json

        expect(response).to have_http_status(:success)
--- a/spec/enterprise/models/channel/voice_spec.rb
+++ b/spec/enterprise/models/channel/voice_spec.rb
@@ -3,8 +3,13 @@
 require 'rails_helper'

 RSpec.describe Channel::Voice do
+  let(:twiml_app_sid) { 'AP1234567890abcdef' }
  let(:channel) { create(:channel_voice) }

+  before do
+    allow(Twilio::VoiceWebhookSetupService).to receive(:new).and_return(instance_double(Twilio::VoiceWebhookSetupService, perform: twiml_app_sid))
+  end
+
  it 'has a valid factory' do
    expect(channel).to be_valid
  end
@@ -40,12 +45,19 @@ RSpec.describe Channel::Voice do
      expect(channel.errors[:provider_config]).to include('api_key_secret is required for Twilio provider')
    end

+    it 'validates presence of twiml_app_sid in provider_config' do
+      channel.provider_config = { account_sid: 'sid', auth_token: 'token', api_key_sid: 'key', api_key_secret: 'secret' }
+      expect(channel).not_to be_valid
+      expect(channel.errors[:provider_config]).to include('twiml_app_sid is required for Twilio provider')
+    end
+
    it 'is valid with all required provider_config fields' do
      channel.provider_config = {
        account_sid: 'test_sid',
        auth_token: 'test_token',
        api_key_sid: 'test_key',
-        api_key_secret: 'test_secret'
+        api_key_secret: 'test_secret',
+        twiml_app_sid: 'test_app_sid'
      }
      expect(channel).to be_valid
    end
@@ -57,4 +69,11 @@ RSpec.describe Channel::Voice do
      expect(channel.name).to include(channel.phone_number)
    end
  end
+
+  describe 'provisioning on create' do
+    it 'stores twiml_app_sid in provider_config' do
+      ch = create(:channel_voice)
+      expect(ch.provider_config.with_indifferent_access[:twiml_app_sid]).to eq(twiml_app_sid)
+    end
+  end
 end
--- a/spec/enterprise/services/twilio/voice_webhook_setup_service_spec.rb
+++ b/spec/enterprise/services/twilio/voice_webhook_setup_service_spec.rb
@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe Twilio::VoiceWebhookSetupService do
+  let(:account_sid) { 'ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' }
+  let(:auth_token) { 'auth_token_123' }
+  let(:api_key_sid) { 'SKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' }
+  let(:api_key_secret) { 'api_key_secret_123' }
+  let(:phone_number) { '+15551230001' }
+  let(:frontend_url) { 'https://app.chatwoot.test' }
+
+  let(:channel) do
+    build(:channel_voice, phone_number: phone_number, provider_config: {
+            account_sid: account_sid,
+            auth_token: auth_token,
+            api_key_sid: api_key_sid,
+            api_key_secret: api_key_secret
+          })
+  end
+
+  let(:twilio_base_url) { "https://api.twilio.com/2010-04-01/Accounts/#{account_sid}" }
+  let(:incoming_numbers_url) { "#{twilio_base_url}/IncomingPhoneNumbers.json" }
+  let(:applications_url) { "#{twilio_base_url}/Applications.json" }
+  let(:phone_number_sid) { 'PN123' }
+  let(:phone_number_url) { "#{twilio_base_url}/IncomingPhoneNumbers/#{phone_number_sid}.json" }
+
+  before do
+    # Token validation using Account SID + Auth Token
+    stub_request(:get, /#{Regexp.escape(incoming_numbers_url)}.*/)
+      .with(basic_auth: [account_sid, auth_token])
+      .to_return(status: 200,
+                 body: { incoming_phone_numbers: [], meta: { key: 'incoming_phone_numbers' } }.to_json,
+                 headers: { 'Content-Type' => 'application/json' })
+
+    # Number lookup using API Key SID/Secret
+    stub_request(:get, /#{Regexp.escape(incoming_numbers_url)}.*/)
+      .with(basic_auth: [api_key_sid, api_key_secret])
+      .to_return(status: 200,
+                 body: { incoming_phone_numbers: [{ sid: phone_number_sid }], meta: { key: 'incoming_phone_numbers' } }.to_json,
+                 headers: { 'Content-Type' => 'application/json' })
+
+    # TwiML App create (voice only)
+    stub_request(:post, applications_url)
+      .with(basic_auth: [api_key_sid, api_key_secret])
+      .to_return(status: 201,
+                 body: { sid: 'AP123' }.to_json,
+                 headers: { 'Content-Type' => 'application/json' })
+
+    # Incoming Phone Number webhook update
+    stub_request(:post, phone_number_url)
+      .with(basic_auth: [api_key_sid, api_key_secret])
+      .to_return(status: 200,
+                 body: { sid: phone_number_sid }.to_json,
+                 headers: { 'Content-Type' => 'application/json' })
+  end
+
+  it 'creates a TwiML App and configures number webhooks with correct URLs' do
+    with_modified_env FRONTEND_URL: frontend_url do
+      service = described_class.new(channel: channel)
+      sid = service.perform
+
+      expect(sid).to eq('AP123')
+
+      expected_voice_url = channel.voice_call_webhook_url
+      expected_status_url = channel.voice_status_webhook_url
+
+      # Assert TwiML App creation body includes voice URL and POST method
+      expect(
+        a_request(:post, applications_url)
+          .with(body: hash_including('VoiceUrl' => expected_voice_url, 'VoiceMethod' => 'POST'))
+      ).to have_been_made
+
+      # Assert number webhook update body includes both URLs and POST methods
+      expect(
+        a_request(:post, phone_number_url)
+          .with(
+            body: hash_including(
+              'VoiceUrl' => expected_voice_url,
+              'VoiceMethod' => 'POST',
+              'StatusCallback' => expected_status_url,
+              'StatusCallbackMethod' => 'POST'
+            )
+          )
+      ).to have_been_made
+    end
+  end
+end
--- a/spec/factories/channel/channel_voice.rb
+++ b/spec/factories/channel/channel_voice.rb
@@ -8,7 +8,8 @@ FactoryBot.define do
        account_sid: "AC#{SecureRandom.hex(16)}",
        auth_token: SecureRandom.hex(16),
        api_key_sid: SecureRandom.hex(8),
-        api_key_secret: SecureRandom.hex(16)
+        api_key_secret: SecureRandom.hex(16),
+        twiml_app_sid: "AP#{SecureRandom.hex(16)}"
      }
    end
    account