{"method":"GET","path":"https://api.revcent.com/v2/ai_assistants/{ai_assistant_id}","summary":"Get An AI Assistant","description":"Retrieve the details of a specific AI Assistant.","operationId":"GetAIAssistant","parameters":[{"in":"path","name":"ai_assistant_id","description":"The AI Assistant ID.","required":true,"schema":{"type":"string","title":"AI Assistant ID","description":"A 20 character AI Assistant ID.","minLength":20,"maxLength":20}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"additionalProperties":false,"properties":{},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"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":"The API call response code, 1 = Success","type":"integer","enum":[1]}},"title":"APICallResponseInfo","type":"object","additionalProperties":false},{"type":"object","additionalProperties":false,"properties":{"created_date_unix":{"description":"The unix timestamp of when the item was created.","type":"integer","format":"unix-time"},"id":{"type":"string","title":"AI Assistant ID","description":"A 20 character AI Assistant ID.","minLength":20,"maxLength":20},"name":{"type":"string","description":"The AI Assistant name."},"description":{"type":"string","description":"The AI Assistant description."},"enabled":{"type":"boolean","description":"Whether the AI Assistant is enabled."},"settings":{"type":"object","description":"The settings for the AI Assistant.","additionalProperties":false,"properties":{"assistant_instructions":{"type":"string","description":"The instructions for the AI Assistant. These are the base instructions that will be provided to the AI model with every AI Thread associated with the AI Assistant. Useful for setting the overall behavior of the assistant and not for actual actions to perform. Do not include instructions for specific actions to perform in the assistant instructions."},"assistant_limits":{"type":"object","description":"The limits for the AI Assistant. These limits will apply to all AI Threads associated with the AI Assistant.","additionalProperties":false,"properties":{"thread_max_tokens":{"type":"integer","description":"The maximum number of tokens that an AI Thread associated with the AI Assistant can consume before the thread is automatically stopped. Useful for preventing excessively long threads that consume a large number of tokens. 0 means no limit. Default is 0."},"token_max_per_day":{"type":"integer","description":"The maximum number of tokens that an AI Assistant can consume in a 24 hour period. Useful for preventing excessive usage. 0 means no limit. Default is 0."}}},"trigger_settings":{"type":"object","description":"The trigger settings for the AI Assistant.","additionalProperties":false,"properties":{"trigger":{"type":"string","description":"The event that triggers the AI Assistant. An AI Assistant can be triggered by an account event, on demand via API, or on a schedule determined by a valid 5 part cron expression.\nOptions:\n'account_event': The AI Assistant is triggered when a specific event occurs within your RevCent account.\n'on_demand': The AI Assistant is triggered either via API, Web App or as a System Tool within another AI Assistants' thread.\n'schedule': The AI Assistant is triggered on a fixed schedule.","enum":["account_event","schedule","on_demand"]},"account_event":{"additionalProperties":false,"type":"object","description":"If the trigger is account_event there are additional settings that can be configured including filtering specific events from using the assistant.","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"]},"filters":{"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,"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":"object","additionalProperties":false,"description":"A filter function allows you to further refine whether or not the AI Assistant is triggered based on an account event details. You can use a filter function to parse the specific account event details and determine whether the AI Assistant 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/assistants#filter-function\" target=\"_blank\">here</a>.","properties":{"id":{"type":"string","title":"Function ID","description":"A 20 character Function ID.","minLength":20,"maxLength":20},"name":{"type":"string","description":"The filter function name."}}},"delay":{"type":"object","description":"The delay settings for the account event trigger. This determines how long after the account event occurs that the AI Assistant will be triggered. By default, the AI Assistant will be triggered 1 minute after the account event occurs, but a delay can be set in order to wait for other related events to occur.","additionalProperties":false,"properties":{"time_value":{"type":"integer","description":"The value of the time delay."},"time_unit":{"type":"string","description":"The unit of time for the delay.","enum":["minutes","hours","days"]}}},"limits":{"additionalProperties":false,"type":"object","description":"The limits for the account event trigger. These limits only apply to account event triggers and determine the maximum number of times the assistant can be triggered for the same item.","properties":{"max_run_count":{"type":"integer","description":"The maximum number of runs per item. Highly recommended set to 1 to prevent multiple runs for the same item within same events."},"min_time_value":{"type":"integer","description":"If max_run_count 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_run_count is greater than 1, the unit of time that must transpire between runs for the same item.","enum":["hours","days"]}}}}},"schedule":{"additionalProperties":false,"type":"object","description":"If the trigger is schedule, the cron expression that determines when the AI Assistant will be triggered. The cron expression must be a valid 5 part cron expression.","properties":{"cron_expression":{"type":"string","description":"The cron expression that determines when the AI Assistant will be triggered. The cron expression must be a valid 5 part cron expression."},"cron_timezone":{"type":"string","description":"The timezone for the cron expression. If not provided, UTC will be used. The timezone must be a valid IANA timezone string."}}}}}}},"flow":{"type":"array","description":"The flow for the AI Assistant. The flow is an array of nodes that the AI Assistant will go through when triggered. Each node has a type and content. The type determines the kind of node it is and the content provides the necessary information for that node. Inputs and outputs determine the flow, i.e. connecting nodes via node ID's.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique identifier for the node within the flow. Nodes are connected via their IDs within the inputs and outputs properties of the node, and thus should not share the same ID."},"type":{"type":"string","description":"The type of node in the flow.","enum":["start_thread","action_step","action_branch","action_time_delay","action_end_thread"]},"inputs":{"type":"object","description":"The input into the node from other nodes. This determines the previous node in the flow that lead to this node. The start_thread type node does not have any inputs. Note: a nodes' input can only connect one other nodes' output. Multiple other nodes connecting to the same node output is not allowed.","additionalProperties":false,"properties":{"input_1":{"type":"object","description":"The input into the node which can only connect from a single other node.","properties":{"connections":{"type":"array","description":"The node that connects to input_1. Note: The start_thread type node does not have an input, thus leave empty for a start_thread node.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to input_1."},"input":{"type":"string","description":"The output from the prior node that connects to input_1. Note: only node type 'action_branch' has output_2, output_3 and output_4.","enum":["output_1","output_2","output_3","output_4"]}}},"minItems":0,"maxItems":1}}}}},"outputs":{"oneOf":[{"type":"object","description":"The single output_1 for node types: start_thread, action_step, action_time_delay. These determine the next node in the flow that follow the current node. Note: a node output can only connect to one other node. Multiple nodes connecting from a single output is not allowed. The action_end_thread node type does not have any outputs as it is the last node that will run if reached.","additionalProperties":false,"properties":{"output_1":{"type":"object","description":"The output_1. Note: Only 1 connection from output_1 is allowed to another node.","properties":{"connections":{"type":"array","description":"The node that connects to output_1.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to output_1."},"output":{"type":"string","description":"The input of the node that connects to output_1.","enum":["input_1"]}}},"minItems":0,"maxItems":1}}}}},{"type":"object","description":"The mutiple outputs for the action_branch node. These determine the next node in the flow that follow the current node based on the conditional branch statements. Note: a node output can only connect to one other node. Multiple nodes connecting from a single output is not allowed.","additionalProperties":false,"properties":{"output_1":{"type":"object","description":"The output_1, taken if the node settings output_1_message is considered true. Note: Only 1 connection from output_1 is allowed to another node.","properties":{"connections":{"type":"array","description":"The node that connects to output_1.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to output_1."},"output":{"type":"string","description":"The input of the node that connects to output_1.","enum":["input_1"]}}},"minItems":0,"maxItems":1}}},"output_2":{"type":"object","description":"The output_2, taken if the node settings output_2_message is considered true. Only 1 connection from output_2 is allowed to another node.","properties":{"connections":{"type":"array","description":"The node that connects to output_2.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to output_2."},"output":{"type":"string","description":"The input of the node that connects to output_2.","enum":["input_1"]}}},"minItems":0,"maxItems":1}}},"output_3":{"type":"object","description":"The output_3, taken if the node settings output_3_message is considered true. Only 1 connection from output_3 is allowed to another node.","properties":{"connections":{"type":"array","description":"The node that connects to output_3.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to output_3."},"output":{"type":"string","description":"The input of the node that connects to output_3.","enum":["input_1"]}}},"minItems":0,"maxItems":1}}},"output_4":{"type":"object","description":"The output_4. Output 4 is used if no conditions for the other outputs are met in an action_branch node, effectively acting as the 'else' branch. Only 1 connection from output_4 is allowed to another node.","properties":{"connections":{"type":"array","description":"The node that connects to output_4.","items":{"type":"object","additionalProperties":false,"properties":{"node":{"type":"string","description":"The unique identifier of the node that connects to output_4."},"output":{"type":"string","description":"The input of the node that connects to output_4.","enum":["input_1"]}}},"minItems":0,"maxItems":1}}}}}],"description":"The outputs from the node. These determine the next nodes in the flow that follow this node."},"position":{"type":"object","description":"The position of the node in the flow diagram. This is used for visual representation of the flow and does not affect the functionality of the flow. The position values are in pixels, and are represented in the UI when viewing the flow in the RevCent web app. If not present a default value is given. However, if able to be provided, it is recommended to provide position values to ensure the flow diagram is organized and visually easy to follow when viewing the flow in the UI. Note: each node is approximately 300px in width, and 400px in height when viewing in the UI.","additionalProperties":false,"properties":{"x_axis":{"type":"integer","description":"The horizontal x-axis position in pixels of the node in the flow diagram. Note: each node is approximately 300px in width, and 400px in height when viewing in the UI."},"y_axis":{"type":"integer","description":"The vertical y-axis position in pixels of the node in the flow diagram. Note: each node is approximately 300px in width, and 400px in height when viewing in the UI."}}},"node_settings":{"oneOf":[{"type":"object","description":"The settings for an AI Assistant flow node of type 'action_step'.","additionalProperties":false,"properties":{"step_message":{"type":"string","description":"Applies to an 'action_step' node. The message that will be sent to the AI."}},"required":["step_message"]},{"type":"object","description":"The settings for an AI Assistant flow node of type 'action_branch'. This is treated as an if > else if > else statement. The messages are sent to the AI and the AI determines which branch condition is met and thus which output to go down. If no conditions are met, output_4 is used.","additionalProperties":false,"properties":{"output_1_message":{"type":"string","description":"Applies to an 'action_branch' node. The message that will be sent to the AI to determine if the branch condition is met for output 1."},"output_2_message":{"type":"string","description":"Applies to an 'action_branch' node. The message that will be sent to the AI to determine if the branch condition is met for output 2. Optional, if empty or not provided then the branch will only evaluate for output 1"},"output_3_message":{"type":"string","description":"Applies to an 'action_branch' node. The message that will be sent to the AI to determine if the branch condition is met for output 3. Optional, if empty or not provided then the branch will only evaluate for output 1 and 2."}},"required":["output_1_message"]},{"type":"object","description":"The settings for an AI Assistant flow node of type 'action_time_delay'. This node causes a delay in the flow for a specified amount of time before proceeding to other nodes via output_1.","additionalProperties":false,"properties":{"time_unit":{"type":"string","description":"The unit of time for the time delay.","enum":["minutes","hours","days"]},"time_value":{"type":"string","description":"The integer value of the time delay as a string."}},"required":["time_unit","time_value"]}],"description":"The settings for the node based on the node type. Only applicable for 'action_step', 'action_branch', and 'action_time_delay' node types."}}}},"third_party_integration":{"title":"Third Party Integration","type":"object","additionalProperties":false,"description":"The third party AI integration related to the item.","properties":{"id":{"type":"string","description":"A 20 character user third party integration ID.","minLength":20,"maxLength":20},"name":{"title":"User Integration Name","type":"string","description":"The user named third party integration."},"third_party":{"type":"object","description":"Site third party integration, related to the user third party integration.","additionalProperties":false,"properties":{"id":{"type":"string","description":"A 20 character system third party integration ID.","minLength":20,"maxLength":20},"name":{"title":"Site Third Party Integration Name","type":"string","description":"The RevCent named site third party integration."}}}}},"updated_date_unix":{"description":"The unix timestamp of when the item was last updated.","type":"integer","format":"unix-time"}}}]}}},"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."}}}