{"method":"POST","path":"https://api.revcent.com/v2/ai_voice_agents/{ai_voice_agent_id}","summary":"Edit An AI Voice Agent","description":"Edit a previously created AI Voice Agent using the AI Voice Agent ID. Only include the properties you wish to modify. For example, if you only want to modify the name of the AI Voice Agent, then only include the name property in the request body. View markdown documentation at https://revcent.com/documentation/markdown/mcp/operation/EditAIVoiceAgent.md for an in-depth overview of this operation.","operationId":"EditAIVoiceAgent","parameters":[{"in":"path","name":"ai_voice_agent_id","description":"The AI Voice Agent ID","required":true,"schema":{"type":"string","title":"AI Voice Agent ID","description":"A 20 character AI Voice Agent ID.","minLength":20,"maxLength":20}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"The AI Voice Agent name."},"description":{"type":"string","description":"The AI Voice Agent description."},"enabled":{"type":"boolean","description":"Whether the AI Voice Agent is enabled."},"call_method":{"type":"string","description":"The AI Voice Agent call method.","enum":["inbound","outbound"]},"pre_agent_function":{"type":"string","description":"The pre-agent function that will be called before the AI Voice Agent is triggered. The pre-agent function can be used to generate additional content for within the agent instructions when compiling using handlebars syntax. The pre agent function must be created with a trigger of 'api_direct' in order to be accessible to an AI voice agent.<br><br>Read more about the pre-agent function <a href=\"https://kb.revcent.com/en/tools/ai/voice-agents#pre-agent-function\" target=\"_blank\">here</a>. To remove a pre agent function submit an empty string for this value.","minLength":0,"maxLength":20},"settings":{"additionalProperties":false,"properties":{"voice":{"type":"string","description":"The AI voice to be used for the AI Voice Agent. The available voices depend on the list of available voices from OpenAI's realtime voice model.","enum":["marin","cedar"]},"instructions":{"additionalProperties":false,"properties":{"markdown":{"type":"string","description":"The AI voice Agent instructions in markdown format. Agent instructions are generated for each call using the handlebars sytax, allowing for dynamic content based on the specific caller.<br><br>It is recommended to read more about creating the instructions markdown, including formatting, at <a href=\"https://kb.revcent.com/en/tools/ai/voice-agents#agent-instructions\" target=\"_blank\">https://kb.revcent.com/en/tools/ai/voice-agents#agent-instructions</a>.<br><br>Also, OpenAI has a section on conversation flow usage in instruction markdown at <a href=\"https://developers.openai.com/cookbook/examples/realtime_prompting_guide#conversation-flow\" target=\"_blank\">https://developers.openai.com/cookbook/examples/realtime_prompting_guide#conversation-flow</a>"}},"type":"object","description":"The AI Voice Agent instructions."},"limits":{"additionalProperties":false,"properties":{"max_outbound_calls_per_customer":{"type":"integer","description":"If the AI Voice agent call_method is outbound, the maximum number of outbound calls allowed per customer. Default is 1."},"max_calls_per_day":{"type":"integer","description":"The maximum number of calls allowed per day. Default is 0. 0 means no limit."},"max_duration":{"type":"integer","description":"The maximum duration of a call in minutes. Default is 15."}},"type":"object","description":"Limits to be placed on the AI Voice Agent regardless of inbound or outbound calls."},"system_actions":{"items":{"type":"string","description":"System actions that are allowed to be used by the AI in the AI Voice Agent instructions. System actions are opt-in. Only provide system actions that are relevant to the purpose of the AI Voice Agent to ensure the best performance and to prevent callers from triggering unwanted operations. Notice how system actions are operation ID's for API operations, so you can view a system actions' related API operation to get the details of exactly what the system action can do. Depending on the capabilities/instructions of the AI Voice Agent, you may want to enable certain system actions that the AI can call during a conversation. For example, if you have an AI Voice Agent that is meant to assist customers with questions about their orders, you may want to enable system actions related to retrieving sale, customer and shipping details.","enum":["GetCustomer","AddCardToCustomer","SearchCustomers","GetEmailTemplates","GetEmailTemplate","GetFunctions","GetFunction","TriggerFunction","InsertMetadata","CreateNote","GetPayPalTransaction","GetPendingRefund","GetProductSale","RefundProductSale","CreateSale","GetSale","VoidSale","AddFraudAlert","ProcessPendingSale","EstimateSale","GetShipment","EditShipment","RefundShipment","SendSMTPMessage","GetSMTPMessage","GetSubscriptionRenewal","RefundSubscriptionRenewal","GetSubscription","EditSubscription","ActivateSubscription","SuspendSubscription","CancelSubscription","RenewSubscription","GetTransaction","RefundTransaction","GetTrial","CancelTrial"]},"type":"array","description":"System actions are API operations that can be called by AI during a call. It is highly recommended to only include system actions that may be needed by the AI Voice Agent depending on its purpose."},"active_window":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Whether the active window feature is enabled. When enabled, the AI Voice Agent will only be active during certain hours of the day specified by the user."},"start_hour":{"type":"integer","description":"The hour at which the AI Voice Agent will start being active. This is only relevant if the active window feature is enabled."},"end_hour":{"type":"integer","description":"The hour at which the AI Voice Agent will stop being active. This is only relevant if the active window feature is enabled."},"timezone":{"type":"string","description":"The timezone in which the active window hours are specified."},"inactive_forward_number":{"type":"string","description":"If set, inbound calls will be forwarded to this number during inactive hours. Leave blank to not forward and simply hangup with a brief message."}},"type":"object","description":"If you wish to have this agent active only within certain hours during the day. Useful for limiting/preventing late outbound calls."},"trigger_settings":{"type":"object","description":"Trigger settings, which only applies to call_method = 'outbound'.","additionalProperties":false,"properties":{"trigger":{"type":"string","description":"The trigger for an outbound AI Voice Agent. Determines what triggers the AI Voice Agent to make an outbound call, either triggered based on an account event or on demand via API using the TriggerAIVoiceAgent operation.","enum":["account_event","on_demand"]},"account_event":{"additionalProperties":false,"properties":{"notation":{"type":"string","description":"The notation for the account event trigger. Read more at https://kb.revcent.com/en/revcent-account/events to understand notation formatting and their associated event data.","enum":["ai_memo.created","chargeback.created","check_direct.created","customer.created","customer.updated.add_card","customer.updated.address","customer.updated.customer_group","customer.updated.customer_group.added","customer.updated.customer_group.removed","customer.updated.disabled","customer.updated.enabled","discount.created","fraud_detection.created","fraud_detection.updated.false_positive","invoice.created","note.created","offline_payment.created","paypal_dispute.created","paypal_transaction.created","pending_refund.created","pending_refund.created.product_sale","pending_refund.created.product_sale.full","pending_refund.created.product_sale.partial","pending_refund.created.shipping","pending_refund.created.shipping.full","pending_refund.created.shipping.full.has_fulfillment","pending_refund.created.shipping.full.no_fulfillment","pending_refund.created.shipping.has_fulfillment","pending_refund.created.shipping.no_fulfillment","pending_refund.created.shipping.partial","pending_refund.created.shipping.partial.has_fulfillment","pending_refund.created.shipping.partial.no_fulfillment","pending_refund.created.subscription_renewal","pending_refund.created.subscription_renewal.full","pending_refund.created.subscription_renewal.partial","pending_refund.created.tax","pending_refund.created.tax.full","pending_refund.created.tax.partial","product.created","product.deleted","product.updated","product_sale.created","sale.created","sale.created.failed","sale.created.failed.declined","sale.created.failed.error","sale.created.failed.no_gateway","sale.created.failed.fraud_detected","sale.created.failed.merchant_error","sale.created.failed.merchant_hold","sale.created.success","sale.created.success.has_salvage","sale.created.success.is_upsell","sale.created.success.paid","sale.created.success.paid.has_salvage","sale.created.success.paid.is_upsell","sale.created.success.pending","sale.created.success.pending.is_upsell","sale.updated.fraud_alert.added","sale.updated.fraud_alert.removed","salvage_transaction.created","salvage_transaction.updated.processed","salvage_transaction.updated.processed.failed","salvage_transaction.updated.processed.success","sentinel.alert","sentinel.alert.fraud_detected","sentinel.alert.firewall_block","shipping.created","shipping.created.has_fulfillment","shipping.created.no_fulfillment","shipping.updated.delivered","shipping.updated.ship_to","shipping.updated.shipped","subscription.created","subscription.updated.renewed","subscription.updated.renewed.failed","subscription.updated.renewed.success","subscription.updated.status","subscription.updated.status.active","subscription.updated.status.cancelled","subscription.updated.status.occurrence_limit","subscription.updated.status.overdue","subscription.updated.status.suspended","subscription_renewal.updated.failed","subscription_renewal.updated.success","tax.created","transaction.created","trial.created","trial.updated.cancelled","trial.updated.expired","trial.updated.expired.failed","trial.updated.expired.success","trial.updated.extended","trial.updated.shortened"]},"delay_enabled":{"type":"boolean","description":"Whether to set a delay before the AI Voice Agent makes the outbound call. Useful when you may want to give the customer time to checkout after a failed sale before calling them, for example."},"time_value":{"type":"integer","description":"The value for the time unit if the delay is enabled for the account event trigger."},"time_unit":{"type":"string","description":"The unit of time if the delay is enabled for the account event trigger.","enum":["minutes","hours","days"]},"filters":{"additionalProperties":false,"type":"object","description":"If the trigger is 'account_event', you have the ability to filter the items that trigger the agent based on certain criteria. For example, you may only want to trigger the agent for an item from a specific campaign.","properties":{"campaign_filter":{"type":"array","description":"To filter items that trigger based on one or more associated campaigns.","items":{"type":"string","title":"Campaign ID","description":"A 20 character campaign ID.","minLength":20,"maxLength":20}},"status_filter":{"type":"array","description":"To filter items that trigger based on one or more associated statuses. The available statuses to filter by depend on the account event notation used, i.e. the item type. The first word in the account event notation determines the item type. For example, if the account event notation starts with 'sale', then the available statuses to filter by would be the sale statuses.","items":{"type":"string"}},"metadata_filter":{"type":"array","description":"To filter items that trigger based on one or more associated metadata. Will only trigger for items that have metadata matching all of the specified metadata name and value pairs.","items":{"additionalProperties":false,"required":["name","value"],"properties":{"name":{"type":"string","description":"The metadata name which must be present in an item's metadata along with a matching value."},"value":{"type":"string","description":"The metadata value associated with the metadata name."}},"type":"object"}}}},"filter_function":{"type":"string","description":"A filter function allows you to further refine whether or not the voice agent is triggered based on an account event details. You can use a filter function to parse the specific accountevent details and determine whether the agent should be triggered. A filter function must respond with a string value of either 'pass' or 'fail'. The filter function must be created with an event_source of 'api_direct' in order to be accessible. Read more about using a filter function <a href=\"https://kb.revcent.com/en/tools/ai/voice-agents#filter-function\" target=\"_blank\">here</a>. To remove a filter function submit an empty string for this value.","minLength":0,"maxLength":20}},"type":"object","description":"If the trigger is account_event there are additional settings that can be configured including filtering specific events from using the agent."},"limits":{"additionalProperties":false,"type":"object","description":"The maximum number of times the agent can be triggered for the same item. Read more at https://kb.revcent.com/en/tools/ai/voice-agents#max-runs-per-item","properties":{"max_calls_per_item":{"type":"integer","description":"The maximum number of calls per item. Highly recommended set to 1 to prevent multiple calls for the same item within same events."},"min_time_value":{"type":"integer","description":"If max_calls_per_item is greater than 1, the value for the time unit that must transpire between runs for the same item."},"min_time_unit":{"type":"string","description":"If max_calls_per_item is greater than 1, the unit of time that must transpire between runs for the same item.","enum":["hours","days"]}}}}}},"type":"object","description":"The AI Voice agent settings."},"third_party_integration_ai":{"type":"string","description":"The third-party integration for the realtime voice model. Must be a previously created user third party integration with the OpenAI site integration, using the model 'gpt-realtime-*'. At this time, only OpenAI with the model 'gpt-realtime-*' is supported third_party_integration_ai for AI Voice Agents.","minLength":20,"maxLength":20},"third_party_integration_voice":{"type":"string","description":"The third-party integration for voice phone calls. Must be a previously created user third party integration with the Twilio site integration, along with a selected Twilio phone number the AI Voice Agent will use. At this time, only Twilio is supported as the site integration for a third party integration voice.","minLength":20,"maxLength":20}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"API call response code.","type":"integer","format":"int32","enum":[1]},"ai_voice_agent_id":{"type":"string","title":"AI Voice Agent ID","description":"A 20 character AI Voice Agent ID.","minLength":20,"maxLength":20},"result":{"type":"string"}},"type":"object","additionalProperties":false}}},"description":"Successful response."},"default":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"This value indicates that there is an error. Will always be 0.","type":"integer","enum":[0]},"error_code":{"description":"The specific error code.","type":"string"},"message":{"description":"A human readable description of the error.","type":"string"},"result":{"description":"A description of the API call result.","type":"string"}},"title":"APIStandardErrors","type":"object","additionalProperties":false}}},"description":"Error response."}}}